Fieldmotion API Getting started

Vehicles

Retrieve one vehicle tracking state

POST /a/VehicleTracking_vehicle

Return one local vehicle’s cached tracking and active-user assignment state for its CRM2 detail tab.

When to use this endpoint

Use VehicleTracking_vehicle for the read-only Vehicle Tracking tab on a specific vehicle. It does not refresh Webfleet; use VehicleTracking_fleet when a refresh is required.

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 pageVehicleTracking_view role permission for the vehicle’s Vehicle Tracking tab. Client administrators satisfy the role check.

Parameters

ParameterTypeRequiredDescription
idInteger-compatibleYesNumeric tenant vehicle ID. Missing, zero, negative, and nonexistent IDs produce the same not-found error. UUIDs are not accepted.

Example request

$state = FM_api('VehicleTracking_vehicle', [
	'id' => '30124',
]);

Example response

{
  "connection": {"provider":"webfleet","status":"connected","stale_after_minutes":10,"last_sync_at":1790846400,"last_success_at":1790846400,"last_error":""},
  "vehicle": {"id":30124,"registration":"241-D-12001","description":"Service van","mapped":true,"users":[{"id":94012,"name":"Alex Engineer"}],"tracking":{"observed_at":1790846370,"received_at":1790846400,"privacy_state":"visible","latitude":54.60,"longitude":-5.92,"speed":31.0,"course":180,"ignition":1,"standstill_seconds":0,"trip_mode":2,"driver_reference":"driver-7","driver_name":"Alex Engineer","odometer":42150.3,"stale":false}},
  "server_time": 1790846400
}

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":"Vehicle not found"}The converted ID is below one or no tenant vehicle row matches.

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

Behaviour and edge cases

  • When tracking is disconnected, a valid local vehicle returns {"connection":{...disconnected...},"vehicle":null} without server_time.
  • When connected but unmapped, the vehicle object remains present with mapped:false and tracking:null.
  • Private tracking rows contain null sensitive fields. Only active assigned users are returned, sorted naturally by name.
  • Unlike the fleet response, this detail object omits current_job and next_job.

See it in Fieldmotion

CRM1

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

CRM2

Open a vehicle from Stock → Vehicles and select its Vehicle Tracking tab. The page calls this endpoint once and plots a marker only for a visible permitted position.

Related endpoints