Fieldmotion API Getting started

Assets

Set an asset location

POST /a/Asset_setLocation

Replace an asset’s complete legacy whereabouts pair and append movement history.

When to use this endpoint

Use Asset_setLocation for CRM1 inline whereabouts changes that supply type and target together.

For new integrations, prefer Asset_updateData with location because it rejects circular Asset-type chains.

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 asset ID. Soft-deleted rows are still found.
typeInteger stringNoWhereabouts type; omitted/invalid text becomes 0. Conventional values are 0 site, 1 customer, and 2 asset, but no range check is performed.
locationInteger stringNoTarget ID; omitted/invalid text becomes 0. Existence and compatibility with type are not checked.

Example request

$result = FM_api('Asset_setLocation', [
	'id' => '4821',
	'type' => '1',
	'location' => '1042',
]);

Example response

{
  "ok": 1,
  "movement_id": 551
}

If both stored values are loosely equal to the request, the response is {"ok":1,"movement_id":"551","msg":"no changes needed"}. The no-change movement ID can be null when no history exists.

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, zero, or otherwise not positive.
{"error":"asset does not exist"}No asset row has that ID. A soft-deleted row still counts as existing.

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

Behaviour and edge cases

  • An actual change backfills an initial creation-time movement if needed, closes the active movement, and inserts a new active movement. The new row’s owner is null, meaning no owner change was recorded.
  • Address resolution follows customer, site-to-customer, or nested-asset chains and stops on repeats. The old/new resolved addresses are passed to address history.
  • The endpoint can update archived or soft-deleted assets. It does not validate target existence.
  • This is a single-record mutation with no filtering or pagination.

Side effects

  • Updates location_id, location_type, and last_edited; invalidates asset and customer-asset caches; appends movement/address history; and writes an asset audit entry.

See it in Fieldmotion

CRM1

Change an asset’s location inline on the Assets page. CRM1 calls Asset_setLocation with the selected type and ID.

CRM2

No normal CRM2 save uses this route; cycle regression coverage uses it only to preserve and test legacy invalid data.

Related endpoints