Set one customer custom field

When to use this endpoint

Use Customer_setCustom when the caller already knows the stored custom-field name and needs to change only that value.

This low-level setter does not validate the field against the tenant’s custom-field definitions. Prefer a metadata-driven customer-edit workflow when the caller does not already have a trusted field name.

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 ID; it must convert to a positive integer. The handler does not verify that the row exists.
`field`	String	Yes	Exact key in `custom_values`. A present blank or unknown key is accepted.
`value`	Mixed	Yes	Replacement value. Blank, zero, arrays, and other supplied JSON-compatible values are accepted; only omission is rejected.

Example request

$result = FM_api('Customer_setCustom', [
	'id' => '1088',
	'field' => 'Service Level',
	'value' => 'Gold',
]);

Example response

{
  "ok": 1
}

A loosely equal existing value returns {"ok":1,"warning":"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 does not convert to a positive integer.
`{"error":"missing or invalid parameter: value"}`	`value` is omitted.
`{"error":"missing or invalid parameter: field"}`	`field` is omitted.

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 missing customer is not reported. The handler can insert a change-history row, emit an audit event, fire Customer_edit, and still return success even when its customer update matched no row. Confirm the customer first when stale IDs are possible.

The read has no active/deleted filter and does not check whether the customer query returned a row.
Invalid, empty, or missing stored JSON is treated as an empty map when the new key is assigned. The resulting map is encoded as a JSON object.
Valid scalar JSON in custom_values, such as true, a number, or a string, is not normalized and can cause a PHP runtime error when indexed or updated.
The no-change test uses PHP loose equality; values with different wire types can therefore be treated as equal.
Field names and values are not checked against tenant custom-field definitions, types, or option lists.
This is a single-record mutation; it provides no list filtering or pagination.

Side effects

On the change path, a customer_changes row labelled custom: <field> is inserted before the customer update.
The customer write replaces custom_values, updates last_edited, and sets edited_uuid to Customer_setCustom. It does not explicitly invalidate the customer cache.
The handler writes a customer audit event and fires Customer_edit. These actions and the database writes are not transactional.

See it in Fieldmotion

CRM1

The legacy customer edit popup and Customers page use Customer_setCustom for individual custom fields. Filter Network requests by the exact function name after saving one custom value.

CRM2

CRM2 normally submits customer layout updates through its broader update contract; no direct production CRM2 call to Customer_setCustom was found.

Related endpoints

Customer_getCustomFields reads selected custom-field values.
Customer_get returns the stored custom_values field with the customer row.