Upload Documents
You can use this API method to upload a document file containing multiple documents.
You POST the file as you would a standard HTTP POST file upload, as if it were posted via an html form with an enctype of multipart/form-data and a FILE input type field.
Files are in a CSV format and must contain headers that match our document field's keys as the first line.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| csv | File | Yes | N/A | The csv file to upload POSTED |
| zip | File | Conditional | N/A | ZIP containing the row PDFs. Required unless an active, client-owned tpl_id is supplied. |
| tpl_id | Int | Conditional | N/A | Positive integer id of an active template owned by the OAuth client. Required when no ZIP is supplied. Arrays, fractions, signed/exponent forms, inactive/deleted templates, and foreign-client ids are rejected before the batch CSV is retained. |
| sp_postage | Postage Code | No | 1 | The type of postage to apply to the uploaded documents. Defaults to USPS first class if not specified. See Resources > Postage Types for the full list. |
| return_envelope_id | Int | No | No return envelope | The return envelope to include with each uploaded document. The id of an active, client-owned return envelope. Omit, pass null, or pass 0 for no return envelope. |
A CSV return_envelope_id column overrides the global request value for that row. Values are validated after field mapping; an invalid row is rejected without creating its document. Public API values must be null, integer 0, or a positive integer/digit-only form value. Empty strings, web placeholders, signs, decimals, exponents, booleans, arrays, inactive/deleted ids, and foreign ids are rejected.
Partial batch semantics: after file-level preflight succeeds, CSV rows are processed independently. If one row is rejected but another succeeds, the response has status: 0 and row messages in errors while still retaining the successful objects in document, their number in total_document_count, and the batch metadata in files. Clients must inspect those success fields even when status is zero and retry only rejected rows. A file-level validation/ZIP extraction failure, or a batch in which every row is rejected, retains neither batch metadata nor documents.
Mail-profile fields: the document objects include return_envelope_id (int|null), mail_class (letter | large_envelope | large_envelope_intl | priority | null), mail_class_reason (letter | sheet_count_triggered_large_envelope | weight_triggered_large_envelope | priority_upgrade | null), sheet_count (int|null), check_sheet_count (int), insert_sheet_count (int), computed_weight_oz (number|null), and large_envelope (bool).