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

# How documents flow through Upwell

> Where documents come from, how they get classified and attached, who can see them, and how they leave — the lifecycle of a POD, BOL, rate confirmation, or invoice PDF.

# How documents flow through Upwell

Documents — PODs, bills of lading, rate confirmations, carrier invoices, invoice PDFs — move through a consistent lifecycle no matter how they arrive: **in → classified → attached → shared → out**. This page is the conceptual map; the [shipment documents guide](/api-guides/shipment-documents) covers the API.

## 1. How documents come in

| Source               | What happens                                                                                                                                                                                                                                         |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Inbound email**    | Attachments on emails to your Upwell inbound addresses are ingested automatically, then grouped and classified (below).                                                                                                                              |
| **API upload**       | You attach bytes directly — base64 for smaller files, or a two-step presigned URL for large ones. See [shipment documents](/api-guides/shipment-documents) and [integration patterns](/integration-patterns#document-upload-two-step-presigned-url). |
| **Integration sync** | Documents pulled from a connected TMS or portal during sync.                                                                                                                                                                                         |
| **Generated**        | Upwell renders some documents itself — most notably the **customer-invoice PDF**, generated for an AR customer invoice. That PDF then travels with the invoice at delivery (the outbound step below).                                                |

## 2. Classification

An incoming document doesn't yet know what it is. Upwell classifies it — automatically for emailed/parsed documents, or from the `type` you supply on API upload — assigning a **document type** (POD, BOL, rate confirmation, carrier invoice, and so on) drawn from your account's available document types.

<Note>
  Until a document is classified, its `type` reads as `UNKNOWN`. Over the API that's the signal that classification is still in flight — treat a document still `UNKNOWN` past your timeout as *needs manual review*, not a hard failure. See [Knowing when a carrier invoice is processed](/api-guides/carrier-invoice-status).
</Note>

<Warning>
  When writing a document's `type` via the API, use the **canonical type code**, not its display label — e.g. `PROOF_OF_DELIVERY`, where `POD` is only the label. The [shipment documents guide](/api-guides/shipment-documents) covers this.
</Warning>

## 3. Attachment

A classified document is linked to the record it belongs to — a **shipment** (the load), a **carrier invoice** (AP), or a **customer invoice** (AR). The same underlying file can be associated with more than one record; removing an association detaches the document from that record without destroying the file. The [data model](/concepts/data-model) covers these objects.

## 4. Visibility

Two independent flags control who can see a document when it's shared:

* `visibleToCarrier` — whether it's exposed to the carrier.
* `visibleToCustomer` — whether it's exposed to the customer.

They're set when you attach a document and can differ per document, so a shipment can hold a mix of internal-only and shared files.

## 5. How documents go out

* **Customer delivery (AR).** When a customer invoice is delivered, its supporting documents go with it — by email, EDI, or portal, per the customer's configuration. See [Accounts receivable management](/accounts-receivable/receivables).
* **Integration push (AP & AR).** Documents can be pushed back to a connected TMS/portal through a retriable, persisted upload queue, so a transient failure retries rather than dropping the document.

<Note>
  This page is the conceptual overview. To actually list, add, or remove a shipment's documents over the API, see [Retrieving and managing shipment documents](/api-guides/shipment-documents). To submit a carrier invoice with its documents, see [Submitting carrier invoices via API](/api-guides/carrier-invoice-submission).
</Note>