Fieldmotion API Getting started

Vehicles

Set the stale-position threshold

POST /a/VehicleTracking_settingsSave

Set how many minutes may pass before a cached vehicle position is marked stale.

When to use this endpoint

Use VehicleTracking_settingsSave from the CRM2 administrator screen to tune the fleet display’s stale-position threshold.

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
stale_after_minutesInteger-compatibleNoDefaults to 10 when omitted. After integer conversion it must be from 1 through 1440, inclusive. Fractional and nonnumeric values are truncated or become zero.

Example request

$setup = FM_api('VehicleTracking_settingsSave', [
	'stale_after_minutes' => '15',
]);

Example response

{
  "connection": {"provider":"webfleet","status":"connected","stale_after_minutes":15,"last_sync_at":1790846400,"last_success_at":1790846400,"last_error":""},
  "vehicles": [],
  "remote_objects": [],
  "mappings": [],
  "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 connection row exists.
{"error":"Stale threshold must be between 1 and 1440 minutes"}The converted value is outside the inclusive range.

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 threshold is evaluated against server_time - tracking.observed_at. A position exactly at the threshold is not stale; it becomes stale only when older.
  • The setting changes presentation classification only. It does not alter the once-per-minute provider refresh throttle.

Side effects

  • Updates the global tenant connection row’s threshold and edit timestamp and records a vehicle_tracking/settings Core audit event.
  • Does not contact Webfleet or clear existing positions.

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, change Stale after (minutes), and choose Save threshold.

Related endpoints