Fieldmotion API Getting started

Departments

Set department customer types

POST /a/Department_setCustomerTypes

Replace the customer-type list stored in a department’s metadata.

When to use this endpoint

Use Department_setCustomerTypes from the CRM1 Departments table to restrict which customer types are associated with a department.

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 row is read and updated only in the authenticated tenant.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesExisting department ID after integer conversion.
valJSON array stringYesNonempty decoded array stored at meta.customer_types. Despite the error wording, the implementation does not actually coerce or validate every item as an integer.

Example request

$result = FM_api('Department_setCustomerTypes', [
	'id' => '42',
	'val' => json_encode(['3', '7']),
]);

Example response

{
  "ok": 1
}

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":"no id supplied"}id is absent or integer-converts to zero.
{"error":"no val supplied"}val is absent or PHP-false-like.
{"error":"val should be a JSON-encoded array of integers"}The value is invalid JSON, decodes to a non-array, or decodes to an empty array.
{"error":"department does not exist"}No department has the converted ID.

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

Behaviour and edge cases

  • Existing metadata is decoded as an array; invalid, empty, or non-array metadata is replaced with an empty object before customer_types is assigned.
  • An empty list cannot be saved through this route, even though the CRM1 UI describes a blank list as allowing all customer types.
  • There is no customer-type existence check, filtering, or pagination.

Side effects

  • Replaces meta.customer_types and advances the department’s last_edited datetime.
  • Does not invalidate the departments cache or write generic audit history.

See it in Fieldmotion

CRM1

Open Users → Departments, edit Customer Types, and save a nonempty selection. CRM1 sends the selected IDs as JSON text.

CRM2

CRM2 edits metaCustomerTypes through Department_updateData, not this administrator-only route.

Related endpoints