Connect Webfleet vehicle tracking

When to use this endpoint

Use VehicleTracking_connect from the CRM2 Vehicle Tracking settings screen when a client administrator is connecting or replacing the tenant’s Webfleet account.

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

Parameter	Type	Required	Description
`account`	String	Yes	Webfleet account name after surrounding whitespace is removed.
`username`	String	Yes	Webfleet username after surrounding whitespace is removed.
`password`	String	Yes	Webfleet password. It is not trimmed, returned, or stored in plaintext.

Example request

$setup = FM_api('VehicleTracking_connect', [
	'account' => 'replace-with-webfleet-account',
	'username' => 'replace-with-webfleet-user',
	'password' => 'replace-with-webfleet-password',
]);

Example response

{
  "connection": {"provider":"webfleet","status":"connected","stale_after_minutes":10,"last_sync_at":0,"last_success_at":0,"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": [],
  "suggestions": [{"vehicle_id":30124,"remote_object_uid":"wf-vehicle-17"}]
}

Errors and unusual responses

Response	Condition
`{"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 account is required"}`	The trimmed account is blank. Equivalent messages name `username` or `password`.
`{"error":"Vehicle Tracking encryption is not configured"}`	The server lacks an active valid encryption key or the required sodium encryption function.
`{"error":"Vehicle Tracking provider is not configured"}`	The server-side Webfleet API key is absent.
`{"error":"Webfleet rejected the request"}`	Webfleet returns an application-level rejection. Transport failures return `Webfleet is temporarily unavailable`.

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

Behaviour and edge cases

The server calls Webfleet showVehicleReportExtern before storing the connection. Remote rows with blank IDs are ignored and duplicate remote IDs collapse to the last row.
Credentials are encrypted with the active server key and tenant/provider-specific additional authenticated data. Public responses never expose account, username, password, ciphertext, or key ID.
Registration matches are suggestions only. Matching removes punctuation and ignores case, and a suggestion is made only when the normalised registration is unique locally and remotely.
Reconnecting reuses the tenant/provider connection row, including its existing stale threshold, while resetting sync times, errors, route cache, remote objects, and deletion state.

Side effects

Creates or reactivates one global vehicle_tracking_connections row for the tenant and Webfleet provider.
On replacement, deletes tenant api_syncs mappings and vehicle_tracking_positions. It also records a vehicle_tracking/connect Core audit event.
Makes an outbound HTTPS request to Webfleet; connection and read timeouts are 10 and 30 seconds.

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, fill the Connect Webfleet form, and choose Connect. The client redacts all three credential parameters from its request diagnostics.

Related endpoints

VehicleTracking_saveMappings confirms vehicle-to-tracker mappings after connection.
VehicleTracking_disconnect removes credentials and cached tenant tracking data.