List customer types by department

When to use this endpoint

Use CustomerTypes_listByDepartment when presenting the Customer edit form’s type selector and its department/transition restrictions.

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
`id`	Integer string	No	Current customer-type ID, not a customer ID. A configured `allowed_next` value changes how the result is built.
`dept_id`	Integer string	No	Department ID. If its decoded metadata contains a nonempty `customer_types` array/value, candidates are restricted to those IDs. Missing departments or empty/invalid metadata impose no restriction.

Example request

$choices = FM_api('CustomerTypes_listByDepartment', [
	'id' => '12',
	'dept_id' => '4',
]);

Example response

[
  {"id": "12", "name": "Commercial", "allowed_next": "12,13"},
  {"id": "13", "name": "Residential"}
]

When transition rules are active, the current type is deliberately first and is the only row that includes allowed_next; eligible alternatives follow in name order.

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.
`Database/query error rather than a stable API error`	Stored `allowed_next` or department `customer_types` metadata is malformed for direct use as an SQL ID list.

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

Behaviour and edge cases

A blank transition list means unrestricted, not no transitions. If the current row has blank allowed_next, the endpoint discards the special current-row branch and returns every department-allowed type in name order.

With a nonblank transition list, the current type remains the first choice even if the department metadata does not include it. Alternative rows must be in both the transition list and department list, and the current ID is excluded from alternatives.
Without a usable current ID, all department-allowed types are returned as id/name rows in name order.
There is no pagination. The only tenant configuration consulted is the department’s meta.customer_types value.

See it in Fieldmotion

CRM1

Edit a customer and change its department or type. CRM1 reloads the allowed type choices with this endpoint.

CRM2

Customer edit screens also use this endpoint where the department-aware selector is enabled.

Related endpoints

CustomerType_save writes allowed_next.
CustomerTypes_list lists types without department/transition restrictions.