Tracking API Guide

Overview

The Tracking API provides a normalized, real-time view of every package moving through the iDrive network. When a label is purchased through iDrive, a tracker is automatically created and associated with the shipment — no additional setup required on your end. For carriers that don't support automatic tracker creation, iDrive handles the setup manually. From there, iDrive receives carrier scan events on your behalf, normalizes them across carriers, and surfaces the latest shipment state through the Tracking API.
The Tracking API is read-only. Tracker records are created server-side as a side effect of label purchase. You do not need to call any endpoint to create or register a tracker.
Supported carriers include USPS, UPS, FedEx, DHL eCommerce, Amazon Shipping, GLS, OSM, ePost Global, DoorDash, and SpeedX. Scan event availability and depth vary by carrier.

Quickstart

The minimum path to your first tracker takes three steps.

1. Get an access token

Exchange your API client credentials for a short-lived access token using the machine-to-machine (M2M) token endpoint. You will pass the returned token in the Authorization header on every subsequent call. The token is scoped to the tenantId you include in the request body, so no separate tenant header is required on downstream calls.

curl -X POST 'https://api.idrivelogistics.com/api/v1/tokens/m2m' \
  -H 'Content-Type: application/json' \
  -d '{
    "grantType": "clientCredentials",
    "clientId": "YOUR_API_CLIENT_ID",
    "clientSecret": "YOUR_API_CLIENT_SECRET",
    "tenantId": "YOUR_TENANT_ID"
  }'

Confirm the exact response shape on idrivelogistics.readme.io. The important behaviors are: client credentials are exchanged for a short-lived bearer token, the token is scoped to the tenantId supplied in the request, and the bearer token is required on every Tracking API call.

2. List recent trackers

Pass the access token as a bearer token. The example below returns trackers most recently created first.

curl 'https://api.idrivelogistics.com/api/v1/trackers?sort=createdAt:desc' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

3. Get a single tracker by ID

Once you know a tracker's ID — for example, from the list call above or from the tracker ID returned at label purchase time — fetch its full state directly.

curl 'https://api.idrivelogistics.com/api/v1/trackers/{trackerId}' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Authentication

The Tracking API uses OAuth 2.0 client credentials (machine-to-machine) for authentication. API consumers exchange a client ID and client secret for a short-lived bearer token, then send that token on every API request.

Token endpoint. POST /api/v1/tokens/m2m

Request body.

{
  "grantType": "clientCredentials",
  "clientId": "YOUR_API_CLIENT_ID",
  "clientSecret": "YOUR_API_CLIENT_SECRET",
  "tenantId": "YOUR_TENANT_ID"
}

The tenantId in the request body scopes the resulting token to a single tenant — typically your 3PL tenant or one of your brand tenants. Because the tenant is bound to the token, you do not send a separate tenant header on Tracking API requests. If you operate multiple tenants (for example, a 3PL parent with brand tenants underneath), mint a separate token per tenant and use the appropriate token for each request. A token minted for tenant A will return 403 Forbidden if used to read trackers under tenant B.

Authorization header. Pass the token returned by /api/v1/tokens/m2m as a bearer token on every Tracking API call.

Authorization: Bearer YOUR_ACCESS_TOKEN

Tokens are short-lived; refresh them by re-calling /api/v1/tokens/m2m when you receive a 401 Unauthorized response.

The x-tenant-id header is part of iDrive's human (Auth0) login flow and is not used by API consumers. M2M tokens carry the tenant internally — including x-tenant-id on Tracking API requests is unnecessary.

Environments

Test-mode labels (mode: "TEST") generate trackers, but tracking events for test labels are limited compared to production. Expect a small number of synthetic events and not a full delivery lifecycle. The window is very short so we recommend trying to capture those tracking events right after you purchase a label in TEST mode. When you switch the mode to "LIVE", then you will be begin to see fully delivery lifecycle tracking updates.

The Tracker resource

A tracker represents a single package's tracking record. It carries the tracking number, the most recent status, the carrier, references back to the shipment and label, and metadata about origin and destination.
The fields below reflect the conceptual data model.

Endpoints

List trackers

GET /api/v1/trackers

Returns trackers for the tenant bound to your access token. Supports filtering, sorting, and pagination.
Headers

curl --request GET \
     --url https://api.beta.idrivelogistics.com/api/v1/trackers \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response — 200 OK

