Fieldmotion API Getting started

Customers

Set a customer department

POST /a/Customer_setDepartmentId

Assign one customer to a tenant department or clear its department assignment.

When to use this endpoint

Use Customer_setDepartmentId when a caller has obtained a department ID from tenant configuration and needs a focused assignment change.

Send zero to clear the assignment. This endpoint does not apply customer-type department restrictions enforced by some user interfaces.

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 stringYesCustomer ID. Presence is checked, but zero and other integer conversions proceed to lookup and then return “customer does not exist”.
department_idInteger stringYesExisting tenant department ID, or 0 to clear. Blank converts to zero.

Example request

$result = FM_api('Customer_setDepartmentId', [
	'id' => '1088',
	'department_id' => '7',
]);

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 supplied"}id is omitted.
{"error":"missing or invalid parameter: department_id"}department_id is omitted.
{"error":"customer does not exist"}No customer row matches the converted ID.
{"error":"department_id already set to new value"}The converted value already matches the stored assignment; this no-change case is an error, not success.
{"error":"that department does not exist"}A nonzero department ID does not exist in the tenant.

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

Behaviour and edge cases

  • The customer and department lookups do not filter active or deleted rows.
  • Any supplied value is converted with intval; zero clears the department and bypasses department lookup.
  • The endpoint verifies that a nonzero department exists but does not verify that it is allowed for the customer’s type.
  • This is a single-record mutation; it provides no list filtering or pagination.

Side effects

  • The customer write updates department_id, last_edited, and edited_uuid. It does not explicitly invalidate the customer cache or fire Customer_edit.
  • A customer_changes row labelled department records the old and new values after the write, and a customer audit event is written. The operations are not transactional.

See it in Fieldmotion

CRM1

The legacy customer edit popup and Customers table call Customer_setDepartmentId when the department selection changes; customer create/edit workflows also use the same handler internally.

CRM2

CRM2 exposes department in its customer layout editor, but no direct production call to this focused endpoint was found.

Related endpoints