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: 
curl https://api.upwell.com/api/rest/shipments/shi_abc123/documents \
  -H "Authorization: YOUR_API_KEY"
# -> { "shipmentDocumentsByShipmentId": [
#      { "id": "...", "documentId": "doc_...", "createdAt": "...", "updatedAt": "...",
#        "documents": [ { "id": "doc_...", "type": "PROOF_OF_DELIVERY",
#                         "sourceSystem": "...", "sourceSystemId": "...",
#                         "visibleToCarrier": true, "visibleToCustomer": false } ] } ] }
FieldMeaning
idThe shipment-document link ID — use this to delete the association.
documentIdThe underlying document’s ID.
documentsArray of the underlying document record(s).
documents[].typeThe document’s classification — one of your account’s available document types (e.g. PROOF_OF_DELIVERY; POD is that type’s display label, not a write value).
documents[].visibleToCarrier / visibleToCustomerSharing flags.
documents[].sourceSystem / sourceSystemIdProvenance from your system, when set.
createdAt / updatedAtTimestamps.
Testing against staging? Use the staging base URL https://staging.api.upwell.com with your staging API key — the paths are identical.

​
Add a document to a shipment

POST /api/rest/shipments/{shipmentId}/documents attaches a document from base64-encoded bytes: 
curl -X POST https://api.upwell.com/api/rest/shipments/shi_abc123/documents \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "shipmentId": "shi_abc123",
        "input": {
          "base64": "JVBERi0xLjQ...",
          "mimeType": "application/pdf",
          "type": "PROOF_OF_DELIVERY",
          "filename": "pod.pdf",
          "visibleToCarrier": true
        }
      }'
# -> { "createShipmentDocument": { "id": "...", "documentId": "doc_..." } }
Required: base64, mimeType, and type (one of your available document types). 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 Integration patterns.
sourceSystem and sourceSystemId are all-or-nothing — provide both or neither. See Integration patterns.

​
Remove a document from a shipment

DELETE /api/rest/shipments/{shipmentId}/documents/{id} removes the document’s association with the shipment. Use the shipment-document id from the list response (not the underlying documentId): 
curl -X DELETE https://api.upwell.com/api/rest/shipments/shi_abc123/documents/SHIPMENT_DOCUMENT_ID \
  -H "Authorization: YOUR_API_KEY"
# -> { "deleteFileAssociations": { "affectedRows": 1,
#      "returning": [ { "id": "...", "fileId": "...", "associationId": "..." } ] } }
For the complete, always-current 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.