Fieldmotion API Getting started

Departments

Retrieve departments by ID

POST /a/Departments_getById

Fetch selected raw columns for a batch of department IDs, as used by object caches and exports.

When to use this endpoint

Use Departments_getById after another workflow has supplied department IDs and a compact batch lookup is needed.

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
idsJSON array or native arrayYesIDs are integer-converted and deduplicated; 0 is retained. A scalar or malformed decoded value is not promoted to a list.
fieldsJSON array stringNoAny of id, name, last_edited, and cdate. Omission selects all four. Unlike ids, a native array is not accepted here.

Example request

$rows = FM_api('Departments_getById', [
	'ids' => json_encode(['42', '43']),
	'fields' => json_encode(['id', 'name']),
]);

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.
{"error":"missing or invalid parameter: ids"}The ids key is absent.
{"error":"no ids in list"}The supplied/decoded list is empty.
{"error":"no fields selected"}fields contains no allowed field.
Runtime warning or type errorids is malformed/non-array JSON, or fields is a native array/non-array JSON value.

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

Behaviour and edge cases

  • Missing IDs are silently omitted. There are no null placeholders, pagination, or endpoint maximum.
  • The SQL query defines no ordering; do not assume rows follow the input ID sequence.
  • The handler closes the PHP session before querying so parallel requests are not held behind its session lock.

See it in Fieldmotion

CRM1

Department object caching and CSV export translation call this route, normally requesting id and name.

CRM2

The CRM2 cache and export widgets use the same batch lookup for department labels.

Related endpoints