Fieldmotion API Getting started

Departments

Set department users

POST /a/Department_setUsers

Replace a department’s user-ID list and mirror additions/removals into tenant user membership fields.

When to use this endpoint

Use Department_setUsers for the CRM1 Departments page’s user picker. It is the focused legacy route that attempts reciprocal membership updates.

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
idInteger stringYesDepartment ID after integer conversion; zero is rejected, but row existence is not checked.
valsStringYesComma-separated IDs or JSON-looking numeric array text. Non-digit/non-comma characters are stripped. Use truthy text [] to clear the department list.

Example request

$result = FM_api('Department_setUsers', [
	'id' => '42',
	'vals' => '[18,24]',
]);

Example response

{
  "ok": 1
}

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":"no id parameter"}The ID is absent or integer-converts to zero.
{"error":"missing or invalid parameter: vals"}vals is absent or PHP-false-like. The handler reads it before this check, so a missing value can also emit a runtime warning.
Runtime warning or type errorvals is a native array rather than text.

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 tenant users whose parent matches the current tenant are changed. Missing user IDs remain in the department’s list but have no reciprocal row update.
  • New user memberships avoid appending the department when its loose value is already present; removed memberships use a comma-boundary regular expression.
  • The department’s stored list is the sanitized IDs joined by commas. Duplicates are not removed.

Side effects

  • Updates added/removed users’ departments, last_edited, and edited_uuid. Only removals explicitly invalidate the legacy employees cache.
  • Replaces the department’s users string without advancing its last_edited, invalidating its cache, or writing audit history.

See it in Fieldmotion

CRM1

Open Users → Departments and edit the Users cell. CRM1 serializes the selected numeric IDs into vals.

CRM2

CRM2 updates the mapped users field through Department_updateData, whose reciprocal logic understands both comma and JSON list forms.

Related endpoints