Fieldmotion API Getting started

Vehicles

Replace vehicle-tracking mappings

POST /a/VehicleTracking_saveMappings

Replace the tenant’s complete one-to-one mapping between Fieldmotion vehicles and cached Webfleet trackers.

When to use this endpoint

Use VehicleTracking_saveMappings after reviewing the saved and suggested matches on the CRM2 Vehicle Tracking settings page. Always send the complete desired mapping set.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session, and the tenant’s features2.vehicle_tracking entitlement must currently equal 1. The entitlement is read from the global account row on every call.

The user needs the explicit pageSettingsVehicleTracking_edit role permission for Vehicle Tracking settings. Client administrators satisfy the role check.

The handler also requires client-administrator status; the page permission alone is insufficient for a non-administrator.

Parameters

ParameterTypeRequiredDescription
mappingsJSON array or native arrayEffectively yesComplete replacement array of objects containing numeric vehicle_id and string remote_object_uid. An omitted, malformed, or non-array value decodes to an empty array and therefore clears all mappings.

Example request

$setup = FM_api('VehicleTracking_saveMappings', [
	'mappings' => json_encode([
		['vehicle_id' => 30124, 'remote_object_uid' => 'wf-vehicle-17'],
	]),
]);

Example response

{
  "connection": {"provider":"webfleet","status":"connected","stale_after_minutes":10,"last_sync_at":0,"last_success_at":1790846400,"last_error":""},
  "vehicles": [{"id":30124,"reg":"241-D-12001","description":"Service van"}],
  "remote_objects": [{"id":"wf-vehicle-17","number":"17","name":"Service van tracker","registration":"241D12001"}],
  "mappings": [{"vehicle_id":"30124","remote_object_uid":"wf-vehicle-17"}],
  "suggestions": []
}

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":"Webfleet is not connected"}No active connected Webfleet row exists.
{"error":"Invalid vehicle tracking mapping"}An item is not an object/array, names a nonexistent tenant vehicle, or names a tracker absent from the cached remote-object catalogue.
{"error":"Each vehicle and tracker may be mapped only once"}The request repeats a local vehicle or remote tracker.

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

Behaviour and edge cases

  • Every referenced vehicle must currently exist and every tracker ID must be present in the connection’s cached remote-object list.
  • One local vehicle maps to at most one tracker and one tracker maps to at most one local vehicle.
  • The returned setup may produce new unsaved suggestions for vehicles left unmapped.

Side effects

  • Replaces Webfleet vehicle rows in tenant api_syncs, deletes every cached tracking position for the connection, resets last_sync_at to zero, clears the ETA route cache, and records a mapping audit event.
  • The next fleet refresh is eligible to contact Webfleet immediately and repopulate positions for the new mappings.

See it in Fieldmotion

CRM1

No CRM1 production caller was found. Vehicle Tracking navigation and screens are implemented in CRM2.

CRM2

Open Settings → Vehicle Tracking, review the dropdowns, and choose Save mappings. Suggested selections are not persisted until that button is used.

Related endpoints