Fieldmotion API Getting started

Customers

Retrieve a customer address

POST /a/Customer_getAddress

Return the current or historically effective customer address and contact subset, with a legacy option that changes the customer parent before reading it.

When to use this endpoint

Use Customer_getAddress when a document, job, or audit workflow needs a compact customer location snapshot rather than the full customer record. Supplying when asks the address-history store for values effective before a Unix timestamp, preserving historical rendering after a customer address or parent changes.

For a current general-purpose record use Customer_get. Do not supply parent_id for a read-only lookup; that legacy parameter performs a write.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The linked user must be active.

The handler requires login and performs no additional role or page-permission check. It reads the authenticated tenant. Unlike the general customer detail endpoints, its customer lookup does not filter on deleted or is_active.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesCustomer ID. It must convert to an integer of at least 1.
whenUnix timestamp stringNoWhole Unix seconds. A positive value is converted to milliseconds and used to select address-history snapshots with cdate < when × 1000. Omitted, zero, negative, and non-numeric values return current data.
parent_idInteger stringNoLegacy write control. A value other than -1 or 0 calls Customer_setParentId before the address is read. Omit it for a read-only request.

Example request

$address = FM_api('Customer_getAddress', [
	'id' => '1042',
	'when' => '1771927200',
]);

Example response

{
  "city": "Belfast",
  "country": "GBR",
  "county": "Antrim",
  "landline": "028 9012 3456",
  "latitude": "54.5973",
  "longitude": "-5.9301",
  "mobile": "07700 900123",
  "name": "Northwind Service Centre",
  "parent_id": 1001,
  "postcode": "BT1 1AA",
  "state": "",
  "street_address1": "14 Harbour Road",
  "street_address2": "",
  "town": "Belfast",
  "parent_name": "Northwind Group"
}

parent_name is present only when the effective parent ID is positive and a name can be resolved. parent_id is normalized to a non-negative JSON integer; most other stored scalars remain strings.

Errors and unusual responses

ResponseCondition
{"error":"missing or invalid parameter: id"}id does not convert to a positive integer.
[]The customer is not present, or no tenant table prefix is available. Missing customers do not produce a not-found error object.

An error from the internal parent update is not returned by this endpoint. If changing the parent matters, call Customer_setParentId explicitly and check its response before reading the address.

Behaviour and edge cases

  • Historical selection is strictly before the supplied instant, not at or before it.
  • The newest qualifying history row supplies the base snapshot. Older qualifying rows are scanned to fill keys absent from newer legacy metadata.
  • If historical metadata lacks a usable name or parent, the helper searches nearby history entries and then falls back to the current customer value.
  • When no history row exists before when, current customer values are returned.
  • A current parent name is looked up from the customer table. Historical metadata can preserve the earlier parent name; if only an earlier parent ID is known, the endpoint resolves that ID's current name.
  • The read does not exclude inactive or soft-deleted customers.

Side effects

With parent_id omitted, -1, or 0, the endpoint performs no write. In particular, this legacy parameter cannot be used to clear a parent to zero.

See it in Fieldmotion

CRM1

No direct production CRM1 caller of Customer_getAddress was found. The Customer → Address History screen uses the related history data-table endpoint rather than this compact snapshot call.

CRM2

No direct production CRM2 caller was found. CRM2 current-address displays use layout-driven customer details, while historical editing uses dedicated address-history APIs.

Related endpoints