Fieldmotion API Getting started

Assets

List asset location history

POST /a/Asset_locationsGetDT

Page through an asset’s recorded whereabouts and owner timeline.

When to use this endpoint

Use Asset_locationsGetDT for the CRM1 asset Location History table.

Use Asset_exportLocationHistory when a user needs the same history as CSV.

Authentication and permissions

The handler requires an authenticated tenant context, established by signed API-key fields or a CRM session. It checks the tenant table prefix but performs no further permission check.

Parameters

ParameterTypeRequiredDescription
aidInteger stringYesAsset ID. Presence is required, but zero, nonexistent, archived, and soft-deleted IDs are not rejected.
lengthInteger stringYesPage size passed directly to the SQL limit after integer conversion. Zero produces no rows.
order[0][dir]StringYesLegacy inverted direction: exact desc produces ascending SQL order; every other value produces descending order.
drawInteger stringYesDataTables token returned as an integer.
startInteger stringNoZero-based offset; defaults to 0.
order[0][column]Integer stringNo0 movement ID, 1 joined customer name, or 2 start time. Unsupported values retain movement-ID ordering.

Example request

$page = FM_api('Asset_locationsGetDT', [
	'aid' => '4821',
	'draw' => '1',
	'start' => '0',
	'length' => '25',
	'order' => [['column' => '0', 'dir' => 'asc']],
]);

Example response

{
  "draw": 1,
  "recordsTotal": "2",
  "recordsFiltered": "2",
  "data": [
    [551, ["1", "1042", "Northwind Service Centre", null, null], ["1 Main Street", "", "Dublin", "Dublin", "D02 XY12"], "2026-09-24 10:00:00", null, "", "7719", null, [1, 1042, "Northwind Service Centre"]]
  ]
}

Rows are [movementId, [locationType, locationId, customerName, siteName, assetName], [address1, address2, town, county, postcode], start, end, reserved, jobId, siteAddress, [ownerKnown, ownerId, ownerName]].

Location types are 0 site/area, 1 customer, and 2 another asset. Owner ID is null when the historical owner cannot be established.

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: aid"}aid is absent.
{"error":"missing or invalid parameter: length"}length is absent.
{"error":"missing or invalid parameter: [order][0][dir]"}The nested 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

  • No search filter is implemented; both counts equal the number of movement rows for the asset.
  • Historical address data first comes from the latest address snapshot no more than two seconds after the movement start. If no snapshot exists, the helper resolves the recorded location chain as it stood at that time.
  • Historical owner data comes from the latest movement at or before the row. It returns No Owner for an explicit zero owner and Unknown when history is unavailable or the customer is now deleted/missing.
  • Current names are joined without deleted filters, so a historical target’s present name can still appear. The endpoint is read-only.

See it in Fieldmotion

CRM1

Open an asset’s Location History tab and filter Network requests for Asset_locationsGetDT.

CRM2

CRM2 history regression coverage consumes the same positional owner tuple, although the primary direct production screen remains CRM1.

Related endpoints