Tracking API Guide

Pull: Fetch tracker data whenever you need it, by listing trackers or looking one up by ID.

📘

Prefer to have updates sent to you automatically? (RECOMMENDED)

See the Webhooks guide to get tracking updates pushed to your endpoint.

Overview

The Tracking API gives you a normalized view of every package shipped through iDrive. When you buy a label, iDrive creates a tracker for it automatically. You don't need to register anything. iDrive collects carrier scans, normalizes them across carriers, and exposes the latest state through this API.

The API is read-only.

Supported carriers include USPS, UPS, FedEx, DHL eCommerce, Amazon Shipping, GLS, OSM, ePost Global, DoorDash and SpeedX. Scan detail varies by carrier.

3PLs: a token for your 3PL tenant returns trackers for every merchant under it. Each tracker's tenantId tells you which merchant it belongs to. You don't need a separate token per merchant.

Quickstart

1. Get an access token

Create an API key in the iDrive TMS under Settings > API Keys and choose Full access. Read-only keys can't read trackers.

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"
  }'

2. List recent trackers

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

3. Get one tracker

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

Authentication

Exchange your client ID and secret for a bearer token, then send it on every request.

Endpoint: POST /api/v1/tokens/m2m

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

• tenantId is optional and defaults to your key's tenant.
• A token reads trackers for its tenant and every tenant under it. 3PLs should use their 3PL tenant.
• Tokens last 1 hour. Request a new one before the current one expires, or when you get a 401.
• Don't send an x-tenant-id header. It's only used for logging in to the web app. The token already carries your tenant.

Authorization: Bearer YOUR_ACCESS_TOKEN

Environments

The sandbox uses its own account and API keys. Ask your iDrive contact for sandbox credentials. Sandbox accounts come with sample tenants and carrier accounts.

Test labels: labels with mode: "TEST" create trackers, but only a few synthetic events arrive, shortly after purchase. Check right after you buy the label. LIVE labels show the full delivery lifecycle.

The Tracker resource

One tracker per package.

Each event in events[]:

Endpoints

List trackers

GET /api/v1/trackers

{
  "items": [
    {
      "id": "clx9abc123def456",
      "tenantId": "merchant-tenant-id",
      "onBehalfOfId": "merchant-tenant-id",
      "labelId": "string",
      "shipmentId": "string",
      "trackingNumber": "9400100000000000000000",
      "carrier": "USPS",
      "serviceLevel": "USPS_PRIORITY",
      "provider": "EASYPOST",
      "externalTrackerId": "string",
      "carrierAccountId": "string",
      "status": "IN_TRANSIT",
      "senderCountryCode": "US",
      "senderPostalCode": "84101",
      "recipientCountryCode": "US",
      "recipientPostalCode": "10001",
      "events": [
        {
          "id": "string",
          "status": "IN_TRANSIT",
          "previousStatus": "PRE_TRANSIT",
          "providerStatus": "string",
          "eventDate": "2026-05-14T19:35:40.788Z",
          "location": "SALT LAKE CITY, UT, 84101",
          "city": "SALT LAKE CITY",
          "stateProvince": "UT",
          "postalCode": "84101",
          "country": "US",
          "carrierMessage": "Departed USPS facility",
          "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": 1,
  "pageNumber": 0,
  "nextPageToken": "string"
}

To page through results, pass nextPageToken back as pageToken. Stop when nextPageToken is missing.

Get a tracker by ID

GET /api/v1/trackers/{id}

This returns one tracker with the same fields as above. It returns 404 if the tracker doesn't exist or isn't under your tenant.

Tracker statuses

Build your logic on these values, not on carrier strings.

For more detail, use carrierMessage on each event.

Errors and troubleshooting

Error responses include message, statusCode, errors and correlationId. Include the correlationId when you contact support.

Checklist:

• Right environment? Sandbox keys don't work in production, and production keys don't work in the sandbox.
• Right tenant? Your token sees its own tenant and every tenant under it, but not tenants outside that tree.
• No updates? A new tracker stays PRE_TRANSIT until the first carrier scan, which can take minutes or more than a day. If it never updates, ask iDrive to confirm tracking is turned on for that carrier account.
• Test label? Test labels only get a few events, right after purchase.

Need help?

• API reference: idrivelogistics.readme.io
• Sandbox access, rate limits or anything else: contact your iDrive contact.