List customer address history

When to use this endpoint

Use Customer_getAddressHistoryDT to populate the CRM1 Address History tab and inspect address snapshots recorded over time.

The endpoint does not reconstruct the customer’s current address; use Customer_getAddress for current normalized address fields.

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

Parameter	Type	Required	Description
`customer_id`	Integer string	Yes	Customer object ID matched against address rows. Presence is checked, but positivity and customer existence are not.
`start`	Integer string	Yes	Zero-based row offset.
`length`	Integer string	Yes	Page size.
`draw`	Integer string	Yes	DataTables counter copied to the response.
`order[0][dir]`	String	Yes	Exact `desc` selects descending; other values select ascending.
`order[0][column]`	Integer string	No	`0` sorts by address-row ID; `1` and all other values sort by creation date.
`address`	String	No	Case-insensitive substring match against the raw metadata JSON, country, postcode, or county.

Example request

$history = FM_api('Customer_getAddressHistoryDT', [
	'customer_id' => '1088',
	'start' => '0',
	'length' => '25',
	'draw' => '12',
	'order' => [['column' => '1', 'dir' => 'desc']],
	'address' => 'Harbour',
]);

Example response

{
  "draw": 12,
  "recordsTotal": "2",
  "recordsFiltered": "1",
  "data": [
    ["340", "1727172000000", "{\"name\":\"Northwind Belfast\",\"street_address1\":\"14 Harbour Road\"}", "County Antrim", "BT1 1AA", "GBR"]
  ]
}

Each row is address-row ID, stored creation value, raw metadata JSON string, county, postcode, and country. Current history rows normally store creation time as Unix milliseconds; a synthesized baseline can use 0. The endpoint does not decode or normalize metadata.

Errors and unusual responses

Response	Condition
`{"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: start"}`	`start` is absent.
`{"error":"missing or invalid parameter: length"}`	`length` is absent.
`{"error":"missing or invalid parameter: customer_id"}`	`customer_id` is absent.
`{"error":"missing or invalid parameter: [order][0][dir]"}`	The sort direction is absent.
`{"error":"missing or invalid parameter: draw"}`	`draw` is absent.

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 address rows with obj_type=0 and the supplied obj_id are included.
There is no customer-existence, customer-deletion, or address-deletion filter. A nonexistent customer ID simply yields no rows unless orphan history exists for that ID.
The search lowercases the request and compared columns, but retains SQL wildcard meaning for percent and underscore.

See it in Fieldmotion

CRM1

Open a customer and select Address History. Filter Network requests for Customer_getAddressHistoryDT; address search, sort, and pagination reload this endpoint.

CRM2

A source search found no CRM2 caller for this history table.

Related endpoints

Customer_getAddress returns the current address rather than historical snapshots.
Customer_getChangesDT returns field-level customer change history.