Fieldmotion API Getting started

Customers

Find a customer by custom value

POST /a/Customer_getByCustom

Find one active customer ID by an exact key/value pair in the stored custom-values object.

When to use this endpoint

Use Customer_getByCustom for a legacy integration that stores a stable external key in custom_values and needs the corresponding local customer ID.

Do not rely on it to detect duplicates: it returns at most one matching ID and establishes no winner when several records contain the same value.

Authentication and permissions

The request must establish tenant context. The handler checks DBP but performs no additional permission check.

Parameters

ParameterTypeRequiredDescription
nameStringYesExact JSON property name in custom_values. A blank string is accepted as a supplied name.
valueScalar stringYesExact stored JSON scalar text. Matching is database collation-dependent; no trimming or case normalization is applied by the handler.

Example request

$result = FM_api('Customer_getByCustom', [
	'name' => 'external_id',
	'value' => 'NW-1042',
]);

Example response

{
  "id": "1042"
}

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: name"}name is absent.
{"error":"missing or invalid parameter: value"}value is absent.
{"error":"no customer found with that custom value"}No non-deleted customer has the exact custom property/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

  • Soft-deleted customers are excluded; inactive customers are included.
  • The query has no explicit ordering or uniqueness constraint. If duplicates exist, the selected row is not defined as part of the contract.
  • The response contains only id; retrieve the record separately when fields or activity state are needed.
  • There is no pagination.

See it in Fieldmotion

CRM1

No production CRM1 caller was found. The endpoint remains covered by direct API tests.

CRM2

No production CRM2 caller was found; mapped customer searches use other list/detail endpoints.

Related endpoints