Fieldmotion API Getting started

Customers

Retrieve mapped customer details

POST /a/Customer_getLayoutDetails

Read field-map customer records for the configurable CRM2 customer layout.

When to use this endpoint

Use Customer_getLayoutDetails when implementing the CRM2 configurable Customer layout and you need exact field-map names rather than database column names.

For a conventional integration lookup, prefer Customers_getById; this route inherits generic layout filtering and legacy advanced-search behavior.

Authentication and permissions

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

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

ParameterTypeRequiredDescription
fieldsArray of stringsYesRequested field-map keys. It must be a request array, not a JSON string. Recognized examples include id, name, accountNumber, contactName, streetAddress1, parent, taxType, and widgetTableContact. Unknown names are omitted.
id / idsInteger string or arrayNoRestrict to local customer IDs. If both are supplied, id wins. Values are converted to integers.
<mapped field>Scalar or arrayNoAny recognized customer map key in the request becomes an exact filter: text is trimmed and case-insensitive; numeric values are converted to integers. Arrays become IN filters.
orderString/object or arrayNoMapped sort fields. Each object uses id and optional dir: "desc"; a plain string sorts ascending. Invalid fields are ignored.
advanceSearchArrayNoLegacy filter clauses using mapped column/id, condition, value, optional andOr, and parentheses in special. The raw where form is internal and unsafe for untrusted input.
widgetTableContactField name in fieldsNoWhen requested, stored contacts JSON is converted to the widget’s mapped row shape and the temporary contacts field is removed unless explicitly requested too.

Example request

$rows = FM_api('Customer_getLayoutDetails', [
	'id' => ['1042'],
	'fields' => ['id', 'name', 'accountNumber', 'widgetTableContact'],
]);

Example response

[
  {
    "id": 1042,
    "name": "Northwind Service Centre",
    "accountNumber": "NW-1042",
    "widgetTableContact": [
      {"name": "Alex Morgan", "email": "alex@example.test"}
    ]
  }
]

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: fields"}fields is absent.
[]No non-deleted customer satisfies all filters.

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 unless isActive is filtered.
  • id is appended to the field list and therefore appears in every returned row, even when the caller did not request it.
  • All exact filters are combined with AND. Advanced-search clauses are added as one further grouped filter.
  • There is no limit or pagination. A broad call can return every matching customer and every requested field.
  • The endpoint does not apply CRM2 department- or account-manager-based visibility filters; callers should not use it as an authorization boundary.

See it in Fieldmotion

CRM1

No production CRM1 caller was found. CRM1 customer forms use legacy customer endpoints.

CRM2

The Customer layout map registers this as its read endpoint. Open a configurable customer edit/view layout and filter Network requests for Customer_getLayoutDetails.

Related endpoints