Parameters
| Query parameter | Meaning | Example |
|---|---|---|
bookingReference | The booking reference Airlift issued for the shipment. | AIRLAMD132196 |
Send Authorization: Bearer <token> with every request. The token comes from the OAuth 2.0 client credentials flow and must carry the documents:read scope.
Example request
curl 'https://api.airliftusa.com/api/v1/api-service/external/documents?bookingReference=AIRLAMD132196' \
--header 'Authorization: Bearer YOUR_TOKEN'Example response (200)
[
{
"id": "ENCODED_DOC_ID",
"document_type": "Booking Copy",
"file_name": "BKGCONF_CAD0840707_pdf_513_2025-10-27_05:44:37.pdf",
"file_link": "https://api.airliftusa.com/api/v1/api-service/external/documents/ENCODED_DOC_ID/download",
"file_metadata": { "size": 28660, "uploaded_at": "2025-10-27T11:14:32Z" },
"memo": null
}
]- file_link is the download URL for the file; send the same bearer token when fetching it.
- file_metadata.size is in bytes and uploaded_at is UTC.
Other status codes: 400 missing or invalid parameter, 401 token missing or expired, 403 scope not granted, 404 nothing matches the reference, 500 server error. Limits are 60 requests a minute and 4,000 an hour per consumer, reported in the X-RateLimit-* headers.
Frequently asked questions
Which documents come back?
Whatever is attached to the booking in the Airlift system, each labelled with its document_type, such as the booking copy.
Do I need a separate scope to download?
No. The documents:read scope covers both the listing and the download link it returns.
Other endpoints
- GET /trackntrace · Track & Trace Events
- GET /booking · Ocean Booking
- POST /bookings · Ocean Booking Service
- GET /invoices · Invoices Data Service
- GET /invoice · Invoice Data
- All API documentation
- Free tariff API
Need access? Register your application in the developer portal; the API is open to approved Airlift customers.