Fieldmotion API Getting started

Departments

Retrieve selected department fields

POST /a/Department_getRequestedDetails

Retrieve selected department fields through CRM2’s shared field map, with exact mapped filters and optional ordering.

When to use this endpoint

Use Department_getRequestedDetails for CRM2 selectors, detail cards, and cached named-field lookups. It returns an array even when one ID is requested.

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
fieldsNative arrayNoMapped keys to return: id, name, meta, users, lastEdited, cdate, assets, customers, and metaCustomerTypes. Omission requests all keys; unknown keys are ignored and id is always selected internally.
id / idsInteger string or native arrayNoOptional ID filter. Scalars are integer-converted; arrays are integer-converted element by element. JSON array text is not decoded.
Mapped field filtersScalar or native arrayNoText, JSON, and datetime values use case-insensitive exact matching; integer fields use numeric equality. Arrays become IN filters.
orderMapped name/object or native arrayNoOrder fields such as name, or objects such as {"id":"name","dir":"desc"}. Unknown fields are ignored.
advanceSearchNative arrayNoShared CRM2 advanced-search conditions over mapped fields.

Example request

$rows = FM_api('Department_getRequestedDetails', [
	'id' => '42',
	'fields' => ['id', 'name', 'metaCustomerTypes'],
]);

Example response

[
  {"id": "42", "name": "North region", "metaCustomerTypes": ["3", "7"]}
]

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.
[]No row matches, an ID array is empty, or valid filters select nothing.
Runtime warning or type errorfields, order, or another array option is supplied in 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

  • No ID is required. With no filters, every tenant department is returned; there is no pagination or endpoint limit.
  • metaCustomerTypes is extracted and decoded from meta.customer_types; the top-level meta, users, assets, and customers values remain stored strings.
  • Duplicate IDs do not duplicate rows. Ordering is absent unless order is supplied.

See it in Fieldmotion

CRM1

CRM1 does not directly call this route; its legacy pages use Department_get, Departments_getNames, and Departments_getDT.

CRM2

Department pickers and configurable pages across users, assets, forms, reporting, and history call this mapped reader, usually requesting id and name.

Related endpoints