Working with shipment documents
Documents — PODs, bills of lading, rate confirmations, and so on — attach to a shipment (the load), not only to a carrier invoice. This page covers listing, adding, and removing a shipment’s documents.There are two document surfaces — pick the endpoint by what you’re keyed on:
- By shipment (load):
GET /api/rest/shipments/{shipmentId}/documents— this page. - By carrier invoice (AP):
GET /api/rest/carrier_invoices/{id}/documents— see Knowing when a carrier invoice is processed.
List a shipment’s documents
GET /api/rest/shipments/{shipmentId}/documents returns the shipment’s documents, keyed by shipmentDocumentsByShipmentId:
Add a document to a shipment
POST /api/rest/shipments/{shipmentId}/documents attaches a document from base64-encoded bytes:
id is the file id (file_…) — use it as {id} on delete. documentId is the documents row id (doc_…). Call the list endpoint for file.url and the rest of the document.
Required: base64 (the file bytes, without a data: prefix), mimeType, and type (a DocumentTypeEnum value such as PROOF_OF_DELIVERY). Optional: filename, visibleToCarrier, visibleToCustomer, and a sourceSystem + sourceSystemId pair.
The base64 path is convenient for smaller files. For large documents, prefer the two-step presigned-URL upload — see Document conventions.
Documents on the load count toward a customer’s required documents for carrier invoices. Adding, removing, or reclassifying a shipment document makes Upwell re-evaluate the load’s carrier invoices that aren’t yet approved or paid, which can clear or reopen a Missing required document exception. See Customer-required documents.
Remove a document from a shipment
DELETE /api/rest/shipments/{shipmentId}/documents/{id} removes the document’s association with the shipment. {id} is the file id from create or list (file_…), not documentId:
For the complete request and response schemas, see the
shipments/{shipmentId}/documents entries in the API Reference. To attach documents to a carrier invoice instead, see Submitting carrier invoices via API.
