POST /v2/telemetry/batch — Amazon Automotive Telematics API

Authentication

Requests must be signed with SigV4a. Service name: execute-api, region set: *.

Headers

Header		Description
`X-Provider-Key`	aggregators only	The provider name assigned during onboarding (not an API key). Required only for provider aggregators submitting on behalf of multiple providers. Single-provider integrations have this injected automatically from the onboarded account.
`Content-Type`	required	Must be `application/json`.

Request Body

Field	Type		Description
`batchId`	`string`	required	A UUID uniquely identifying this batch request. Used for deduplication and support investigations.
`timestamp`	`number`	optional	Epoch milliseconds timestamp of when this batch was assembled by the client.
`data`	`array`	required	The list of telemetry payloads to submit. Each entry follows the Telemetry Payload schema.

Example Request

{
  "batchId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1751989541000,
  "data": [
    {
      "payloadId": "550e8400-e29b-41d4-a716-446655440001",
      "carrier": "AZNG",
      "signalTimestamp": 1751989541000,
      "assetIdentifier": { "id": "MY-VEHICLE-01", "type": "TRACTOR", "operator": "AZNG" },
      "gps": {
        "latitude": 47.6062,
        "longitude": -122.3321,
        "speed": 88.5,
        "speedUnits": "KILOMETERS_PER_HOUR",
        "heading": 270.0,
        "inMotion": true
      }
    },
    {
      "payloadId": "550e8400-e29b-41d4-a716-446655440002",
      "carrier": "AZNG",
      "signalTimestamp": 1751989541000,
      "deviceIdentifier": { "id": "XIRGO-DEVICE-001", "manufacturer": "XIRGO", "model": "XT2460" },
      "signals": [
        {
          "id": "770e8400-e29b-41d4-a716-446655440000",
          "type": "OBD_LIFETIME_ODOMETER",
          "value": "245000.5",
          "valueUnit": "KILOMETERS",
          "assetPart": "ENGINE"
        }
      ]
    }
  ]
}

Response

Payloads are processed independently. Returns 202 Accepted when all payloads succeed, or 207 Multi-Status when one or more fail. Always check the failed list even on a 207.

Field	Type	Description
`requestId`	`string`	Unique request identifier for support.
`accepted`	`string[]`	payloadIds that were accepted. Present on 207 responses.
`failed`	`object[]`	Payloads that failed, with per-payload error detail.
`summary.total`	`integer`	Total payloads submitted.
`summary.accepted`	`integer`	Number accepted.
`summary.failed`	`integer`	Number failed.

Example Response — 202 All Accepted

{
  "requestId": "abc-123-def"
}

Example Response — 207 Partial Failure

{
  "requestId": "abc-123-def",
  "accepted": ["550e8400-e29b-41d4-a716-446655440001"],
  "failed": [
    {
      "payloadId": "550e8400-e29b-41d4-a716-446655440002",
      "errorType": "Validation",
      "errorMessage": "Payload contains invalid data",
      "validationErrorDetails": [
        { "field": "signalTimestamp", "message": "Field cannot be empty" }
      ]
    }
  ],
  "summary": { "total": 2, "accepted": 1, "failed": 1 }
}

Error Responses

Status	Description
`400`	Validation failed on the batch wrapper fields (e.g. missing `batchId`). Per-payload failures are returned in the 207 response body above.
`403`	Authentication failed. Verify your SigV4a signing and that requests are signed from your registered AWS account.
`500`	Internal error. Retry with exponential backoff. Retain data locally for back-filling.