Fieldmotion API Getting started

Assets

Resolve an asset address

POST /a/Asset_getAddress

Resolve address data from an asset’s current whereabouts or owner, optionally reading historical customer address values.

When to use this endpoint

Use Asset_getAddress when a job, invoice, or import needs an address snapshot for an asset rather than the asset’s raw location IDs.

The result follows customer, location, and nested-asset references. Use Asset_getLocation instead when the caller needs only the immediate current location and its display coordinates.

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
idInteger stringYesPositive server-side asset ID. App IDs are not accepted.
whenUnix timestamp stringNoWhole seconds since the Unix epoch. Values that convert to 0 use current values. A positive value is passed to customer address history and nested-asset resolution, but a legacy omission prevents it from selecting historical movement for the top-level asset.

Example request

$address = FM_api('Asset_getAddress', [
	'id' => '4821',
	'when' => '1787740200',
]);

Example response

{
  "city": "Dublin",
  "country": "IRL",
  "county": "Dublin",
  "landline": "",
  "latitude": "53.3498",
  "longitude": "-6.2603",
  "mobile": "",
  "name": "Example Engineering » Compressor 4 (CMP-004)",
  "parent_id": 0,
  "postcode": "D02 XY12",
  "state": "",
  "street_address1": "1 Example Street",
  "street_address2": "",
  "town": "Dublin",
  "location_customer_id": 1088,
  "location_customer_name": "Example Engineering"
}

The exact address keys depend on the resolved source. Customer addresses can include contact and parent fields; location records contribute only name, latitude, longitude, and street_address1.

The final name always appends » <asset name> (<asset code>). location_customer_id and location_customer_name are nonzero only when the asset’s immediate resolved location is a customer.

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: id"}id is absent or does not convert to a positive integer.
{"error":"asset not found"}The top-level asset does not exist or is soft-deleted.

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

Behaviour and edge cases

  • The top-level existence check excludes soft-deleted assets but allows inactive and archived assets.
  • Location type 1 resolves a customer address; type 0 resolves a location’s own address; type 2 follows another asset recursively. Repeated location references stop resolution rather than looping.
  • If the location cannot produce an address, a positive owner_id is used as the fallback customer.
  • The top-level helper does not select the asset id into the row passed to movement-history resolution. As a result, when does not rewind the top-level asset’s whereabouts: it uses the current location, then applies the timestamp to customer address history or owner fallback.
  • When the current location points to another asset, that nested row does include its ID, so the timestamp can select the nested asset movement active at that time. Movement selection uses start_time <= when, preferring a row whose interval contains the time and otherwise the latest row started by then.
  • Nested records and owner/customer fallbacks are not consistently filtered for deletion, so historical or legacy references can still supply data.
  • If neither whereabouts nor owner resolves an address, the endpoint still returns location_customer_id=0, a blank location_customer_name, and a name beginning with » followed by the asset name and code.
  • The endpoint returns one resolved object and has no filtering or pagination.

See it in Fieldmotion

CRM1

No direct browser call was found. CRM server workflows call Asset_getAddress while importing jobs, maintaining stored job address details, and deriving invoice recipient details.

CRM2

No direct production CRM2 browser call was found; CRM2 reaches this behavior through the same server-side job and invoice helpers.

Related endpoints