Fieldmotion API Getting started

Customers

Retrieve one customer

POST /a/Customer_get

Retrieve one non-deleted customer by local ID or an authorized outsourced-customer token, optionally limiting the stored fields returned.

When to use this endpoint

Use Customer_get when a workflow has one customer identifier and needs a single record, including the legacy outsourced-customer token format used by job and quote screens. It is also useful when older UI code expects an object rather than the array returned by the batch endpoint.

For integrations that can batch work, prefer Customers_getById. It accepts several IDs in one request and supports derived relationship names.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler requires login and performs no additional page or role-permission check.

Numeric IDs are read from the authenticated tenant. An outsourced token is accepted only when the token's source tenant has an active outsourcing link into the authenticated tenant. Both paths exclude soft-deleted customers but include inactive customers.

Parameters

ParameterTypeRequiredDescription
idInteger string or outsourced tokenYesLocal customer ID, or a legacy o<source-tenant>i<customer-id> token. Other values are converted to an integer for local lookup.
fieldsJSON array or arrayNoAllowed stored fields to select. Unknown names are ignored. If omitted—or if no supplied name is accepted—the endpoint falls back to its broad default field set rather than returning an error.

Allowed fields

department_id, 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, city, state, country, last_edited_all,
is_flagged, contacts

The default set contains every field above except contacts. Request contacts explicitly when it is needed. Unlike Customers_getById, this endpoint does not offer parent_name, type_name, or account_manager_name.

Example request

$customer = FM_api('Customer_get', [
	'id' => '1042',
	'fields' => json_encode([
		'id',
		'name',
		'email',
		'mobile',
	]),
]);

Example response

{
  "id": 1042,
  "name": "Northwind Service Centre",
  "email": "service@example.test",
  "mobile": "07700 900123"
}

The local response overwrites id with the integer-converted request ID, so it is a JSON number even though other database scalars are often strings. An outsourced response retains the complete token as a JSON string. Stored JSON columns are returned encoded, not expanded into nested objects.

Errors and unusual responses

ResponseCondition
{"error":"missing parameter: id"}id was omitted. A present blank value is instead converted to local ID 0 and normally produces the not-found error.
{"error":"requested customer does not exist"}The selected local or outsourced row does not exist or is soft-deleted.
{"error":"that customer belongs to an outsource host that is not linked to you"}The outsourced token names a source tenant without an active link to the authenticated tenant.

Behaviour and edge cases

  • A field list containing only unknown names unexpectedly selects the broad default set. Do not use an empty allowlist as a way to probe existence.
  • The endpoint returns inactive customers but not soft-deleted customers.
  • The outsourced path reads the linked tenant's customer table and returns the same requested stored fields. It does not enrich relationships or translate IDs.
  • The outsourced token replaces the row's numeric ID in the response so the caller can preserve its cross-tenant identity.

See it in Fieldmotion

CRM1

Open a job for editing, change its customer, and filter the Network panel for Customer_get. CRM1 retrieves the selected customer's full default record so it can adopt the customer's department. Quote note fields also call this endpoint when sourcing a value from the quote customer.

CRM2

No direct production CRM2 call to Customer_get was found. CRM2 customer displays use the shared Customer.getInstance cache, which batches records through Customers_getById.

Related endpoints