Ingest API

The Ingest API receives tracker payloads in the selected database scope.

Path Structure

/[SCOPE]/ingest/[INGEST_TYPE]/[DEVICE_KEY]

• SCOPE is live or sandbox.
• INGEST_TYPE selects the payload parser.
• The currently available ingest type is iris.
• DEVICE_KEY uses the format PREFIX-NUMBER.
• Payloads must be sent as JSON via POST.

POST /[SCOPE]/ingest/iris/[DEVICE_KEY]

Receives an IRIS route payload. Requires only device_token in the payload.

Required Top-Level Parameters

• device_token: device token returned by /[SCOPE]/devices/register
• route: array of trackpoints

Required Trackpoint Fields

• ts: trackpoint timestamp in Unix milliseconds, UTC
• lat: latitude
• lon: longitude

Optional Trackpoint Fields

• speed: speed in km/h, default 0
• bearing: movement direction, default 0
• satellites: GPS satellites, default 0
• Additional trackpoint fields are accepted and stored in provider metadata.

Example Request

{
  "device_token": "1234567890123456",
  "route": [
    {
      "id": "tp-1",
      "ts": 1779028800000,
      "lat": 50.123456,
      "lon": 8.123456,
      "speed": 42,
      "bearing": 180,
      "satellites": 9,
      "gsmLevel": 4,
      "batteryPerc": 76,
      "charging": true
    }
  ]
}

Response

{
  "status": {
    "code": "200",
    "apiTimeConsumed": "0.018s"
  },
  "data": {
    "status": "ok",
    "written": 1,
    "ignored": 0,
    "failed": 0,
    "failed_points": []
  }
}

Errors

Errors are returned as JSON responses with an ErrorMessage field.