Create a mapped department · Fieldmotion API

When to use this endpoint

Use Department_createData for the CRM2 Departments screen’s shared create workflow. Use Department_new when administrator enforcement, trimmed names, and duplicate detection are required.

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

Parameter	Type	Required	Description
`name`	String	No	Stored verbatim. Blank and duplicate names are accepted and there is no endpoint length check.
`meta`	JSON value or JSON text	No	Complete value for the legacy text-backed metadata column. Strings are not checked for valid JSON.
`metaCustomerTypes`	Value or native array	No	Writes `meta.customer_types`. A native array is JSON-encoded; this can be supplied with `meta`, in which case the nested value is applied to that object.
`users`	String or native array	No	Stored user-membership value. Omission is forced to an empty string; a native array is JSON-encoded. No user rows are synchronized by this create route.
`assets / customers`	String or native array	No	Legacy membership columns. Native arrays are JSON-encoded; related asset/customer rows are not synchronized.
`cdate`	Datetime string	No	Stored creation datetime. Blank becomes SQL `null`; omission leaves the schema default (`null`).
`lastEdited`	Datetime string	No	Stored `last_edited`. Omission sets the server’s current datetime.
`id`	Any	No	Ignored during creation even though it appears in the shared map.

Example request

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

Example response

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

Errors and unusual responses

Response	Condition
`{"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 parameters."}`	No writable mapped value is accepted. In normal use this is avoided because the handler supplies `users=""`.

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

Behaviour and edge cases

Memberships are not made reciprocal. Supplying users, assets, or customers only writes the department row. It does not update the corresponding membership columns on those records.

Unknown keys are ignored. At least the handler-supplied empty users value is inserted, so an otherwise empty request can create an unnamed department.
The route performs no duplicate-name, administrator, filtering, or pagination logic.
last_edited defaults to the current server datetime, while cdate remains null unless supplied.

Side effects

Inserts one tenant departments row, advances the departments cache marker, and writes generic audit entries for accepted mapped fields.
Does not create user, asset, customer, order, or job links.

See it in Fieldmotion

CRM1

CRM1’s Departments screen creates rows with Department_new, not this route.

CRM2

Open Users → Departments and create a row. The shared display widget derives Department_createData from its singular API prefix.

Related endpoints

Department_new is the administrator-only focused creator.
Department_updateData updates mapped fields and partly synchronizes user memberships.