🚀 Getting started

Finxa Track API

A single, unified API for real-time shipment tracking across every major carrier. Integrate in minutes — send a tracking number, get back the full event timeline.

📦Universal tracking

DHL, FedEx, UPS, USPS, Aramex, and 1,500+ carriers — one endpoint.

🔑Simple auth

One API key in the header. No OAuth flows, no tokens to refresh.

⚡Built for speed

Median response under 400 ms. Rate-limit headers on every response.

Quick start

Track your first shipment in three steps.

1Create an account

2Generate an API key

Go to Dashboard → API Keys. Copy the key — it's shown only once.

3Make a request

Send a POST to /api/v1/track with your key and a tracking number.

cURL

curl -X POST https://api.track.finxa.ai/api/v1/track \
  -H "Content-Type: application/json" \
  -H "x-api-key: fxa_live_xxxxx.xxxxxxxxxxxxxxxxxx" \
  -d '{"trackingNumber": "9522760236"}'

Your full API key is displayed only once when you create it. We store a SHA-256 hash and can never retrieve the original. Treat it like a password — never commit it to source control or expose it in client-side code.

Key details

Property	Details
Format	`fxa_live_<prefix>.<secret>` — e.g. `fxa_live_e1e6b873.e1bc14a0...`
Header name	`x-api-key`
Default scope	`track:read`
Storage	SHA-256 hash — we never store the plaintext key.

Base URL

All API requests should be made to the following base URL.

Production

https://api.track.finxa.ai

ℹ️

Development

For local development, the API runs at http://localhost:8000. All endpoint paths remain the same.

Track a shipment

The core endpoint. Send a tracking number and get back the full shipment timeline including carrier, status milestones, locations, and timestamps.

POST/api/v1/track

Request body

Parameter	Type	Required	Description
`trackingNumber`	string	required	The carrier tracking number to look up. The carrier is auto-detected.

Example request

curl -X POST https://api.track.finxa.ai/api/v1/track \
  -H "Content-Type: application/json" \
  -H "x-api-key: fxa_live_xxxxx.xxxxxxxxxxxxxxxxxx" \
  -d '{"trackingNumber": "9522760236"}'

Response object

A successful request returns 201 Created with a JSON body containing the tracking data, event history, and delivery statistics.

Top-level structure

Field	Type	Description
`data.trackings[]`	array	Array of tracking results (usually one).
`tracking.trackingNumber`	string	The tracking number that was queried.
`tracking.courierCode`	string	Auto-detected carrier code (e.g. `dhl`, `fedex`).
`tracking.statusMilestone`	string	Current status: `info_received`, `in_transit`, `out_for_delivery`, `delivered`, `exception`.
`events[]`	array	Chronological list of tracking events.
`events[].status`	string	Human-readable status message from the carrier.
`events[].datetime`	string	ISO 8601 timestamp of the event.
`events[].location`	string	Location where the event occurred.
`statistics.timestamps`	object	Key timestamps: `infoReceivedDatetime`, `inTransitDatetime`, `deliveredDatetime`.

Example response · 201 Created

{
  "data": {
    "trackings": [
      {
        "tracking": {
          "trackingNumber": "9522760236",
          "courierCode": "dhl",
          "statusMilestone": "in_transit"
        },
        "events": [
          {
            "status": "Shipment picked up",
            "datetime": "2025-12-23T14:27:00.000Z",
            "location": "TAMPA - EAST - Florida - USA",
            "courierCode": "dhl",
            "statusMilestone": "in_transit"
          },
          {
            "status": "Processed at ORLANDO - USA",
            "datetime": "2025-12-23T22:30:00.000Z",
            "location": "ORLANDO - Florida - USA",
            "courierCode": "dhl",
            "statusMilestone": "in_transit"
          },
          {
            "status": "Arrived at DHL Sort Facility",
            "datetime": "2025-12-24T01:40:00.000Z",
            "location": "CINCINNATI HUB - Ohio - USA",
            "courierCode": "dhl",
            "statusMilestone": "in_transit"
          }
        ],
        "statistics": {
          "timestamps": {
            "infoReceivedDatetime": "2025-12-23T14:27:00-05:00",
            "inTransitDatetime": "2025-12-23T14:27:00-05:00",
            "deliveredDatetime": null
          }
        }
      }
    ]
  }
}

Error handling

The API uses standard HTTP status codes. Error responses always include a message field explaining what went wrong.

201CreatedTracking data returned successfully.

400Bad RequestMissing or invalid trackingNumber.

401UnauthorizedMissing or invalid API key.

429Too Many RequestsRate limit exceeded. See Retry-After header.

502Bad GatewayUpstream carrier lookup failed.

503Service UnavailableTracking provider is temporarily unavailable.

504Gateway TimeoutCarrier lookup timed out. Retry the request.

Error response · 401 Unauthorized

{
  "statusCode": 401,
  "message": "Invalid API key."
}

ℹ️

Tip

For 429 responses, read the Retry-After header to know how many seconds to wait before retrying.

Rate limits

Every response includes rate limit headers so you can track your usage in real time.

X-RateLimit-Limit

Maximum number of requests allowed in the current window.

X-RateLimit-Remaining

Number of requests remaining in the current window.

X-RateLimit-Reset

Unix timestamp when the rate limit window resets.

Retry-After

Seconds to wait before retrying (only on 429 responses).

⚠️

Monthly quota

Your plan includes a monthly request quota. Monitor usage from the dashboard or the GET /api/v1/usage endpoint.

Code examples

Copy-paste snippets for the most popular languages. Replace the API key with your own.

curl -X POST https://api.track.finxa.ai/api/v1/track \
  -H "Content-Type: application/json" \
  -H "x-api-key: fxa_live_xxxxx.xxxxxxxxxxxxxxxxxx" \
  -d '{"trackingNumber": "9522760236"}'

All endpoints

Complete list of available routes.

POST

/api/v1/trackLook up shipment status by tracking number.

GET

/api/v1/healthCheck API service status and availability.

GET

/api/v1/api-keysList all API keys for your organization.

POST

/api/v1/api-keysCreate a new API key.

DELETE

/api/v1/api-keys/:idRevoke an existing API key.

GET

/api/v1/usageView request volume and billable usage.

GET

/api/v1/logsInspect recent API request activity.