Fieldmotion API Getting started

Job types

Update one job-type field

POST /a/JobType_updateField

Replace one mapped job-type field across one or several explicit IDs.

When to use this endpoint

Use JobType_updateField only for low-level mapped inline or bulk editing. No production CRM1 or CRM2 caller was found during this investigation.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

ParameterTypeRequiredDescription
fieldStringYesOne of id, name, priority, lastEdited, notes, meta, archived, nominalCode, taxSettings, department, metaFormID, metaSendNotification, metaNotificationEmail, or metaOrderNum.
valMixedYesComplete replacement value. Numeric fields are integer-converted; arrays/objects for JSON-compatible values are encoded by the shared helper. Focused business validation is not applied.
idInteger string or native arrayConditionallyOne target or an already-decoded ID array. Supply id or ids; id takes precedence.
idsInteger string or native arrayConditionallyAlternative target(s). All values are integer-converted. JSON array text is not decoded.

Example request

$updated = FM_api('JobType_updateField', [
	'ids' => ['42', '43'],
	'field' => 'archived',
	'val' => '1',
]);

Example response

{
  "ok": 1,
  "oldData": [
    {"id": "42", "archived": "0"},
    {"id": "43", "archived": "0"}
  ]
}

For a named metadata subfield, each oldData row contains the complete raw meta column rather than only that subfield.

When no matched row needs a change, the response is {"ok":"1","warning":"no change required"} and oldData is omitted.

Errors and unusual responses

ResponseCondition
{"error":"not logged in"}No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
{"error":"missing or invalid parameter: field"}field is absent.
{"error":"missing or invalid parameter: val"}val is absent or null.
{"error":"missing or invalid field"}The field is not in the Job Type map.
{"error":"missing or invalid parameter: id/ids"}Neither target key is supplied.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • Missing target rows are silently omitted; if every target is missing, the no-change success response is returned.
  • Changing an ordinary mapped field also advances last_edited. Passing field=lastEdited does not preserve the supplied value because current server time is appended to the same update.
  • The route does not enforce archive, priority, notification, email, form, department, nominal, metadata, or name business rules.
  • There is no filtering or pagination beyond the explicit IDs.

Side effects

  • Changed rows advance the job-type cache marker and produce one generic audit entry naming the mapped field and target IDs.
  • Unlike JobType_updateData, this route does not scan notes for mentions. Existing jobs are not rewritten.

See it in Fieldmotion

CRM1

A production-source search found no direct CRM1 caller.

CRM2

A production-source search found no direct CRM2 caller; the configurable editor uses JobType_updateData.

Related endpoints