Fieldmotion API Getting started

Departments

List department names

POST /a/Departments_getNames

Return department ID/name pairs sorted by name, optionally restricted to native-array IDs.

When to use this endpoint

Use Departments_getNames to populate department selectors or resolve a known native list of IDs to display names.

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
idsNative arrayNoOptional IDs, integer-converted before the SQL IN filter. JSON array text is not decoded.

Example request

$names = FM_api('Departments_getNames', [
	'ids' => ['42', '43'],
]);

Example response

[
  {"id": "42", "name": "North region"},
  {"id": "43", "name": "South region"}
]

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.
Runtime warning or type errorids is present but is not a native array.
Database-dependent false/errorAn empty native ID array produces an invalid empty IN list rather than returning early.

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

Behaviour and edge cases

  • Omitting ids returns every tenant department. Missing requested IDs are silently omitted.
  • Rows are ordered by the database name collation. Duplicate input IDs do not duplicate result rows.
  • There is no search, pagination, endpoint maximum, archive filter, or additional permission check.
  • The handler closes the PHP session before querying.

See it in Fieldmotion

CRM1

Department selectors throughout jobs, users, customers, assets, forms, calendars, reports, and target pickers call this route.

CRM2

Most CRM2 pickers use Department_getRequestedDetails, though some job/form screens still call this lightweight route.

Related endpoints