Set a customer contact number

When to use this endpoint

Use Customer_setLandline for the primary Contact Number field on an existing active customer.

This setter is the appropriate focused path when tenant rules must be enforced. Its uniqueness behavior is an exact stored-string comparison, so normalize numbers consistently in the caller.

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	Active, non-deleted customer to update; it must convert to a positive integer.
`val`	String	No	New contact number. Omission defaults to blank. A trimmed copy is validated and compared, but a successful update stores the original untrimmed request string.

Example request

$result = FM_api('Customer_setLandline', [
	'id' => '1088',
	'val' => '028 9012 3456',
]);

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":"customer does not exist"}`	The ID does not identify a non-deleted customer.
`{"error":"Contact Number must be filled"}`	The trimmed value is blank while `customers-require-landlines` is enabled.
`{"error":"That landline is already in use by the following customers: ..."}`	`customer-landline-unique` is enabled and another non-deleted customer has the exact trimmed value. The message contains customer names and HTML links.

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

Behaviour and edge cases

Comparison and storage differ. Validation and no-change checks use the trimmed value, but the update stores raw val. Leading or trailing whitespace can therefore be written and can undermine later exact-match checks.

This is the only setter in this batch whose target lookup explicitly requires deleted=0; inactive rows are not excluded.
Uniqueness considers other non-deleted customers only and does not normalize punctuation, spaces, or country codes.
When the required-value setting is disabled, omission or blank clears the field.
This is a single-record mutation; it provides no list filtering or pagination.

Side effects

A real change updates landline, last_edited, and edited_uuid. It does not explicitly invalidate the customer cache.
It writes a customer audit-log entry and fires Customer_edit. No call or message is sent.

See it in Fieldmotion

CRM1

Open the legacy customer edit popup, change Contact Number, and filter Network requests for Customer_setLandline. Tenant settings can make the field required or reject a duplicate.

CRM2

No direct production CRM2 caller was found. CRM2 customer forms use their layout-driven update path.

Related endpoints

Customer_setMobile changes the separate mobile field without these tenant checks.
Customer_get retrieves the value after the update.