Fieldmotion API Getting started

Customers

Search for customer IDs

POST /a/Customers_search

Find non-deleted customer IDs with exact or wildcard matches across selected customer fields and custom values, using deterministic ID ordering and zero-based pagination.

When to use this endpoint

Use Customers_search when an integration needs to locate customer IDs from known customer data before fetching full records. It is useful for matching a parent, email address, postcode, contact value, primary telephone number, name, or one or more configured custom-field values.

The response contains IDs only. Pass them to Customers_getById for field-limited records. Use Customers_list instead when its simpler name, activity, and edit-time filters are sufficient and you want records returned directly.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The linked user must be active.

The handler requires login but has no additional role or page-permission check. It searches only the authenticated tenant and always excludes soft-deleted customers. Inactive customers remain eligible.

Parameters

ParameterTypeRequiredDescription
nameStringNoCase-insensitive customer-name match. A value without an outer % is exact. A leading or trailing % switches the comparison to SQL wildcard matching.
emailStringNoCase-insensitive exact or wildcard match against the primary email field.
postcodeStringNoCase-insensitive exact or wildcard postcode match.
contactsStringNoCase-insensitive exact or wildcard comparison against the stored contacts column. The endpoint does not decode structured contact JSON before comparing it.
landlineStringNoMatches the primary landline field. Exact matching by default; a leading or trailing % enables wildcard matching. Blank values are ignored.
mobileStringNoMatches the primary mobile field. Exact matching by default; a leading or trailing % enables wildcard matching. Blank values are ignored.
phoneStringNoMatches the primary landline or mobile field, grouped together before combining with other filters. Does not search Key Contacts or require Telephony integration. Exact matching by default; a leading or trailing % enables wildcard matching. Blank values are ignored.
parent_idInteger stringNoRestricts results to this stored parent ID. The literal value 0 finds top-level customers. Blank and non-numeric values other than 0 are ignored.
customJSON objectNoMaps custom-field keys to required values. Every non-blank value becomes a case-insensitive exact or wildcard condition against custom_values; all supplied conditions must match. Send this object as JSON before signing.
results-per-pageInteger stringNoMaximum IDs returned per page. Defaults to 100. Integer values below 1 are rejected; the handler imposes no upper bound.
current-pageInteger stringNoZero-based page number. Defaults to 0. Negative values are rejected.

Every non-blank filter is combined with AND, including separate landline and mobile filters. Use phone to match either primary phone field. There is no general free-text “match any field” mode.

Example request

$result = json_decode(FM_api('Customers_search', [
	'phone' => '07700111222',
	'results-per-page' => '50',
	'current-page' => '0',
]), true);

$customers = FM_api('Customers_getById', [
	'ids' => json_encode($result['ids']),
	'fields' => json_encode(['id', 'name', 'contact_name', 'email', 'landline', 'mobile']),
]);

Example response

{
  "ids": [1042, 1088, 1116]
}

IDs are JSON numbers ordered by ascending customer ID. The response does not include a total count or a next-page token.

Errors and unusual responses

ResponseCondition
{"error":"invalid parameter: results-per-page"}The integer-converted page size is below 1.
{"error":"invalid parameter: current-page"}The integer-converted page number is negative.
{"ids":[]}No non-deleted customer satisfies every supplied filter, or the requested page is beyond the result set.

Malformed custom JSON is not handled as a stable validation error. Validate and JSON-encode the object in the client before sending it.

Behaviour and edge cases

  • With no business filters, the endpoint pages through every non-deleted customer in ascending ID order.
  • Filter values are trimmed and lowercased. Blank values are ignored; the custom-field value "0" is also ignored because the legacy filter treats it as empty.
  • Only a leading or trailing % selects LIKE. Under that mode, SQL wildcard characters in the value are not escaped, so % and _ have wildcard meaning.
  • Phone searches compare stored text without removing spaces, punctuation, or country prefixes. Supply the stored format or an appropriate wildcard pattern. A customer matching both phone fields is returned only once.
  • Pagination is offset-based: the database offset is results-per-page × current-page. Inserts or deletes between requests can shift later pages.
  • The endpoint has no server-side page-size ceiling. Choose a moderate size and fetch details in retryable batches.

See it in Fieldmotion

CRM1

No production CRM1 caller of Customers_search was found. The Customers screen uses its data-table endpoint rather than this integration-oriented ID search, so exercise this call with a signed API request.

CRM2

No production CRM2 caller was found. CRM2 also performs customer-list filtering through the data-table contract, not Customers_search.

Related endpoints