Query mapped departments · Fieldmotion API

When to use this endpoint

Use Departments_getDataTable for CRM2’s configurable Departments table or another named-field query. It returns keyed objects rather than CRM1’s positional rows.

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
`fields`	Native array	Yes	Requested keys from `id`, `name`, `meta`, `users`, `lastEdited`, `cdate`, `assets`, `customers`, and `metaCustomerTypes`. Unknown keys are ignored and `id` is always returned.
`users`	Native array of objects	No	Each object’s `id` is joined into a raw regular expression against `main.users`. Empty/malformed entries can produce an empty pattern.
`assets / metaCustomerTypes`	Native arrays	No	Values are joined with `\|` into raw regular-expression filters against the stored asset text or metadata JSON text.
`isTable / draw / start / length`	Integer strings	No	Shared table controls. Table mode defaults on with offset `0`, length `10`, and draw `0`. Exact `isTable=0` removes counts/paging unless positive `limit` is supplied.
`orderBy / orderDesc / order`	Shared mapped ordering	No	Explicit named ordering or DataTables fallback ordering.
`searchValue / searchField`	String / mapped names	No	Case-insensitive substring search over selected/all mapped fields.
`Mapped filters / advanceSearch / groupBy`	Shared scalar/array controls	No	Generic mapped filters, advanced conditions, and grouping. Date-range controls also apply to `lastEdited` or `cdate`.

Example request

$page = FM_api('Departments_getDataTable', [
	'fields' => ['id', 'name', 'users', 'assets', 'metaCustomerTypes'],
	'start' => '0',
	'length' => '25',
	'draw' => '4',
]);

Example response

{
  "data": [
    {"id":"42","name":"North region","users":["18","24"],"assets":"51,52","metaCustomerTypes":"[\"3\"]","orders":[{"po_id":"91","status":"0"}]}
  ],
  "draw": 4,
  "recordsTotal": "8",
  "recordsFiltered": "8"
}

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: fields"}`	`fields` is absent.
`{"error":"error in database query"}`	A generated filter/order/grouping query fails.
`Runtime warning or type error`	A special filter or shared array parameter is supplied with an unsupported scalar shape.

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

Behaviour and edge cases

users is normalized after the query: valid stored JSON arrays are returned as arrays; otherwise the string is split on commas. Other membership/meta fields keep their selected representation.
Every returned row is enriched with all requisition/purchase orders targeting department type 5, even if orders was not requested. This causes two extra queries per row.
Table counts cover all departments/filtered rows. The table has no deleted state or implicit permission/department filter.

See it in Fieldmotion

CRM1

CRM1 uses Departments_getDT, not this route.

CRM2

Open Users → Departments. The shared data-table widget sends its visible fields, filters, ordering, and paging controls here.

Related endpoints

Departments_getDT serves the positional CRM1 table.
Department_getRequestedDetails provides unpaged mapped detail lookups.