Customers
Find a customer by account number
/a/Customer_getByAccountNumber
Resolve one non-deleted customer ID from the value stored in the customer account-number field.
When to use this endpoint
Use Customer_getByAccountNumber when another system already holds the Fieldmotion customer account number and needs the corresponding Fieldmotion ID before fetching details or creating a linked object.
This is a lookup, not a uniqueness guarantee. Fieldmotion permits duplicate account numbers through several write paths, so integrations that require an unambiguous external key should validate tenant data and retain the returned Fieldmotion ID.
Authentication and permissions
The request must establish an authenticated tenant through signed API-key fields or a logged-in CRM session. The handler has no additional role or page-permission check.
Only the authenticated tenant is searched. Soft-deleted customers are excluded; inactive customers are eligible.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
account_number | String | Yes | Value compared with the stored account_number. The handler does not trim, normalize, or validate it; comparison collation follows the tenant database. A present blank string is a valid lookup value. |
Example request
$result = FM_api('Customer_getByAccountNumber', [
'account_number' => 'NW-1104',
]);Example response
{
"id": "1042"
}The database ID is normally serialized as a JSON string.
Errors and unusual responses
| Response | Condition |
|---|---|
{"error":"not logged in"} | No tenant context was established. |
{"error":"missing or invalid parameter: account_number"} | The parameter was omitted. Blank is not rejected when present. |
{"error":"no customer exists with that account_number"} | No non-deleted customer matched. |
Behaviour and edge cases
- The query does not specify an order and returns only one ID. If several customers share the value, which matching ID is selected is not guaranteed.
- Inactive customers are returned; soft-deleted customers are not.
- Whitespace is significant because the handler does not trim the request.
- The endpoint returns no customer fields beyond
id. Follow it with a detail endpoint.
See it in Fieldmotion
CRM1
No production CRM1 caller of Customer_getByAccountNumber was found. Use a signed API request to observe this integration lookup.
CRM2
No production CRM2 caller was found. CRM2's customer pages select records by internal ID and do not demonstrate this endpoint.
Related endpoints
Customer_getretrieves the resolved customer record.Customers_getByIdfetches one or more resolved IDs with a selected field list.Customers_listis better suited to supported name, activity, and edit-time filters.