Fieldmotion API Getting started

Customers

Resolve customers by Xero ID

POST /a/Customers_listByXeroId

Resolve Xero contact identifiers to linked local customer IDs for the tenant’s current Xero organization.

When to use this endpoint

Use Customers_listByXeroId while importing data whose customer reference is a Xero contact ID. It translates existing synchronization links; it does not create customers or links.

The endpoint is connector-specific. Do not use it for QuickBooks or Business Central identifiers.

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
namesJSON array stringYesXero contact identifiers. Duplicates are removed first; then every character other than lowercase a-z and digits is stripped. Callers normally send lowercase GUIDs with punctuation removed by this normalization.

Example request

$links = FM_api('Customers_listByXeroId', [
	'names' => json_encode(['01234567-89ab-cdef-0123-456789abcdef']),
]);

Example response

[
  {
    "local_id": "1042",
    "remote_id": "0123456789abcdef0123456789abcdef"
  }
]

The endpoint returns link-table values, not customer rows. Both identifiers are normally JSON strings.

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 parameter: names"}names is absent.
{"error":"invalid parameter: names"}names does not decode to an array.
[]No link matches the normalized IDs, connector, object type, and current Xero organization.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • Only api_name="xero", object_type="customer" links for the tenantId in the tenant’s xero_token setting are returned. A missing token uses a blank instance ID.
  • The endpoint does not join the customer table, so a link can be returned even if its local customer is inactive, deleted, or missing.
  • Deduplication occurs before punctuation normalization; differently formatted inputs can normalize to the same SQL value.
  • Result order is undefined. There is no pagination or limit.

See it in Fieldmotion

CRM1

In CRM1, open a CSV import whose customer-ID mapping is translated from Xero. The import mapper batches column values through Customers_listByXeroId; filter Network requests by the function name.

CRM2

CRM2’s import widget uses the same endpoint when a customer ID column is translated from Xero. Observe it in Network while preparing the import mapping.

Related endpoints