Skip to main content

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:

List a shipment’s documents

GET /api/rest/shipments/{shipmentId}/documents returns the shipment’s documents, keyed by shipmentDocumentsByShipmentId:
Testing against staging? Use the staging base URL https://staging.api.upwell.com with your staging API key — the paths are identical, and keys are environment-specific. See Environments for how staging access is provisioned.

Add a document to a shipment

POST /api/rest/shipments/{shipmentId}/documents attaches a document from base64-encoded bytes:
The create response is only those two fields. 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.
sourceSystem and sourceSystemId are all-or-nothing — provide both or neither. See Integration patterns.
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.