Fieldmotion API Getting started

Vehicles

Retrieve the tracked fleet

POST /a/VehicleTracking_fleet

Refresh eligible Webfleet positions and return the tenant fleet with assignments, current/next jobs, and privacy-safe tracking state.

When to use this endpoint

Use VehicleTracking_fleet to drive the CRM2 Fleet Operations map and vehicle cards. The screen polls it once per minute while visible.

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 pageFleetOperations_view role permission for Fleet Operations. Client administrators satisfy the role check.

Parameters

This endpoint has no operation-specific parameters.

Example request

$fleet = FM_api('VehicleTracking_fleet');

Example response

{
  "connection": {"provider":"webfleet","status":"connected","stale_after_minutes":10,"last_sync_at":1790846400,"last_success_at":1790846400,"last_error":""},
  "vehicles": [{
    "id": 30124,
    "registration": "241-D-12001",
    "description": "Service van",
    "mapped": true,
    "users": [{"id":94012,"name":"Alex Engineer"}],
    "current_job": null,
    "next_job": {"id":70124,"reference":"JOB-70124","scheduled_at":1790853600,"ends_at":1790857200,"customer":"Example Customer"},
    "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 Tracking is not connected"}No active connected Webfleet connection exists.

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

Behaviour and edge cases

  • At most one request per connection per 60 seconds claims the refresh lease and contacts Webfleet. Concurrent or earlier polls use the stored connection and positions.
  • Provider/decryption failures leave the latest permitted positions available and expose a safe message in connection.last_error. A later successful refresh clears that message.
  • Only mapped trackers produce positions. The store retains one latest position per mapped vehicle, not route history.
  • Private-trip observations contain privacy_state="private" but all location, motion, driver, and odometer fields are null; a new private observation also replaces a previously visible position.
  • Active users are assigned by either numeric vehicle ID or vehicle UUID. Current and next jobs exclude deleted/completed rows, use user-type zero, and consider scheduled rows up to one year ahead.
  • Job destination coordinates are deliberately omitted from this response and retained server-side for ETA calculation.

Side effects

  • When refresh is due, updates the global connection lease/sync/error fields, calls Webfleet showObjectReportExtern, and replaces each mapped vehicle’s stored latest-position row.

See it in Fieldmotion

CRM1

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

CRM2

Open Jobs → Fleet Operations. Initial map load and each visible one-minute refresh call this endpoint; inspect the vehicle state cards and network response together.

Related endpoints