Shipments carry documents — shipping labels, invoices, customs declarations — added by you at creation, generated by Perform.AI, or issued by carriers through booking. Two endpoints retrieve them; full specs in the API reference: List Documents and Retrieve a Document.
List documents across Shipments
GET /v5/shipments/documents/ returns the documents of up to 10 Shipments per request. Identify them with either shipment_uuids or shipment_ids — never both — comma-joined without spaces:
Each document comes with its Shipment context, metadata (name, type, file_format, created_date, additional_info), and a download_url. Results are page-based: limit 25–100 (default 25), page from 1, with total_pages in the response. No matching documents returns HTTP 200 with an empty data array.
Retrieve one document
GET /v5/shipments/documents/{document_uuid}/ fetches a single document by the document_uuid you got from a listing, a Shipment’s details, or a booking response:
This endpoint returns the document two ways: the download_url and a base64_content string — use the latter when you want the bytes without a second fetch. An unknown UUID returns HTTP 404 ("No document is found").
Rules to build around
Every download_url expires after 1 hour, and each call generates a fresh one. Never store the URL — store the document_uuid and fetch a new link when you need the file.
- Providing both
shipment_uuids and shipment_ids in one listing call fails validation: Please provide either shipment_uuids or shipment_ids to proceed.
- Document
type values such as shipping_label and shipping_label_qr are how label filtering works — the Retrieve Labels endpoint (Booking section) is this listing pre-filtered to label types.
additional_info often carries format details worth reading before printing — label size (A6, 4x6) or ZPL dialect.
Next steps
- Labels specifically: the Retrieve Labels guide (Booking & labels section).
- Attach your own documents at creation or by update — via public or allowlisted URLs.
