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 key for a short-lived access token. You will pass this token in the Authorization header on every subsequent call.

curl -X POST 'https://api.idrivelogistics.com/api/v1/auth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "YOUR_API_KEY"
  }'

The exact request shape for the token endpoint may vary; confirm against the live spec on idrivelogistics.readme.io. The important behaviors are: API keys are exchanged for bearer tokens, and the bearer token is required on every Tracking API call.

2. List recent trackers

Pass the access token as a bearer token, and pass your tenant's identifier in the x-tenant-id header. 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' \
  -H 'x-tenant-id: YOUR_TENANT_ID'

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' \
  -H 'x-tenant-id: YOUR_TENANT_ID'

Authentication

All Tracking API endpoints require two pieces of identification on every request.

Authorization header. A bearer token obtained by exchanging your API key against the auth endpoint. Tokens are short-lived; refresh them when you receive a 401 Unauthorized response.

Authorization: Bearer YOUR_ACCESS_TOKEN

Tenant header. A header identifying which tenant the request applies to. Trackers are always scoped to a single tenant — typically your 3PL tenant or one of your brand tenants.

x-tenant-id: YOUR_TENANT_ID

If you operate multiple tenants (for example, a 3PL parent with brand tenants underneath), you must set the correct x-tenant-id for each request. A token authorized for tenant A will return 403 Forbidden if used to read trackers under tenant B.

Environments

Sandbox accounts are issued on request and are pre-loaded with sample tenants and carrier accounts so you can exercise the full request/response shape without producing real labels. Contact your iDrive technical contact to request sandbox credentials.

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.

Lifecycle timestamps such as firstScanTime, pickupTime, outForDeliveryTime, deliveredTime, returnToSenderTime, and deliveryExceptionTime are populated as the corresponding events are received. Fields remain null until the carrier reports the matching event.

Endpoints

List trackers

GET /api/v1/trackers

Returns trackers for the tenant identified by x-tenant-id. Supports filtering, sorting, and pagination.

Headers

Query parameters

Example

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

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

Headers

Same as List trackers.

Example

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

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.

Statuses are intentionally coarse. Use the per-event entries in trackingDetails[] if you need finer-grained narration (for example, "Departed regional facility" or "Held by customs").

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 tenant header. A token issued for tenant A will not read trackers under tenant B. Multi-tenant 3PLs must set x-tenant-id per request based on the brand or 3PL whose data they are reading.
• 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.