> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upwell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieving and managing shipment documents

> List, add, and remove the documents attached to a shipment (load) via the API — and how that differs from carrier-invoice documents.

# 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.

<Note>
  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](/api-guides/carrier-invoice-status).
</Note>

## List a shipment's documents

`GET /api/rest/shipments/{shipmentId}/documents` returns the shipment's documents, keyed by `shipmentDocumentsByShipmentId`:

```bash theme={null}
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 } ] } ] }
```

| Field                                                | Meaning                                                                                                                                                           |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                                 | The shipment-document link ID — use this to delete the association.                                                                                               |
| `documentId`                                         | The underlying document's ID.                                                                                                                                     |
| `documents`                                          | Array of the underlying document record(s).                                                                                                                       |
| `documents[].type`                                   | The 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` / `visibleToCustomer` | Sharing flags.                                                                                                                                                    |
| `documents[].sourceSystem` / `sourceSystemId`        | Provenance from your system, when set.                                                                                                                            |
| `createdAt` / `updatedAt`                            | Timestamps.                                                                                                                                                       |

<Tip>
  Testing against staging? Use the staging base URL `https://staging.api.upwell.com` with your staging API key — the paths are identical.
</Tip>

## Add a document to a shipment

`POST /api/rest/shipments/{shipmentId}/documents` attaches a document from base64-encoded bytes:

```bash theme={null}
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.

<Note>
  The base64 path is convenient for smaller files. For large documents, prefer the two-step presigned-URL upload — see [Integration patterns](/integration-patterns#document-upload-two-step-presigned-url).
</Note>

<Warning>
  `sourceSystem` and `sourceSystemId` are all-or-nothing — provide both or neither. See [Integration patterns](/integration-patterns).
</Warning>

## 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`):

```bash theme={null}
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": "..." } ] } }
```

<Note>
  For the complete, always-current request and response schemas, see the `shipments/{shipmentId}/documents` entries in the [API Reference](/api-reference/introduction). To attach documents to a carrier invoice instead, see [Submitting carrier invoices via API](/api-guides/carrier-invoice-submission).
</Note>