Skip to main content

​
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 covers the API.

​
1. How documents come in

SourceWhat happens
Inbound emailAttachments on emails to your Upwell inbound addresses are ingested automatically, then grouped and classified (below).
API uploadYou attach bytes directly — base64 for smaller files, or a two-step presigned URL for large ones. See shipment documents and integration patterns.
Integration syncDocuments pulled from a connected TMS or portal during sync.
GeneratedUpwell 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.
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.
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 covers this.

​
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 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.
  • 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.
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. To submit a carrier invoice with its documents, see Submitting carrier invoices via API.