Update department mapped fields

When to use this endpoint

Use Department_updateData for CRM2’s shared Departments editor. It supports scalar or bulk IDs, but reciprocal user processing is reliable only for a single department ID.

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`	Integer string or native array	Yes	Target department ID or native list of IDs. JSON array text is not decoded. Bulk mode discards per-row warnings/errors.
`name / users / assets / customers`	String or native array	No	Complete replacements for the mapped text columns. Native arrays are JSON-encoded. Only `users` receives reciprocal synchronization.
`meta`	JSON value or JSON text	No	Complete metadata replacement. Nonblank string input is not JSON-validated.
`metaCustomerTypes`	Value or native array	No	Replacement for `meta.customer_types`, preserving other decodable metadata keys.
`cdate / lastEdited`	Datetime strings	No	Mapped timestamps. Blank becomes SQL `null`; any successful field change automatically sets `last_edited` to the current server datetime.
`noRecord`	Native array	No	Internal audit control listing mapped keys whose generic history entries should be hidden.

Example request

$result = FM_api('Department_updateData', [
	'id' => '42',
	'name' => 'Northern region',
	'users' => ['18', '24'],
]);

Example response

{
  "ok": 1
}

A scalar no-op returns {"warning":"No Change."}; a missing row returns {"warning":"No data."}; supplying only unknown update keys returns {"warning":"no updated fields."}.

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: id"}`	`id` is absent and `users` is not being processed.
`{"error":"department does not exist"}`	`users` is present and the scalar ID does not resolve to a department.

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

Behaviour and edge cases

Only user membership is synchronized. Changing assets or customers does not update those records. Bulk IDs combined with users are unsafe because the pre-read integer-converts the array before the generic bulk loop.

User lists accept JSON text, comma-separated text, or a native array for membership comparison. Blank/invalid IDs and duplicates are removed for reciprocal processing, though the department stores the mapped input form.
Added/removed existing users receive a JSON-encoded departments list. Missing users are silently ignored and can remain in the department value.
Unknown keys are ignored. Scalar ID zero normally returns No data.; there is no explicit positive-ID or page-permission check.

Side effects

Updates the department, advances last_edited, invalidates the departments cache, and writes generic field-level audit history.
For changed users, updates reciprocal tenant user departments JSON and invalidates the users cache, but does not advance those users’ last_edited. The operations are not transactional.

See it in Fieldmotion

CRM1

CRM1 uses focused setters for department editing rather than this route.

CRM2

Open Users → Departments. The shared display widget uses this route for names, assets, customer-type metadata, and other mapped edits.

Related endpoints

Department_setUsers is the older comma-oriented user writer.
Department_updateField applies one mapped value to explicit IDs without reciprocal synchronization.