Retrieve customers by ID · Fieldmotion API

When to use this endpoint

Use Customers_getById when you already have one or more customer IDs and need the corresponding records. It is the normal detail step after Customers_listByLastEdited in a short-polling workflow, and Fieldmotion's object cache uses it to combine several customer lookups into one request.

Use Customers_list instead when you need to find records by name, activity state, or edit time. This endpoint does not search and does not return a placeholder for an unknown ID.

Authentication and permissions

The request must authenticate either with the signed API-key fields described in Getting started or through a logged-in CRM session. The linked user must be active.

The handler requires a logged-in user but has no additional role or page-permission check. Normal numeric IDs are read from the authenticated user's tenant and soft-deleted customers are excluded. Legacy outsourced customer tokens are accepted only when the authenticated tenant has an active link from the source tenant.

Parameters

Parameter	Type	Required	Description
`ids`	JSON array or array	Yes	Customer IDs to retrieve. Signed external requests should send a JSON array of string IDs, for example `["1042","1088"]`. Numeric-looking values are converted to integers and deduplicated. The legacy token form `o<source-tenant>i<customer-id>` addresses a customer supplied through outsourcing.
`fields`	JSON array or array	No	Limits returned columns. Omit it to return every allowed stored field. Unknown names are ignored; if no accepted or derived field remains, the endpoint returns `{"error":"no fields selected"}`.

Allowed fields

account_number, id, name, notes, email, last_edited, industry,
parent_id, street_address1, street_address2, town, county, postcode,
landline, mobile, contact_name, cdate, created_by, custom_values,
callback, account_manager, type, meta, callback_notes, latitude,
longitude, is_active, country, department_id, state, city, price_band,
contacts, is_flagged, credit_terms, area_id, accounts_number,
accounts_name, billing_target

Three derived names are also accepted: parent_name, type_name, and account_manager_name. Requesting one automatically includes its ID field (parent_id, type, or account_manager) in the response.

Example request

The arrays are JSON-encoded before signing so the exact nested values reach the endpoint:

$customers = FM_api('Customers_getById', [
	'ids' => json_encode(['1042', '1088']),
	'fields' => json_encode([
		'id',
		'name',
		'email',
		'parent_name',
		'last_edited',
	]),
]);

Example response

[
  {
    "id": "1042",
    "name": "Northwind Service Centre",
    "email": "service@example.test",
    "parent_id": "1001",
    "last_edited": "2026-09-24 09:41:18",
    "parent_name": "Northwind Group"
  },
  {
    "id": "1088",
    "name": "Northwind Cork",
    "email": "cork@example.test",
    "parent_id": "1001",
    "last_edited": "2026-09-24 09:46:02",
    "parent_name": "Northwind Group"
  }
]

Legacy database scalars such as IDs are commonly serialized as JSON strings. Stored structured fields—including meta, custom_values, and contacts—are returned as JSON-encoded strings rather than decoded objects.

Errors and unusual responses

Response	Condition
`{"error":"missing or invalid parameter: ids"}`	`ids` was omitted.
`{"error":"no fields selected"}`	`fields` was present but contained no accepted stored or derived field.
`{"error":"not logged in"}`	The request did not establish an authenticated user.
`[]`	No requested local ID matched a non-deleted customer, or no authorized outsourced record was found.

Missing IDs are silently omitted; the result does not preserve a slot for each request value. As with other legacy API calls, application errors may be JSON responses with an HTTP 200 status.

Behaviour and edge cases

Normal IDs are converted with integer semantics and deduplicated before the query.
The database query does not establish request order. Match records by id instead of relying on array position.
Soft-deleted local customers are excluded. Inactive customers are not excluded.
Derived names appear only when the referenced row can be resolved; a missing related name is omitted rather than returned as an empty field.
In the current legacy implementation, request parent_name whenever requesting type_name or account_manager_name. Those enrichment branches reuse the internal parent-ID list and can otherwise produce a server-side warning or error.
There is no pagination parameter or explicit batch-size limit in this handler. Keep integration batches moderate so requests remain retryable.
Outsourced tokens are a legacy cross-tenant UI mechanism. They require an active tenant link, retain the token as the returned id, and the outsourced query does not apply the local branch's soft-delete filter or derived-name enrichment.

See it in Fieldmotion

CRM1

Open Customers, select a customer, and open the main edit page. With browser developer tools open, filter the Network panel for Customers_getById. CRM1's Customer.getInstance object cache batches nearby lookups for the same endpoint, so the ids array may contain more than the customer currently visible.

CRM2

Open Customers and select a record. CRM2's Customer edit page calls the same Customer.getInstance cache; filter Network requests for Customers_getById. CRM2 also uses field-limited batches when exporting form data that contains customer fields.

Related endpoints

Customers_list finds customer records by supported filters and can return selected fields directly.
Customers_listByLastEdited supplies changed IDs for the recommended polling flow.
Customer_new creates a customer; fetch the returned ID here when the integration needs the stored final name or other generated values.