{
  "items": [
    {
      "id": "string",
      "tenantId": "string",
      "labelId": "string",
      "shipmentId": "string",
      "onBehalfOfId": "string",
      "externalTrackerId": "string",
      "provider": "EASYPOST",
      "carrier": "USPS",
      "serviceLevel": "string",
      "senderCountryCode": "string",
      "senderPostalCode": "string",
      "recipientCountryCode": "string",
      "recipientPostalCode": "string",
      "carrierAccountId": "string",
      "trackingNumber": "string",
      "isInternal": true,
      "status": "PRE_TRANSIT",
      "events": [
        {
          "status": "PRE_TRANSIT",
          "externalShipmentId": "string",
          "previousStatus": "PRE_TRANSIT",
          "providerStatus": "string",
          "location": "string",
          "city": "string",
          "stateProvince": "string",
          "postalCode": "string",
          "country": "string",
          "carrierMessage": "string",
          "eventDate": "2026-05-14T19:35:40.788Z",
          "id": "string",
          "createdAt": "2026-05-14T19:35:40.788Z",
          "updatedAt": "2026-05-14T19:35:40.788Z"
        }
      ],
      "createdAt": "2026-05-14T19:35:40.788Z",
      "updatedAt": "2026-05-14T19:35:40.788Z"
    }
  ],
  "itemCount": 0,
  "totalItems": 0,
  "pageNumber": 0,
  "nextPageToken": "string"
}

Get a tracker by ID

GET /api/v1/trackers/{id}

Returns the full tracker record for a single ID. Use this when you already have the tracker ID in hand — for example, from the response to a label purchase.
Path parameters

curl 'https://api.idrivelogistics.com/api/v1/trackers/trk_01HZX3ABCDEF' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response — 200 OK returns a single tracker object with the same shape as an item in the list response.
A 404 Not Found is returned if the tracker does not exist or if it exists under a tenant your token is not authorized to read.

Tracker statuses

iDrive normalizes carrier-specific status codes into a single set of values. Build your application logic against these normalized values rather than against carrier-specific strings, which vary across carriers and change without notice.

Filtering, sorting, and pagination

The list endpoint accepts a familiar query-string convention.
Filtering. The filter parameter accepts an expression in the form field<comparator>value. Use == for equality. Example:

filter=carrier==AMZN_US

Confirm the full set of supported fields and comparators against the live spec; in practice, filtering by carrier, currentStatus, and time fields is the most common pattern.
Sorting. The sort parameter takes one or more field:direction clauses. Example:

sort=createdAt:desc

Pagination. The list endpoint returns a nextCursor value when more results are available. Pass it back as the cursor query parameter to retrieve the next page. Iterate until nextCursor is omitted from the response.

Errors and troubleshooting

The Tracking API uses standard HTTP status codes. Error bodies share a common envelope:

{
  "message": "You do not have permission to access this connection",
  "statusCode": 403,
  "errors": [],
  "correlationId": "5jBjAM+2TDWDjsnOJI/SsA/0000000975"
}

When opening a support ticket, always include the correlationId from the failing response. It is the fastest way for the iDrive team to find the corresponding request in our logs.

Common status codes

Troubleshooting checklist

When a Tracking API call is not behaving as expected, work through this list before opening a ticket.

• Confirm the environment. Production uses api.idrivelogistics.com. The sandbox uses api.beta.idrivelogistics.com. Pointing a sandbox tenant ID at production (or vice versa) will return 403 or 404.
• Confirm the token's tenant. A token is minted for a single tenant — the tenantId value you sent to /api/v1/tokens/m2m. A token minted for tenant A will not read trackers under tenant B. Multi-tenant 3PLs must mint a separate token per tenant and use the right token for each request.
• Confirm tracking is enabled for the carrier account. If you create a label and never see tracker updates, verify with iDrive that tracking webhooks are enabled for the underlying carrier account. Test-mode labels in particular have limited tracking in sandbox.
• Allow time for the first event. A tracker created at the moment of label purchase will report PRE_TRANSIT until the carrier produces its first scan. The gap can be from minutes to over a day depending on carrier and pickup cadence.
• Treat carrier strings as opaque. When parsing lastLocation, prefer the trackingDetails[*].location field on individual events rather than re-parsing lastLocation, which is a display string. If you must parse it, the convention for US scans is City, State, Zip — a missing component is rendered as null.
• Use correlationId when escalating. The single most useful thing in a support ticket is the correlation ID from the failing response.

Need help?

• Live API reference and try-it-out: idrivelogistics.readme.io
• Sandbox access, rate-limit increases, or anything else: contact your iDrive contact.