Fieldmotion API Getting started

Departments

List departments

POST /a/Departments_list

List all departments or those edited in an open time window, with a small raw-field allowlist.

When to use this endpoint

Use Departments_list for lightweight synchronization/list workflows that need more than ID/name or a last_edited lower bound.

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
last_editedDatetime stringNoStrict lower bound. The query also adds a strict upper bound using the server’s current datetime. Input is interpolated as escaped text and not date-validated.
fieldsJSON array or native arrayNoAdditional fields from meta, users, last_edited, cdate, assets, and customers. id/name are always selected. The legacy allowlist also accepts nonexistent email; skills is recognized but not returned.

Example request

$rows = FM_api('Departments_list', [
	'fields' => ['last_edited', 'users'],
	'last_edited' => '2026-09-01 00:00:00',
]);

Example response

[
  {"id":"42","name":"North region","last_edited":"2026-09-25 10:30:00","users":"18,24"}
]

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.
false or database errorThe accepted legacy field email is requested; that column does not exist in the department schema.
Runtime warning or type errorMalformed JSON for fields produces an unsupported decoded shape in downstream handling.

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 edit window is last_edited > supplied value AND last_edited < server now; rows exactly on either boundary and null timestamps are excluded.
  • Unknown fields are ignored, requested duplicates are not removed from the SQL selection, and raw JSON/membership values remain strings.
  • There is no ordering, pagination, endpoint maximum, deleted-state filter, or additional permission gate.

See it in Fieldmotion

CRM1

The Job Types settings page uses this list to populate department-related configuration.

CRM2

No direct CRM2 caller was found; CRM2 uses mapped department readers.

Related endpoints