Fieldmotion API Getting started

Departments

Create a department

POST /a/Department_new

Create a uniquely named department through the administrator-only legacy workflow.

When to use this endpoint

Use Department_new for CRM1 department creation and import flows that must reuse an existing exact-name row instead of creating a duplicate.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session, and the acting user must be a client administrator.

The validation of name occurs before authentication. A valid name from a non-administrator returns {"error":"not an admin"}.

Parameters

ParameterTypeRequiredDescription
nameStringYesTrimmed department name. It must remain nonempty; there is no explicit length limit. Exact duplicates are reused.

Example request

$created = FM_api('Department_new', [
	'name' => 'North region',
]);

Example response

{
  "ok": 1,
  "id": 42
}

If the exact stored name already exists, the response is {"id":42,"warning":"that department already exists"} and no row is inserted.

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: name"}The name is absent, blank, or only whitespace.
{"error":"not an admin"}The authenticated user is not a client administrator.

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

Behaviour and edge cases

  • Whitespace at both ends is removed before lookup and storage. The exact-name lookup follows the tenant table’s binary collation, so case variants can be distinct.
  • New rows receive current cdate and last_edited datetimes plus an empty users string. Other columns use schema defaults.
  • There is no filtering or pagination; one lookup and at most one insert occur.

Side effects

  • Inserts one department and invalidates the departments cache when no exact duplicate exists.
  • Does not write generic field history or create reciprocal user/asset/customer links.

See it in Fieldmotion

CRM1

Open Users → Departments and choose Create. Customer and user import/update paths also call this route when a supplied department name does not already exist.

CRM2

CRM2’s shared Departments creator uses Department_createData; it does not call this focused route.

Related endpoints