Fieldmotion API Getting started

Vehicles

Retrieve vehicle-tracking setup

POST /a/VehicleTracking_getSetup

Load public connection status, local vehicles, cached Webfleet objects, saved mappings, and unsaved registration suggestions.

When to use this endpoint

Use VehicleTracking_getSetup to render the CRM2 administrator mapping screen. It reads cached setup state and does not refresh the provider.

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_view 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

This endpoint has no operation-specific parameters.

Example request

$setup = FM_api('VehicleTracking_getSetup');

Example response

{
  "connection": {"provider":"webfleet","status":"connected","stale_after_minutes":10,"last_sync_at":1790846400,"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.

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

Behaviour and edge cases

  • Without a connection, connection reports provider webfleet, status disconnected, threshold 10, and zero sync timestamps; the other arrays contain local vehicles or are empty as applicable.
  • Local vehicles are ordered by registration then numeric ID. Mappings are ordered by local vehicle ID.
  • Remote objects come from the last successful connect operation, not a live Webfleet request.
  • Suggestions compare registrations after uppercasing and removing non-alphanumeric characters. They exclude already mapped vehicles/trackers and are never saved automatically.
  • Connection credentials and internal identifiers are deliberately absent from the public object.

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. Page load calls this endpoint and renders either the connect form or the settings/mapping table.

Related endpoints