Check whether a customer contact number is unique

When to use this endpoint

Use Customer_checkLandlineIsUnique to preflight the primary Contact Number during a customer edit when the tenant chooses to require unique numbers.

The endpoint does not read that tenant setting itself. Callers decide whether to run the check; Customer_setLandline separately enforces the setting during its write.

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	Positive customer ID to exclude. The handler does not verify that this customer exists, and `0` cannot be used for a new record.
`landline`	String	No	Proposed number after trimming. Omission becomes blank and can match another customer whose stored value is blank.

Example request

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

Example response

{
  "ok": 0,
  "data": {
    "id": 1042,
    "name": "Northwind Service Centre"
  }
}

When no collision is found, the response is {"ok":1}. The conflicting id is an integer; name is the stored customer name.

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":"invalid or missing parameter: id"}`	`id` is absent or does not convert to a positive integer.

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

Behaviour and edge cases

Only rows with deleted=0 participate; inactive customers still participate.
The SQL has no ordering, so when several rows collide the returned customer is not deterministic.
Numbers are compared as stored after trimming the proposed input; punctuation and country prefixes are not normalized.
The endpoint returns one match and provides no filtering or pagination.

See it in Fieldmotion

CRM1

On the legacy customer edit page, change Contact Number and submit while customer-landline-unique is enabled. Filter Network requests for Customer_checkLandlineIsUnique; CRM1 uses the returned name in its warning.

CRM2

No direct production CRM2 caller was found. Its customer edit flow performs validation through the layout-driven update path.

Related endpoints

Customer_setLandline applies the tenant required-number and uniqueness settings during a focused update.
Customer_new applies the same uniqueness setting when creating a customer.