API Documentation — TrackFlow

Authentication

All requests must include your API key in the request header.

Generate your API key from the TrackFlow Dashboard. Keep it secret — never expose it in client-side code.

# Pass your API key in the X-API-Key header
curl https://api.trackflow.io/v2/track/1Z204E380338943508 \
  -H "X-API-Key: tf_live_sk_xxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

const trackPackage = async (trackingNumber) => {
  const res = await fetch(
    `https://api.trackflow.io/v2/track/${trackingNumber}`,
    {
      headers: {
        'X-API-Key': 'tf_live_sk_xxxxxxxxxxxxxxxxxxxx',
        'Accept':    'application/json',
      },
    }
  );
  return res.json();
};

import requests

headers = {
    "X-API-Key": "tf_live_sk_xxxxxxxxxxxxxxxxxxxx",
    "Accept":    "application/json",
}
res = requests.get(
    "https://api.trackflow.io/v2/track/1Z204E380338943508",
    headers=headers,
)
data = res.json()

GET

/track/{trackingNumber}

Retrieve full tracking information for a single shipment including all events, estimated delivery, carrier details, and route.

Path Parameters

Parameter	Type	Required	Description
trackingNumber	string	Required	The carrier tracking number (e.g. `1Z204E380338943508`)

Query Parameters

Parameter	Type	Required	Description
carrier	string	Optional	Carrier code (e.g. `ups`, `fedex`). Auto-detected if omitted.
lang	string	Optional	Language for event descriptions. Default: `en`

Response — 200 OK

{
  "success": true,
  "tracking_number": "1Z204E380338943508",
  "carrier": {
    "code": "ups",
    "name": "UPS",
    "service": "UPS Ground"
  },
  "status": "in_transit",
  "status_description": "Package transferred to destination facility",
  "estimated_delivery": "2026-06-17T23:59:00Z",
  "origin": { "city": "Los Angeles", "country": "US" },
  "destination": { "city": "New York", "country": "US" },
  "events": [
    {
      "status": "Package transferred to destination facility",
      "location": "Louisville, KY",
      "timestamp": "2026-06-15T03:42:00Z",
      "type": "transit"
    }
  ],
  "last_updated": "2026-06-15T09:00:00Z"
}

POST

/track/batch

Track up to 50 shipments in a single API call. Returns results in the same order as the input array.

Batch requests are counted as individual tracking lookups against your rate limit quota.

Request Body

curl -X POST https://api.trackflow.io/v2/track/batch \
  -H "X-API-Key: tf_live_sk_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "shipments": [
      { "tracking_number": "1Z204E380338943508", "carrier": "ups" },
      { "tracking_number": "449044304137821",    "carrier": "fedex" }
    ]
  }'

const res = await fetch('https://api.trackflow.io/v2/track/batch', {
  method: 'POST',
  headers: {
    'X-API-Key':     'tf_live_sk_xxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    shipments: [
      { tracking_number: '1Z204E380338943508', carrier: 'ups'   },
      { tracking_number: '449044304137821',    carrier: 'fedex' },
    ],
  }),
});

GET

/carriers

Returns the full list of supported carriers with their codes, names, countries, and tracking number formats.

Response — 200 OK

{
  "count": 724,
  "carriers": [
    {
      "code":    "ups",
      "name":    "UPS",
      "country": "US",
      "type":    "express",
      "tracking_format": "^1Z[A-Z0-9]{16}$"
    },
    {
      "code":    "indiapost",
      "name":    "India Post EMS",
      "country": "IN",
      "type":    "postal",
      "tracking_format": "^[A-Z]{2}[0-9]{9}[A-Z]{2}$"
    }
  ]
}

POST

/webhooks

Subscribe to real-time push events for a tracking number. TrackFlow will POST to your endpoint when the shipment status changes.

Request Body Parameters

Parameter	Type	Required	Description
tracking_number	string	Required	The tracking number to subscribe to.
url	string	Required	Your HTTPS endpoint to receive event payloads.
events	string[]	Optional	Filter by event types: `delivered`, `exception`, `all`

Validate webhook payloads using the X-TrackFlow-Signature header (HMAC-SHA256 signed with your webhook secret).

DEL

/webhooks/{webhookId}

Unsubscribe and permanently delete a webhook subscription.

Parameter	Type	Required	Description
webhookId	string	Required	The webhook ID returned when the subscription was created.

Error Codes

The API uses standard HTTP status codes. All errors return a JSON body.

Status	Code	Description
400	invalid_tracking_number	The tracking number format is invalid for the specified carrier.
401	unauthorized	Missing or invalid API key.
404	not_found	No tracking data found for this number.
429	rate_limit_exceeded	You have exceeded your plan's request quota.
503	carrier_unavailable	The carrier's tracking API is temporarily unavailable.

Rate Limits

Requests are rate limited per API key per rolling 60-second window.

Plan	Requests / min	Requests / day	Batch size
Free	10	500	5
Starter	60	10,000	20
Growth	300	100,000	50
Enterprise	Unlimited	Unlimited	50

Rate limit status is returned in response headers: X-RateLimit-Remaining and X-RateLimit-Reset.

SDKs & Libraries

Official client libraries with full TypeScript support and auto-retry handling.

📦

Node.js / TypeScript

npm install @trackflow/sdk

🐍

Python

pip install trackflow

☕

Java

io.trackflow:sdk:2.0

💎

Ruby

gem install trackflow

Pricing

Start free. Scale as you grow. No contracts.

Free

$0 / month

500 lookups / day

All carriers
JSON responses
Email support

TrackFlow API Documentation