Update one department field · Fieldmotion API

When to use this endpoint

Use Department_updateField for trusted bulk mapped-field updates. Prefer Department_updateData when changing user membership so reciprocal user rows are maintained.

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

Parameter	Type	Required	Description
`id / ids`	Integer string or native array	Yes	One target ID or a native array. `id` wins when both are present; values are integer-converted and missing rows are ignored.
`field`	Mapped key	Yes	One of `id`, `name`, `meta`, `users`, `lastEdited`, `cdate`, `assets`, `customers`, or `metaCustomerTypes`.
`val`	Scalar or native array	Yes	Replacement value. Native arrays/objects are JSON-encoded for quoted fields.

Example request

$result = FM_api('Department_updateField', [
	'ids' => ['42', '43'],
	'field' => 'name',
	'val' => 'Northern region',
]);

Example response

{
  "ok": 1,
  "oldData": [
    {"id": "42", "name": "North region"}
  ]
}

Errors and unusual responses

Response	Condition
`{"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; blank values are accepted when present.
`{"error":"missing or invalid field"}`	The field is not in the department map.
`{"error":"missing or invalid parameter: id/ids"}`	Neither ID parameter is present.

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

Behaviour and edge cases

Mapped relationship fields have no reciprocal handling. Writing users, assets, or customers changes only department rows. The map also permits changing the primary id; external integrations should never use that field.

If every matching row already has the value, or no IDs exist, the response is {"ok":"1","warning":"no change required"}. Note the string success value.
Changed rows receive current last_edited. Updating lastEdited itself is effectively overwritten by that automatic timestamp.
metaCustomerTypes updates only the nested JSON path per row; invalid prior metadata is normalized by the shared helper.

Side effects

Updates all changed matching rows, invalidates the departments cache, and writes one generic audit event covering the changed IDs.
Does not synchronize user/asset/customer membership or enforce administrator/page permissions.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found; CRM1 uses the focused department setters.

CRM2

The shared UI generally calls Department_updateData; this field-level route remains available for generic bulk actions.

Related endpoints

Department_updateData updates several mapped fields and synchronizes user membership.
Department_getRequestedDetails reads the same map.