Fieldmotion API Getting started

Assets

Get asset locations

POST /a/Assets_getLocations

Resolve each selected asset’s current whereabouts into customer, area, or parent-asset display data.

When to use this endpoint

Use Assets_getLocations after asset rows provide whereabouts IDs and an export or map needs names, addresses, or coordinates.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler requires login or an established tenant database context and performs no additional Asset-page or role-permission check unless the page says otherwise.

Every query and write uses the authenticated tenant’s tables. CRM1 and CRM2 may hide actions through client-side permissions that these collection routes do not repeat.

Parameters

ParameterTypeRequiredDescription
cids / idsJSON array string or native arrayYesAsset IDs. cids is the legacy primary name; ids is accepted only when cids is absent. Values are integer-converted.
indexedInteger-compatibleNoWhen nonzero, returns an object keyed by asset ID and removes each row’s id. Default 0 returns a JSON array with id.
fieldsAnyNoIgnored. Some export callers send a field list, but the endpoint always returns its fixed shape.

Example request

$locations = FM_api('Assets_getLocations', [
	'ids' => json_encode(['4821', '4822']),
	'indexed' => '1',
]);

Example response

{
  "4821": {
    "location_type": "1",
    "location_id": "1042",
    "latitude": "53.3498",
    "longitude": "-6.2603",
    "name": "Example Engineering",
    "street_address1": "1 Example Street",
    "postcode": "D02 X285"
  }
}

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: cids"}Neither key is present.
{"error":"invalid parameter: cids"}The selected value is not an array and does not decode to one.

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 source assets are excluded. Customer whereabouts merge customer coordinates and address fields; area whereabouts add name and coordinates; Asset whereabouts add only the parent asset name.
  • User whereabouts (location_type=3), unknown types, zero IDs, and missing target rows remain as the base id/location_type/location_id tuple.
  • The area query selects lng but the merge reads lon, so the returned area longitude is currently 0. There is no ordering guarantee or pagination.

See it in Fieldmotion

CRM1

Job/customer-address helpers and export widgets call this route to translate Asset whereabouts.

CRM2

CRM2 Job Calendar and export widgets use the same translation route, commonly with indexed=1.

Related endpoints