Multi-carrier tracking,
one API.

Every request must include your API key in the x-api-key header. There is no query-param or Bearer-token alternative.

x-api-key: tp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A missing key returns 401 MISSING_API_KEY; one that matches no key returns 401 INVALID_API_KEY. A paused or expired key returns 403 API_KEY_PAUSED or 403 API_KEY_EXPIRED. If verification itself is briefly unavailable you get 503 AUTH_UNAVAILABLE with a Retry-After header - retry; nothing has happened to your key. Keys are issued and revoked on request - if yours stops working unexpectedly, contact us before assuming it's a bug.

Pass one of these names as carrier, or the carrier ID a response returned in courier. Letter case is ignored.

Stale answers. When a carrier can't be reached, the API may answer with the last status it read for that number, up to 24 hours past its freshness window, instead of an error. That answer still has success: true, but carries stale: true, staleReason and dataAgeSeconds, and its cacheExpiresIn is 0. Show it as the last known status with its age, not as the current one, and wait a few minutes before asking again: every call is charged, and a carrier that was unreachable a moment ago usually still is.

Responses are private to your key: every one is sent with Cache-Control: private, no-store, so don't put a shared cache in front of these calls.

Errors share this shape:

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "No tracking data found for V3501635425"
}

A few add fields. NOT_FOUND can carry suggestedCarrier (a carrier ID you can send straight back as carrier) and suggestedCarrierName when the number looks like another carrier's. API_KEY_EXPIRED carries expiresAt, and UPSTREAM_RATE_LIMITED carries retryAfterSeconds.

Two ceilings apply, both set by your plan: a per-minute rate limit and a monthly call allowance. Exceeding either returns 429 with a Retry-After header - RATE_LIMITED for the per-minute one, QUOTA_EXCEEDED for the monthly one. Separately, each client address may send up to 60 requests a minute with an unknown, paused or expired key; past that, requests from that address get 429 RATE_LIMITED until the minute is up, whichever key they carry.

Responses to admitted tracking lookups carry X-Quota-Limit, X-Quota-Used and X-Quota-Reset, so you can watch your own budget rather than discover the ceiling by hitting it. Quota headers are not present on every response: early validation and authentication failures, rate-limited requests, and other error responses returned before the quota check may omit them. Each key renews monthly on its own creation-date anniversary, at the same UTC time it was issued. Need a higher one? Ask us.

Check your plan, limits, and usage without placing a tracking call. Same x-api-key header as /api/v1/track, and it never counts against your monthly allowance.

curl "https://www.trackparcel.in/api/v1/usage" \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "success": true,
  "plan": "growth",
  "paused": false,
  "expired": false,
  "expiresAt": "2027-01-15T18:29:59.999Z",
  "rateLimitPerMinute": 60,
  "monthlyCallQuota": 15000,
  "extraCalls": 0,
  "used": 4213,
  "remaining": 10787,
  "resetsAt": "2026-09-15T08:30:00.000Z",
  "totalRequests": 88210,
  "lastUsedAt": "2026-08-19T03:41:00.000Z"
}

remaining and monthlyCallQuota are null on an unmetered plan. extraCalls is any allowance added to your key on top of the plan quota for the current billing period: it is already counted in remaining and in the X-Quota-Limit header, and it ends at resetsAt.

This endpoint has its own limit of 30 requests per minute per key, whatever your plan, separate from the /api/v1/track limit. It stays reachable even if your key has been paused or has expired, so you can always see why tracking calls are refused: paused and expired say which applies, and expiresAt is when the key stops working (null if it doesn't expire).