Skip to main content

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_code or provider_name in 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 }
]
}
}
FieldTypeRequiredRule
dataobjectYesMust not be null.
data.positionsarrayYesAt 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​

FieldTypeRequiredRule
vehicle_plate_numberstringYesNot blank. At most 120 characters. IFMS changes it to uppercase and removes all whitespace.
recorded_atISO 8601 date and timeYesThe time your device recorded the fix, with an explicit offset. UTC (Z) is recommended. Must be inside the observation window below.
latitudenumberYesWGS 84 decimal degrees, from −90 to 90 inclusive.
longitudenumberYesWGS 84 decimal degrees, from −180 to 180 inclusive.
ignition_onbooleanNoEngine or ignition state, if your device reports it. It helps IFMS tell idling from parked.
device_imeistringNoAt 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.

RuleWhat happens
Each position on its ownIFMS 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 upaccepted + duplicates + rejected equals the number of positions you sent. failures has one entry for every duplicate or rejected position.
DuplicatesA 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 providerRefused 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.
OrderFor 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 beforeIFMS 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​

FieldMeaning
provider_codeYour stable provider identity, taken from your approved application. You never send it.
provider_nameYour organisation's name. It can be absent.
acceptedNew, valid positions that IFMS stored.
duplicatesPositions IFMS had already stored.
rejectedPositions that were not stored because they failed the IFTMS legality check, validation, the time window, parsing or storage.
failuresOne 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.

FieldMeaning
indexThe position's place in the positions array you sent, counting from 0.
vehicle_plate_numberThe plate as you sent it. Absent when it could not be read.
recorded_atThe timestamp as you sent it. Absent when it could not be parsed.
outcomeREJECTED or DUPLICATE.
reasonA code you can act on. See the table below.
messageOptional text for a person to read, for parse, time-window, plate-hold or internal errors. Do not branch on it.
errorsFor INVALID_FIELDS only: one entry per wrong field, with field, message and rejected_value.

Failure reasons​

ReasonMeaningWhat to do
VEHICLE_NOT_REGISTEREDIFTMS 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_LEGALIFTMS 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_CHECKEDIFMS has no IFTMS answer yet for this plate.Send the position again later, with its original recorded_at.
UNPARSEABLEA value or type could not be read.Correct the position and resend only that position.
INVALID_FIELDSOne or more fields broke a rule.Use errors to correct the fields. Resend only that position.
RECORDED_AT_OUT_OF_RANGEThe 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_PROVIDERAnother 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.
DUPLICATEIFMS had already stored this position.Nothing. The retry was safe.
INTERNAL_ERRORIFMS 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_at it 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​

CountsWhat happenedWhat to do
accepted 2, duplicates 0, rejected 0Two new positions stored. failures is empty.Nothing.
accepted 0, duplicates 1, rejected 0A safe replay. One DUPLICATE entry.Nothing. Mark the original as delivered.
accepted 1, duplicates 0, rejected 1One stored, one rejected and listed.Follow the reason. Resend only the corrected position.
accepted 0, duplicates 0, rejected 1Nothing 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 + rejected equals the number of positions it sent;
  • handles every entry in failures by its index and reason;
  • 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_CHECKED later;
  • keeps the original recorded_at on 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.