# iziTN API v2

Find shipment tracking numbers (UPS, FedEx, USPS, Evri, DPD) by destination and date, then
show the ones you want. Base URL: `https://api.izitn.com/v2`

Works with any AI agent or tool that can send HTTP requests: Claude, ChatGPT, Cursor, OpenClaw,
Hermes, n8n, or your own code. Give it this file and an API key.

- OpenAPI document: `https://api.izitn.com/v2/openapi.json`
- Interactive docs: `https://api.izitn.com/v2/docs`

## Authentication

Every request needs an API key, created on the website's API page (https://izitn.com/api):

```
Authorization: Bearer izi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Requests and responses are JSON (`Content-Type: application/json`).

## Credits

`availability`, `search` and `balance` are free. `show` costs 1 credit per tracking number,
unless this account already showed that number (then it is free and `charged` is `false`).

## Typical flow

1. `POST /v2/tn/availability` to find which days have tracking numbers (optional).
2. `POST /v2/tn/search` with the chosen dates: results carry a `token`, not the number.
3. `POST /v2/tn/show` with the `token` of each result you want: returns the tracking number.
4. `GET /v2/balance` to check your remaining credits.

## Filters (availability and search)

| Field | Type | Description |
|---|---|---|
| `country` | string | Destination country, ISO code (`US`, `GB`, `CA`, `FR`, `DE`, ...). Default `US`. |
| `carrier` | string | `ups`, `fedex`, `usps`, `evri`, `dpd`. US: ups, fedex, usps. GB: fedex, evri, dpd. CA, FR, DE, IT: fedex. Other countries: fedex, ups, usps. Leave out for every carrier (US and GB only). |
| `zipcode` | string | Destination zip code. Required for UPS, USPS, and FedEx in the US. 5 characters match exactly; otherwise the first 3 are matched. |
| `city` | string | Destination city, exact name (e.g. `LONDON`). Required for FedEx outside the US. |
| `uk_to_uk` | boolean | FedEx to the UK only: just shipments sent from the UK. Default `false`. |
| `ship_from`, `ship_to` | string | Ship date window, `YYYY-MM-DD`, both days included, 10 days at most. |
| `delivery_from`, `delivery_to` | string | Estimated delivery window, same format and limit. |
| `status` | string | `all`, `in_transit` or `delivered`. Default `all` when not sent. |

At least one date window is required. Giving both returns shipments matching both. A window
with only a start date covers that single day. Only tracking numbers nobody has used yet are returned.

## POST /v2/tn/availability (free)

The days of the date window that have at least one available tracking number. The days are
those of the ship window when one is given, else of the delivery window.

```bash
curl -X POST https://api.izitn.com/v2/tn/availability \
  -H "Authorization: Bearer $IZITN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country": "US", "carrier": "ups", "zipcode": "55117",
       "delivery_from": "2026-10-14", "delivery_to": "2026-10-20"}'
```

```json
{"date_type": "delivery", "days": ["2026-10-14", "2026-10-15", "2026-10-17"]}
```

## POST /v2/tn/search (free)

Shipments matching the filters, sorted by estimated delivery date. Extra fields:
`order` (`asc` default, or `desc`), `page` (default 1), `page_size` (1 to 50, default 10).

```bash
curl -X POST https://api.izitn.com/v2/tn/search \
  -H "Authorization: Bearer $IZITN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country": "GB", "carrier": "fedex", "city": "LONDON",
       "delivery_from": "2026-10-14", "delivery_to": "2026-10-20", "page_size": 20}'
```

```json
{
  "total": 37, "page": 1, "page_size": 20,
  "results": [
    {
      "token": "gAAAAABn...",
      "carrier": "fedex",
      "status_code": "in_transit", "status_label": "In transit",
      "ship_date": "2026-10-11", "scheduled_delivery": "2026-10-15",
      "origin": "MEMPHIS, TN", "destination": "LONDON",
      "zipcode": "", "weight": 1.2, "weight_unit": "LB"
    }
  ]
}
```

`status_code` is `pending` (label created), `in_transit`, `delivered` or `unknown`.
A `token` is valid for 24 hours.

## POST /v2/tn/show (1 credit)

```bash
curl -X POST https://api.izitn.com/v2/tn/show \
  -H "Authorization: Bearer $IZITN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "gAAAAABn..."}'
```

```json
{"tracking_number": "794658322104", "carrier": "fedex", "charged": true, "credit_balance": 49}
```

## GET /v2/balance (free)

```bash
curl https://api.izitn.com/v2/balance -H "Authorization: Bearer $IZITN_API_KEY"
```

```json
{"credit_balance": 49}
```

## Errors

Every error has this body, with an HTTP status:

```json
{"error": {"code": "invalid_request", "message": "Enter a zip code to search."}}
```

| Status | Code | Meaning |
|---|---|---|
| 400 | `invalid_request` | A filter is missing or wrong (no date window, no zip code or city, carrier not offered for the country, window over 10 days, ...). |
| 400 | `invalid_token` | The search result token is malformed or expired (tokens last 24 hours): search again. |
| 401 | `missing_api_key` | No `Authorization: Bearer <api key>` header. |
| 401 | `invalid_api_key` | The API key doesn't exist (mistyped, or deleted). |
| 402 | `insufficient_credits` | Not enough credits to show a tracking number: buy more on the website. |
| 403 | `api_key_disabled` | The API key was disabled on the website's API page. |
| 403 | `account_disabled` | The account that owns the API key is disabled. |
| 404 | `not_found` | The shipment of this result token no longer exists, or the URL is wrong. |
| 422 | `validation_error` | The request body or a parameter has the wrong type or format. |
| 429 | `rate_limited` | More than 60 requests in 60 seconds with this key: wait `Retry-After` seconds. |
| 500 | `internal_error` | Unexpected error on our side: try again, then contact success@izitn.com. |

`message` is readable as is. On `rate_limited`, wait the number of seconds in the `Retry-After`
header. On `invalid_token`, run the search again to get fresh tokens.