Run in PostmanStatus PageContact SupportCustomer Ticket Portal
Guides

Air Tracking

Push complete, standardized air cargo tracking events into your TMS, ERP, data warehouse, or customer experience through one API. Air Tracking extends the Vizion visibility platform with purpose-built airline and forwarder data.

📘

Connection details

Base URL: https://air-prod.vizionapi.com

Authentication: X-API-Key header on every request

Interactive docs: https://air-prod.vizionapi.com/docs

Key capabilities

CapabilityDetail
Connections22 airlines + 7 forwarders
HAWB + MAWB linkingRegister a house waybill and Vizion auto-discovers the underlying master waybill, merging both into one chronological timeline
Airport coverage7,883 airports with canonical IATA codes and enriched locations
Polling frequencyEvery active shipment checked at least hourly

Quick start

Set your environment variables, then follow the five requests below to go from API key to live shipment.

export BASE_URL="https://air-prod.vizionapi.com"
export VIZION_API_KEY="<your-api-key>"

1. Create a webhook

curl -sS -X POST "$BASE_URL/v1/webhooks" \
  -H "X-API-Key: $VIZION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/air",
    "events": "[*]"
  }'
  • Required: url
  • Optional: events[], filter_awbs[], filter_carriers[]
  • The response includes the webhook id and an HMAC-SHA256 secret for verifying deliveries.
  • "events": "[*]" subscribes to all event types.

2. Test the webhook

curl -sS -X POST "$BASE_URL/v1/webhooks/$WEBHOOK_ID/test" \
  -H "X-API-Key: $VIZION_API_KEY"

A 200 response confirms a sample payload was sent to your endpoint.

3. List providers

curl -sS "$BASE_URL/v1/providers?kind=forwarder" \
  -H "X-API-Key: $VIZION_API_KEY"

Filter by kind=carrier or kind=forwarder. Results include code, name, kind, IATA prefix, polling interval, and active state.

4. Register a shipment

curl -sS -X POST "$BASE_URL/v1/shipments" \
  -H "X-API-Key: $VIZION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "awb": "BKK00011771",
    "forwarder": "KWE"
  }'
  • Required: awb
  • HAWBs require forwarder unless linked_mawbs[] is supplied.
  • MAWBs are auto-routed by AWB prefix -- no carrier code needed.
  • Returns 201 for a new registration. Safe to retry; a duplicate returns the same id with 200.

5. Fetch shipment details

curl -sS "$BASE_URL/v1/shipments/$SHIPMENT_ID" \
  -H "X-API-Key: $VIZION_API_KEY"

The response contains the enriched origin/destination, status, pieces, weight, estimated delivery, polling state, linked waybills, and the canonical event history.

API reference

Shipments

MethodEndpointCodesDescription
POST/v1/shipments201 / 200, 400Register shipment. Body: awb (required), forwarder, linked_mawbs[]. Returns id, AWB type, provider, status, and tracking links. Safe to retry.
GET/v1/shipments200, 400Search shipments. At least one filter required: awb, forwarder, status, active. Supports limit (1--100) and offset.
GET/v1/shipments/{id}200, 400 / 404Get shipment details. Returns enriched route, status, pieces/weight, ETA, polling state, linked waybills, and canonical event history.
DELETE/v1/shipments/{id}200, 400 / 404Stop tracking. Data is retained; the polling worker stops.

Providers

MethodEndpointCodesDescription
GET/v1/providers200List providers. Optional kind=carrier|forwarder. Returns code, name, kind, IATA prefix, adapter, poll interval, and active flag.

Webhooks

MethodEndpointCodesDescription
POST/v1/webhooks200Register webhook. Body: url (required), optional events[], AWB and carrier filters. Returns registration result with HMAC-SHA256 secret.
POST/v1/webhooks/{id}/test200Send test delivery. Sends a sample payload to the registered URL.
GET/v1/webhooks/{id}200Get webhook. Returns webhook configuration details.
PATCH/v1/webhooks/{id}200Update webhook. Partial update: any of url, events[], filters, is_active.
GET/v1/webhooks/{id}/deliveries200Get delivery log. Returns last 100 delivery attempts. Optional status filter.
DELETE/v1/webhooks/{id}200Deactivate webhook. Disables the webhook without deleting it.

Webhook events

EventDescription
shipment.createdA new shipment was registered
shipment.status_changedShipment status updated (default subscription)
shipment.deliveredShipment delivered to consignee
shipment.delayedShipment is delayed
shipment.timeline_changedEvents were added or modified in the timeline
shipment.deactivatedTracking was stopped
*Wildcard -- subscribe to all events

Canonical event codes

