Fieldmotion API Getting started

Customers

Check whether an account number is unique

POST /a/Customer_checkAccountNumberIsUnique

Check whether another customer row already uses a proposed account number before a create or edit workflow continues.

When to use this endpoint

Use Customer_checkAccountNumberIsUnique as an advisory preflight when a UI or integration wants account numbers to be distinct.

This check is not enforced by Customer_setAccountNumber and does not reserve the value. Recheck or handle duplicates in the calling workflow.

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

ParameterTypeRequiredDescription
idInteger stringYesCustomer ID to exclude from the search. Send 0 for a not-yet-created customer. The handler checks presence but does not require a positive value or an existing customer.
account_numberStringYesProposed account number after trimming. Blank is accepted and can collide with another blank value.

Example request

$result = FM_api('Customer_checkAccountNumberIsUnique', [
	'id' => '1088',
	'account_number' => 'NW-1088',
]);

Example response

{
  "ok": 1
}

A collision returns an error response rather than ok:0.

Errors and unusual responses

ResponseCondition
{"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 omitted. A present 0 is valid for this endpoint.
{"error":"missing or invalid parameter: account_number"}account_number is omitted.
{"error":"Account number must be unique"}Any other customer row has the proposed trimmed value.

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

Behaviour and edge cases

  • The query does not filter soft-deleted or inactive customers, so either can cause a collision.
  • Comparison follows the tenant database collation; the endpoint performs no case or punctuation normalization beyond trimming.
  • Only the first collision matters. There is no filtering, pagination, or matching-customer data in the response.

See it in Fieldmotion

CRM1

In the legacy Create Customer dialog or customer edit page, change Account Number and filter Network requests for Customer_checkAccountNumberIsUnique. CRM1 shows a warning style but does not make this endpoint an atomic save guard.

CRM2

No direct production CRM2 caller was found. CRM2 customer creation and editing use layout-driven contracts.

Related endpoints