Generate dozens or thousands of PDFs from a CSV upload, then download the bundle.

Bulk envelope generation

Generates many PDFs in a single job. The bulk endpoint accepts a CSV upload where each row becomes one filled PDF; outputs are bundled into a downloadable ZIP when the job completes.

This is the right endpoint when you need anything from "fill 50 offer letters tonight" to "render 10,000 invoices for end-of-month." For one PDF at a time, use POST /generate/pdf.

Permissions

API key scope: write or higher. Each generated PDF counts against your monthly quota.

Form fields

Name	Type	Required	Description
`envelope_id`	integer	yes	Envelope (template + mapping pair) the rows fill.
`file`	file (CSV)	yes	UTF-8 CSV. First row is the header, with column names matching the envelope's expected aliases.
`priority`	string	no	`low` / `normal` / `high`. Default `normal`.

CSV format

The CSV header row names the aliases. Subsequent rows hold one PDF's worth of data per row.

invoiceId,clientName,amount,dueDate
INV-2026-001,Acme Corp,$1250.00,2026-06-01
INV-2026-002,Globex,$880.00,2026-06-01
INV-2026-003,Initech,$420.00,2026-06-15

Example

curl -X POST https://api.simplyfill.app/v1/generate/envelope-bulk \
  -H "Authorization: Bearer $SIMPLYFILL_API_KEY" \
  -F "envelope_id=789" \
  -F "file=@invoices.csv"

import fs from 'node:fs'

const job = await client.generate.bulk({
  envelopeId: 789,
  file: fs.createReadStream('invoices.csv')
})
console.log(job.upload_id)

job = client.generate.bulk(
    envelope_id=789,
    file=open("invoices.csv", "rb"),
)
print(job.upload_id)

Response

202 Accepted:

{
  "upload_id": "bulk_4f9c2a...",
  "envelope_id": 789,
  "total_rows": 3,
  "status": "queued",
  "submitted_at": "2026-05-17T15:20:09Z"
}

Tracking progress

Poll GET /api/v1/generate/envelope-bulk/status/{upload_id}:

{
  "upload_id": "bulk_4f9c2a...",
  "status": "processing",
  "total": 3,
  "succeeded": 2,
  "failed": 0,
  "progress": 66
}

Or subscribe to the batch.completed webhook. When the job finishes, the webhook payload (and the status endpoint) contains a download_url for the result ZIP.

Downloading results

curl -L -o invoices.zip \
  https://api.simplyfill.app/v1/generate/envelope-bulk/download/bulk_4f9c2a... \
  -H "Authorization: Bearer $SIMPLYFILL_API_KEY"

The ZIP contains one PDF per successful row plus a manifest.json listing every row, its status, and the corresponding filename. Failed rows appear in manifest.json with an error message; you can re-run those rows in a follow-up CSV.

For per-row failure inspection without downloading the ZIP, call GET /api/v1/generate/envelope-bulk/results/{upload_id}.

Limits

Limit	Value
Max rows per upload	10,000
Max CSV size	50 MB
Per-row PDF cap	Counts against monthly quota same as a single `/generate/pdf` call

Errors

Status	`error` code	Cause
`400`	`invalid_csv`	CSV missing header row or column count mismatch.
`400`	`validation_error`	A required alias is missing across the envelope's mappings.
`402`	`quota_exceeded`	Projected output exceeds your remaining monthly PDF quota.
`404`	`envelope_not_found`	`envelope_id` is unknown or you lack access.

Bulk envelopes