🚀 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).

Shipment object — `trackings[].shipment`

Field	Type	Description
`shipmentId`	string	Unique identifier for this shipment lookup.
`statusCode`	string	Detailed status code, e.g. `delivery_delivered`, `exception_return`.
`statusCategory`	string	Broad category: `transit`, `delivery`, `exception`, `customs`, `data`.
`statusMilestone`	string	Normalized lifecycle stage: `info_received`, `in_transit`, `out_for_delivery`, `delivered`, `exception`.
`originCountryCode`	string \| null	ISO country code for the origin (e.g. `PT`, `US`).
`destinationCountryCode`	string \| null	ISO country code for the destination (e.g. `BH`).
`trackingNumbers`	array	Array of objects with `tn` — the tracking number(s) for this shipment.
`delivery`	object	Delivery details: `estimatedDeliveryDate`, `courierEstimatedDeliveryDate`, `service`, `signedBy`.
`recipient`	object	Recipient info when available: `name`, `address`, `postCode`, `city`, `subdivision`.

Event object — `trackings[].events[]`

Field	Type	Description
`eventId`	string	Unique identifier for this event.
`trackingNumber`	string	The tracking number this event belongs to.
`status`	string	Human-readable status message from the carrier.
`occurrenceDatetime`	string	ISO 8601 timestamp with the original timezone offset.
`datetime`	string	ISO 8601 timestamp in UTC.
`utcOffset`	string	UTC offset of the event location, e.g. `+03:00`.
`location`	string \| null	Location where the event occurred.
`courierCode`	string	Auto-detected carrier code (e.g. `dhl`, `fedex`).
`statusCode`	string \| null	Detailed status code for this event, if available.
`statusCategory`	string \| null	Broad status category for this event.
`statusMilestone`	string	Normalized milestone: `info_received`, `in_transit`, `out_for_delivery`, `delivered`, `exception`.

Statistics — `trackings[].statistics.timestamps`

Field	Type	Description
`infoReceivedDatetime`	string \| null	When the carrier first received shipment information.
`inTransitDatetime`	string \| null	When the package entered transit.
`outForDeliveryDatetime`	string \| null	When the package went out for delivery.
`failedAttemptDatetime`	string \| null	When a delivery attempt failed, if applicable.
`availableForPickupDatetime`	string \| null	When the package became available for pickup, if applicable.
`exceptionDatetime`	string \| null	When an exception was raised, if applicable.
`deliveredDatetime`	string \| null	When the package was delivered.

Example response · 201 Created

{
  "data": {
    "trackings": [
      {
        "shipment": {
          "shipmentId": "aef5f38c-59ff-44e3-80cd-9769aa55c19b",
          "statusCode": "delivery_delivered",
          "statusCategory": "delivery",
          "statusMilestone": "delivered",
          "originCountryCode": "PT",
          "destinationCountryCode": "BH",
          "delivery": {
            "estimatedDeliveryDate": null,
            "courierEstimatedDeliveryDate": null,
            "service": "International Priority",
            "signedBy": null
          },
          "trackingNumbers": [{ "tn": "887393928990" }],
          "recipient": {
            "name": null,
            "address": null,
            "postCode": null,
            "city": null,
            "subdivision": null
          }
        },
        "events": [
          {
            "eventId": "bc2eacfb-f1e1-4ab0-9e3d-4850f292a21e",
            "trackingNumber": "887393928990",
            "eventTrackingNumber": "887393928990",
            "status": "Delivered",
            "occurrenceDatetime": "2025-12-27T13:53:00+03:00",
            "datetime": "2025-12-27T13:53:00.000Z",
            "hasNoTime": false,
            "utcOffset": "+03:00",
            "location": "SANAD BH",
            "sourceCode": "fedex-tracking",
            "courierCode": "fedex",
            "statusCode": "delivery_delivered",
            "statusCategory": "delivery",
            "statusMilestone": "delivered"
          },
          {
            "eventId": "95836879-868d-4370-8d80-f46f66d337fc",
            "trackingNumber": "887393928990",
            "eventTrackingNumber": "887393928990",
            "status": "On FedEx vehicle for delivery",
            "occurrenceDatetime": "2025-12-27T08:01:00+03:00",
            "datetime": "2025-12-27T08:01:00.000Z",
            "hasNoTime": false,
            "utcOffset": "+03:00",
            "location": "MUHARRAQ BH",
            "sourceCode": "fedex-tracking",
            "courierCode": "fedex",
            "statusCode": "delivery_out_for_delivery",
            "statusCategory": "delivery",
            "statusMilestone": "out_for_delivery"
          },
          {
            "eventId": "4248720d-7abe-4ea7-9fcf-97ca366e58cd",
            "trackingNumber": "887393928990",
            "eventTrackingNumber": "887393928990",
            "status": "Picked up",
            "occurrenceDatetime": "2025-12-24T16:31:00+00:00",
            "datetime": "2025-12-24T16:31:00.000Z",
            "hasNoTime": false,
            "utcOffset": "+00:00",
            "location": "MAIA PT",
            "sourceCode": "fedex-tracking",
            "courierCode": "fedex",
            "statusCode": "transit_handover",
            "statusCategory": "transit",
            "statusMilestone": "in_transit"
          }
        ],
        "statistics": {
          "timestamps": {
            "infoReceivedDatetime": "2025-12-24T02:49:08-06:00",
            "inTransitDatetime": "2025-12-24T16:31:00+00:00",
            "outForDeliveryDatetime": "2025-12-27T08:01:00+03:00",
            "failedAttemptDatetime": null,
            "availableForPickupDatetime": null,
            "exceptionDatetime": null,
            "deliveredDatetime": "2025-12-27T13:53:00+03:00"
          }
        }
      }
    ]
  }
}

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.