Telematics Event Specification

Beta

Telematics data ingestion is in beta and is enabled for a limited number of partners and customers, so its behaviour may still change.

If you are interested in sending telematics data to Cartrack, reach out to your Cartrack contact person to discuss access.

Use this schema when sending telematics events to Cartrack.

API reference

The ingestion endpoint also has an interactive OpenAPI reference, hosted per region. Both regions serve the same contract, so use the one for the host you send to:

• Africa: Data Ingestion reference
• Asia: Data Ingestion reference

Important notes

• Time must be in UTC, ISO-8601 format
• Enforce event uniqueness (e.g., via provider_event_id)
• Validate that event_ts <= ingested_at + tolerance (ingestion time is server-side)
• Version the schema or route to support future changes
• Odometer unit is kilometers

Example payload

{
  "event_type": "PERIODIC",
  "event_ts": "2026-01-19T08:42:15Z",

  "chassis_number": "ABC12345678901234",
  "registration": "XX00XXGP",

  "source": {
    "provider": "third_party_x",
    "device_id": "IMEI123456789",
    "provider_event_id": "evt-984739287",
    "provider_received_ts": "2026-01-19T08:42:18Z"
  },

  "position": {
    "latitude": 1.3521,
    "longitude": 103.8198,
    "altitude": 15,
    "bearing": 245,
    "accuracy": 5
  },

  "telemetry": {
    "speed": 54,
    "ignition": true,
    "rpm": 2200,
    "odometer": 45231.4
  }
}

Field definitions

Top-level fields

Field	Type	Required	Notes
event_type	string	yes	IGNITION_ON, IGNITION_OFF, PERIODIC, SPEEDING_START, SPEEDING_END. Case-sensitive
event_ts	ISO-8601 UTC	yes	Time when event occurred on device
chassis_number	string	yes	Vehicle Identification Number (VIN), exactly 17 characters
registration	string	optional	Vehicle registration (number plate), max 100 characters. See Vehicle registration
source	object	yes	Identifies the event origin
position	object	conditional	Required for location events
telemetry	object	conditional	Vehicle signals. Required for speeding events

Vehicle registration

chassis_number is the required identifier and is what every event is matched on. registration is optional and identifies the same vehicle by its number plate.

Send it when you have it. For a vehicle Cartrack does not yet track, the plate you send will be used when the vehicle is created, instead of a generated placeholder that your fleet would otherwise see next to its real plates. This is rolling out progressively, so a vehicle created today may still show the placeholder.

• Optional. Omitting it changes nothing else about how your events are processed.
• Blank counts as omitted. An empty or whitespace-only value is discarded and the event is still accepted, so there is no need to filter out vehicles you hold no plate for.
• Normalized on arrival. Leading and trailing whitespace is trimmed and the value is upper-cased, matching how Cartrack stores plates. Punctuation and inner spacing are preserved, so ab-12 cd is stored as AB-12 CD.
• Must be the vehicle's real plate. A plate already in use on another vehicle will not be applied, and the placeholder is used instead.
• Used at creation. It will not rename a vehicle Cartrack already tracks. Tell Cartrack support if a plate needs changing on an existing vehicle.

source

Field	Type	Required	Notes
provider	string	yes	Logical source name
device_id	string	optional	IMEI, serial, etc.
provider_event_id	string	recommended	Used for idempotency
provider_received_ts	ISO-8601 UTC	optional	When provider received the event

position

Field	Type	Required	Notes
latitude	number	yes	Decimal degrees
longitude	number	yes	Decimal degrees
altitude	number	optional	Meters above sea level
bearing	number	optional	Heading in degrees clockwise from true north
accuracy	number	optional	Horizontal position accuracy in meters

telemetry

Field	Type	Required	Units / Notes
speed	number	yes	km/h. On speeding events this is the vehicle's actual speed. A posted speed limit is not carried
ignition	boolean	yes	true = ON
rpm	number	optional	Revolutions per minute
odometer	number	yes	Kilometers

Event-type expectations

These are the event types supported today. event_type is validated against this list, so an event carrying any other value is rejected. More types will be added progressively, so check this page or ask your Cartrack contact person before building around a type that is not listed yet.

Event type	Position	Telemetry
IGNITION_ON	required	Marks the beginning of a trip
IGNITION_OFF	required	Marks the end of a trip
PERIODIC	required	Recommended. Used to plot the path taken by the vehicle
SPEEDING_START	required	Required. Marks the start of a speeding period reported by the device. See Speeding events
SPEEDING_END	required	Required. Marks the end of a speeding period. Sending it is recommended; see Speeding events for how a period closes without one

Speeding events

SPEEDING_END is recommended but not required. If none arrives, an open speeding period is closed automatically by whichever of these comes first:

• An IGNITION_OFF. The end of the speeding period is recorded before the ignition off. Other events with telemetry.ignition set to false do not close it.
• A later event with telemetry.speed set to 0.
• 10 minutes after the period opened. The period closes at the time of the last event received while it was open.

These events are ignored:

• A SPEEDING_START while a speeding period is already open
• A SPEEDING_START when the last ignition event received for the vehicle was an IGNITION_OFF, or when no IGNITION_ON has been received yet, whatever its telemetry.ignition says. A vehicle that starts sending mid-trip has its speeding events ignored until its next IGNITION_ON
• A SPEEDING_END when no speeding period is open

Events are ordered by event_ts, so a delayed or buffered (store-and-forward) event cannot reopen or close a speeding period out of order. event_ts must be the time on the device.