These codes standardize operational milestones across all air cargo providers. Each event includes the event_code, a canonical status, UTC timestamp, enriched location, flight_number, pieces, weight, and source waybill.

Booking, receipt, and movement

CodeDescription
BKDBooked for transport
RCDConsignment received
RCSReceived from shipper
MANManifested on the flight
PREPrepared for loading on the flight
AWRDocumentation received at this location
FOHFreight on hand
FWBFreight Waybill processed
DEPDeparted
TFDTransferred to another airline
RCTReceived from another airline

Transfer, arrival, and release

CodeDescription
TRMConsignment to be transferred to another airline
RFFRemoved from flight
RCFReceived from flight
ARRArrived at destination
NFDConsignee notified of the arrival
AWDDocumentation delivered to the consignee
CCDConsignment cleared by Customs
DLVDelivered to the consignee
DISDiscrepancy details
TGCTransferred to Customs/Government control

Sample response

A delivered MAWB shipment (Cargolux, CGO to FRA via LUX):

{
  "id": "0f1a9932-2ba8-4688-9435-45b6af79b392",
  "awb": "172-03592853",
  "awb_type": "mawb",
  "origin": {
    "iata_code": "CGO"
  },
  "destination": {
    "iata_code": "FRA"
  },
  "status": "delivered",
  "pieces": 10,
  "weight_kg": "656.00",
  "events": [
    {
      "timestamp": "2026-02-11T10:32:36.000Z",
      "status": "received",
      "event_code": "FOH",
      "description": "Freight on hand at origin",
      "location": { "iata_code": "CGO" },
      "flight_number": null
    },
    {
      "timestamp": "2026-02-11T18:41:00.000Z",
      "status": "departed",
      "event_code": "DEP",
      "description": "Departed from origin",
      "location": { "iata_code": "CGO" },
      "flight_number": "CV9733"
    },
    {
      "timestamp": "2026-02-12T09:47:00.000Z",
      "status": "arrived",
      "event_code": "ARR",
      "description": "Arrived at transfer station",
      "location": { "iata_code": "LUX" },
      "flight_number": "CV9733"
    },
    {
      "timestamp": "2026-02-12T17:29:00.000Z",
      "status": "departed",
      "event_code": "DEP",
      "description": "Departed from transfer station",
      "location": { "iata_code": "LUX" },
      "flight_number": "CV0007S"
    },
    {
      "timestamp": "2026-02-13T00:53:00.000Z",
      "status": "arrived",
      "event_code": "ARR",
      "description": "Arrived at destination",
      "location": { "iata_code": "FRA" },
      "flight_number": "CV0007S"
    },
    {
      "timestamp": "2026-02-15T21:29:00.000Z",
      "status": "delivered",
      "event_code": "DLV",
      "description": "Delivered to the consignee at destination",
      "location": { "iata_code": "FRA" },
      "flight_number": "CV0007S"
    }
  ]
}

Carrier coverage

Airlines (MAWB tracking)

AirlineIATAAWB prefixEventsFlight no.Pieces/weightCustoms
Lufthansa CargoLH020YesYesYesYes
American Airlines CargoAA001YesYesYesYes
Delta CargoDL006YesYesYesYes
United CargoUA016, 107, 215YesYesYesYes
AFKL Cargo (Air France-KLM)AF057, 074YesYesYesYes
Saudia CargoSV065YesYesYesYes
China Cargo AirlinesCK112YesYesYesYes
IAG Cargo (BA)BA125, 106, 145YesYesYesYes
Cathay Pacific CargoCX160YesYesYesYes
CargoluxCV172YesYesYesYes
Emirates SkyCargoEK176YesYesYesYes
Thai Airways CargoTG217YesYesYes--
MASkargo (Malaysia Airlines)MH232YesYesYesYes
Atlas Air5Y233, 369YesYesYesYes
Turkish CargoTK235YesYesYesYes
China Airlines CargoCI297YesYesYes--
Silk Way West Airlines7L501YesYesYesYes
Etihad CargoEY607YesYesYesYes
Singapore Airlines CargoSQ618YesYesYes--
EVA Air CargoBR695YesYesYesYes
Amerijet InternationalM8810YesYesYesYes

Forwarders (HAWB tracking)

ForwarderCodeEventsPieces/weightCustomsMAWB auto-discovery
Apex LogisticsAPEXYesYesYesYes
DB Schenker / DSVSCHENKERYesYesYes--
DHL Global ForwardingDHLGFYesYesYesYes
Expeditors InternationalEXPEDITORSYesYesYes--
Gati-KWEGATIKWEYesYesYes--
GeodisGEODISYesYesYesYes
Kintetsu World ExpressKWEYesYesYes--
TNT Express / FedExTNTFEDEXYesYesYes--

Updated 4 days ago

Did this page help you?