Fieldmotion API Getting started

Departments

Find departments by name

POST /a/Departments_listByNames

Resolve an exact JSON list of department names to matching ID/name rows.

When to use this endpoint

Use Departments_listByNames during CSV import translation when source rows contain department names instead of IDs.

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
namesJSON array stringYesEvery decoded element must already be a string. Native arrays are not accepted because the handler always JSON-decodes the value.

Example request

$rows = FM_api('Departments_listByNames', [
	'names' => json_encode(['North region', 'South region']),
]);

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 parameter: names"}The key is absent.
{"error":"invalid parameter: names"}The JSON is invalid or does not decode to an array.
{"error":"invalid name string","name":1}An element is not a string; the rejected value is echoed in name.

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

Behaviour and edge cases

  • Matching uses SQL equality under the tenant table’s binary collation, so case and spacing must match stored names exactly.
  • An empty array becomes an IN ("") query and normally returns an empty list. Missing names are silently omitted.
  • The database defines result order; it need not match input order. Duplicate input names do not duplicate rows.
  • There is no partial matching, creation, pagination, or endpoint maximum.

See it in Fieldmotion

CRM1

The CSV import widget batches unique department names through this route before replacing matching cells with IDs.

CRM2

The CRM2 import widget performs the same exact-name translation and substitutes 0 when a name is absent.

Related endpoints