Sending telemetry
This guide describes the telemetry contract in full: what you send, how IFMS processes it and what comes back. For your first call, see Send your first batch. The provider API reference shows the published contract.
The request
POST https://gw.kairosinnovations.dev/api/v1/ingest/telemetry
Authorization: Bearer <access_token>
Content-Type: application/json
- The body is UTF-8 JSON. Field names use
snake_case. - Send your token as described in Access tokens.
- Never send your provider identity: no
provider_codeorprovider_namein the body, and no identity headers. The gateway adds your identity from your approved application.
The envelope
Every batch is wrapped in a data object:
{
"data": {
"positions": [
{ "vehicle_plate_number": "AA-12345", "recorded_at": "2026-08-05T20:04:00Z", "latitude": 9.01, "longitude": 38.77 }
]
}
}
| Field | Type | Required | Rule |
|---|---|---|---|
data | object | Yes | Must not be null. |
data.positions | array | Yes | At least one position. Version 1 sets no maximum number of positions. |
A batch has no other fields. Each position is one GPS fix for one vehicle at one moment. You can put several vehicles, or several fixes for one vehicle, in the same batch.
Position fields
| Field | Type | Required | Rule |
|---|---|---|---|
vehicle_plate_number | string | Yes | Not blank. At most 120 characters. IFMS changes it to uppercase and removes all whitespace. |
recorded_at | ISO 8601 date and time | Yes | The time your device recorded the fix, with an explicit offset. UTC (Z) is recommended. Must be inside the observation window below. |
latitude | number | Yes | WGS 84 decimal degrees, from −90 to 90 inclusive. |
longitude | number | Yes | WGS 84 decimal degrees, from −180 to 180 inclusive. |
ignition_on | boolean | No | Engine or ignition state, if your device reports it. It helps IFMS tell idling from parked. |
device_imei | string | No | At most 32 characters. Used for audit and correlation only, never as the vehicle's identity. |
A position with both optional fields:
{"data":{"positions":[
{"vehicle_plate_number":"AA-12345","recorded_at":"2026-08-05T20:04:00Z",
"latitude":9.005401,"longitude":38.763611,"ignition_on":true,
"device_imei":"356938035643809"}]}}
The timestamps in these examples are illustrations. Send the real time your device recorded each position.
What not to send
Do not send any of these as fields:
- provider identity;
- vehicle or driver master data;
- speed, heading or movement state;
- geofence or reverse-geocoding values;
- message identifiers or batch sequence numbers;
- odometer, altitude or accuracy values;
- other vendor-specific values.
IFMS works out speed, heading and movement state itself, from your successive positions. IFMS ignores fields it does not recognise, so never rely on one being processed.
The observation window
IFMS accepts a position only if recorded_at is between:
- IFMS server time minus 30 days, and
- IFMS server time plus 5 minutes.
A position outside the window does not fail the batch. It comes back in failures with the reason RECORDED_AT_OUT_OF_RANGE. Keep your device and server clocks accurate.
How IFMS processes a batch
IFMS stores a position only when IFTMS, the Ministry’s vehicle register, says the vehicle is legal. Refused positions are never stored. For each refusal, the HTTP 202 response lists an entry in failures[] with outcome: REJECTED and a reason. A new plate is first refused as VEHICLE_NOT_CHECKED. IFMS makes one background lookup for the plate, rather than one for each send. Daily updates and change notices keep the answer current. Once IFTMS says legal, the next send can be accepted.
| Rule | What happens |
|---|---|
| Each position on its own | IFMS checks every position separately. An invalid position is counted and listed in failures. Other valid positions in the same batch are stored only if their vehicles are legal. |
| The counts always add up | accepted + duplicates + rejected equals the number of positions you sent. failures has one entry for every duplicate or rejected position. |
| Duplicates | A position is a duplicate when IFMS already stored one with the same provider identity, normalised plate and recorded_at, compared to the microsecond. |
| The same plate from another provider | Refused as PLATE_HELD_BY_ANOTHER_PROVIDER. A plate is reported by one provider only: the first provider to send positions for it holds it. See One provider per plate. |
| Order | For a legal vehicle, an older position that is still inside the window is stored as history. It does not move the vehicle's live state backwards. |
| A plate IFMS has not seen before | IFMS first refuses the position as VEHICLE_NOT_CHECKED and asks IFTMS in the background. Send it again later. No vehicle or position is created from the refused position. |
Retrying safely
To retry, resend the original position with its original recorded_at. recorded_at is part of the duplicate key, so never refresh it on a retry. If IFMS already stored the position, the retry comes back as a DUPLICATE, and nothing is stored twice.
The 202 response
A valid batch returns HTTP 202 Accepted. 202 does not mean every position was stored. Always check the counts and every entry in data.failures.
This batch had two positions. The first was stored and the second was rejected:
{
"header": {
"operation": "POST",
"request_uri": "/api/v1/ingest/telemetry",
"response_code": 202,
"response_message": "SUCCESS",
"additional_details": ""
},
"data": {
"provider_code": "<your provider code>",
"provider_name": "<your organisation name>",
"accepted": 1,
"duplicates": 0,
"rejected": 1,
"failures": [
{
"index": 1,
"vehicle_plate_number": "AA-67890",
"recorded_at": "2026-08-05T20:04:30Z",
"outcome": "REJECTED",
"reason": "INVALID_FIELDS",
"errors": [
{
"field": "latitude",
"message": "must be less than or equal to 90.0",
"rejected_value": "91"
}
]
}
]
}
}
Response fields
| Field | Meaning |
|---|---|
provider_code | Your stable provider identity, taken from your approved application. You never send it. |
provider_name | Your organisation's name. It can be absent. |
accepted | New, valid positions that IFMS stored. |
duplicates | Positions IFMS had already stored. |
rejected | Positions that were not stored because they failed the IFTMS legality check, validation, the time window, parsing or storage. |
failures | One entry for every duplicate or rejected position, in the order you sent them. Empty when every position was accepted. |
Failure entry fields
Fields with no value are left out.
| Field | Meaning |
|---|---|
index | The position's place in the positions array you sent, counting from 0. |
vehicle_plate_number | The plate as you sent it. Absent when it could not be read. |
recorded_at | The timestamp as you sent it. Absent when it could not be parsed. |
outcome | REJECTED or DUPLICATE. |
reason | A code you can act on. See the table below. |
message | Optional text for a person to read, for parse, time-window, plate-hold or internal errors. Do not branch on it. |
errors | For INVALID_FIELDS only: one entry per wrong field, with field, message and rejected_value. |
Failure reasons
| Reason | Meaning | What to do |
|---|---|---|
VEHICLE_NOT_REGISTERED | IFTMS has no record of the plate. A plate longer than 20 characters is also refused with this reason. | Stop sending positions for it, or have the vehicle registered in IFTMS. |
VEHICLE_NOT_LEGAL | IFTMS says the vehicle is not legal, including a vehicle removed from the register. | Stop sending positions until IFTMS says the vehicle is legal. |
VEHICLE_NOT_CHECKED | IFMS has no IFTMS answer yet for this plate. | Send the position again later, with its original recorded_at. |
UNPARSEABLE | A value or type could not be read. | Correct the position and resend only that position. |
INVALID_FIELDS | One or more fields broke a rule. | Use errors to correct the fields. Resend only that position. |
RECORDED_AT_OUT_OF_RANGE | The timestamp is more than 30 days old or more than 5 minutes ahead. | Fix your device clock or backlog handling. Resend with the true observation time. |
PLATE_HELD_BY_ANOTHER_PROVIDER | Another provider reported this plate first and holds it. message names that provider and the date it took the plate. | Stop sending positions for the plate. If the vehicle has moved to you, ask the Ministry of Transport and Logistics to correct its record in IFTMS, quoting the plate. |
DUPLICATE | IFMS had already stored this position. | Nothing. The retry was safe. |
INTERNAL_ERROR | IFMS could not store this one position. | Retry the same position with controlled backoff and the same recorded_at. |
The set of failure reasons is additive: new reasons can appear. Treat reason and outcome values as plain strings, and handle a value you do not recognise: log it as it is instead of failing. See Changes to the API.
One provider per plate
IFMS accepts positions for a plate from one provider only. The first provider whose position for the plate is accepted holds the plate. Positions from any other provider are refused with PLATE_HELD_BY_ANOTHER_PROVIDER and are not stored.
The hold ends when either of these happens:
- IFTMS records a change of operator for the vehicle, or removes it;
- the holding provider sends no positions for the plate for 30 days, counted from the newest
recorded_atit sent.
After that, the next provider whose position is accepted holds the plate. Nothing in IFMS lets a provider release or take over a plate. If a vehicle has moved to you, ask the Ministry of Transport and Logistics to correct its record in IFTMS.
The message of the refusal reads like this:
Plate ET-12345 is already reported by Mela (since 2 Oct 2026). IFMS accepts one provider per vehicle. The hold is released when IFTMS records a change of operator or removal for this vehicle, or after 30 days without positions from Mela. If this vehicle has moved to you, ask the Ministry of Transport and Logistics to correct its record in IFTMS, quoting the plate.
Show it to a person as it is. Do not parse it: branch on reason.
Reading the counts
| Counts | What happened | What to do |
|---|---|---|
| accepted 2, duplicates 0, rejected 0 | Two new positions stored. failures is empty. | Nothing. |
| accepted 0, duplicates 1, rejected 0 | A safe replay. One DUPLICATE entry. | Nothing. Mark the original as delivered. |
| accepted 1, duplicates 0, rejected 1 | One stored, one rejected and listed. | Follow the reason. Resend only the corrected position. |
| accepted 0, duplicates 0, rejected 1 | Nothing stored. One rejected and listed. | Correct or retry, as the reason says. |
Other responses
Troubleshooting and FAQ lists every other response from the telemetry gateway, such as 400, 401, 403 and 5xx, and what to do about each. For a 401, also see Access tokens.
Handling failures in your client
Your client is ready when it:
- checks that
accepted+duplicates+rejectedequals the number of positions it sent; - handles every entry in
failuresby itsindexandreason; - accepts reasons and response fields it does not recognise;
- follows each refusal reason: waits for registration or legality to be corrected, or retries
VEHICLE_NOT_CHECKEDlater; - keeps the original
recorded_aton every retry, with controlled backoff.
The sample clients on Send your first batch print one line for every entry in failures: see print_failures in the cURL sample and report in the Python, JavaScript and Java samples.