Set a customer state or region

When to use this endpoint

Use Customer_setState for a focused state or region correction on a known customer address.

Normalize whitespace in the caller because this endpoint compares one representation but stores another.

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	Yes	Customer to update; it must convert to a positive integer.
`val`	String	Yes	New state or region. A trimmed copy is compared and sent to address history, but the raw request string is stored. Present blank clears the field.

Example request

$result = FM_api('Customer_setState', [
	'id' => '1088',
	'val' => 'Northern Ireland',
]);

Example response

{
  "ok": 1
}

If the stored value equals the trimmed input, the response is {"ok":1,"msg":"no change needed"}.

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 parameter: id"}`	`id` is absent or invalid.
`{"error":"missing or invalid parameter: val"}`	`val` was omitted.
`{"error":"customer does not exist"}`	No matching customer row exists.

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

Behaviour and edge cases

Raw whitespace can be stored. The no-change check and history helper use trimmed val, while the final SQL update uses the original string. History and the current row can therefore differ. Helper errors are also ignored.

The lookup has no active/deleted filter.
The endpoint does not validate a state list or enforce a length limit.
Address-history work occurs before the final update and is not part of a shared transaction.
This is a single-record mutation; it provides no list filtering or pagination.

Side effects

Address_set can update history, clear linked non-deleted job and invoice customer-detail caches, and mark this customer and descendants as edited.
The final write updates state, last_edited, and edited_uuid, invalidates the customer cache, logs the edit, and fires Customer_edit.

See it in Fieldmotion

CRM1

Open the legacy customer edit popup, change State, and filter Network requests for Customer_setState.

CRM2

No direct production CRM2 caller was found. CRM2 saves customer addresses through its mapped layout contract.

Related endpoints

Customer_getAddress returns current or historical address context.
Customer_get shows the current stored value, including whitespace.