Migration from v1

What's changing

Endpoint changes

If you are currently using a direct API Gateway URL (e.g. https://1hzxpvs4r6.execute-api.us-east-1.amazonaws.com/Prod/accioGPS), migrate to the regional endpoints above.

Authentication changes

Old: SigV4 + x-api-key header (value provided during onboarding).

New: SigV4a only. The x-api-key header is no longer needed — remove it. Access is controlled via the gateway access policy registered during onboarding.

Update your signing logic from SigV4 to SigV4a. If you use an AWS SDK, ensure you are using a version that supports SigV4a. See the Authentication guide for a working Java code sample.

Payload changes

v1 request body

{
  "assetId": "TRUCK-001",
  "assetType": "BOX_TRUCK",
  "assetOwnerId": "AZNG",
  "carrierId": "AZNG",
  "timestamp": 1694466000000,
  "provider": "MY_PROVIDER",
  "position": {
    "latitude": "12.8625706",
    "longitude": "80.0736267"
  },
  "deviceTelemetryData": {
    "inMotion": true,
    "altitude": "123",
    "accelerometerX": "0.5",
    "accelerometerY": "0.3",
    "accelerometerZ": "1.0",
    "heading": "180",
    "gpsSatelliteCount": "16",
    "hdop": "0.6"
  }
}

v2 request body (single)

{
  "payloadId": "550e8400-e29b-41d4-a716-446655440000",
  "carrier": "AZNG",
  "signalTimestamp": 1694466000000,
  "assetIdentifier": { "id": "TRUCK-001", "type": "BOX_TRUCK", "operator": "AZNG" },
  "gps": {
    "latitude": 12.8625706,
    "longitude": 80.0736267,
    "inMotion": true,
    "altitude": 123.0,
    "altitudeUnits": "METERS",
    "accelerometerX": 0.5,
    "accelerometerY": 0.3,
    "accelerometerZ": 1.0,
    "accelerometerUnits": "METERS_PER_SECOND_SQUARED",
    "heading": 180.0,
    "satelliteCount": 16,
    "hdop": 0.6
  }
}

v2 request body (batch)

{
  "batchId": "batch-20240901-001",
  "timestamp": 1694466000000,
  "data": [
    {
      "payloadId": "550e8400-e29b-41d4-a716-446655440001",
      "carrier": "AZNG",
      "signalTimestamp": 1694466000000,
      "assetIdentifier": { "id": "TRUCK-001", "type": "BOX_TRUCK", "operator": "AZNG" },
      "gps": {
        "latitude": 12.8625706,
        "longitude": 80.0736267,
        "inMotion": true,
        "altitude": 123.0,
        "altitudeUnits": "METERS",
        "heading": 180.0,
        "satelliteCount": 16,
        "hdop": 0.6
      }
    },
    {
      "payloadId": "550e8400-e29b-41d4-a716-446655440002",
      "carrier": "AZNG",
      "signalTimestamp": 1694466060000,
      "assetIdentifier": { "id": "TRUCK-002", "type": "TRAILER", "operator": "AZNG" },
      "gps": { "latitude": 13.0, "longitude": 80.25, "inMotion": false }
    }
  ]
}

Field mapping reference

Top-level fields

At least one of assetIdentifier or deviceIdentifier must be provided. At least one of gps, signals, or deviceDiagnostics must be provided.

assetIdentifier constraint: id, type, and operator must all be provided together or all omitted. If omitting the full assetIdentifier, provide a deviceIdentifier instead (new in v2 — used when identifying the asset via the telematics device rather than the asset itself).

GPS / position fields

See GPS for the full field reference.

Units fields

If you submit a field that has a corresponding units field, you must also provide the units value. See Unit Types for the full list of accepted values per enum.

Response changes

The single endpoint returns 202 Accepted with a requestId. The batch endpoint returns 200 OK with a per-record breakdown — check the failed list to handle partial failures.

{
  "requestId": "abc-123-def",
  "responseCode": 202,
  "accepted": ["payloadId-1"],
  "failed": [
    {
      "payloadId": "payloadId-2",
      "errorType": "Validation",
      "errorMessage": "Payload contains invalid data",
      "validationErrorDetails": [
        { "field": "gps.latitude", "message": "Field must be not less than -90.0" }
      ]
    }
  ],
  "summary": { "total": 2, "accepted": 1, "failed": 1 }
}

FAQ

How do I test before switching production traffic?

Use the Gamma endpoints to validate your integration first. See Getting Started for the full endpoint list.

What happens if I send String values for latitude/longitude?

The new API expects Doubles. Sending Strings will result in a 400 ValidationException.

Is the batch endpoint required?

No. The single endpoint works exactly as before — one record per request. Batch is optional and recommended for high-volume clients.

Do I need to keep the x-api-key header?

No — remove it entirely. Authentication is handled via SigV4a request signing. Any identity within your registered AWS account is authorized.