DocumentemplateStart free

Documentation

Documentemplate API

Generate hundreds of documents from another program: you send a spreadsheet, the API queues the batch and you download a ZIP of PDFs.

How it works

Generating hundreds of documents takes a while, so the API doesn't leave you waiting on an open connection: you send the sheet, the batch is queued and your program asks until it finishes.

  1. Send the sheet

    A POST with the template id and an Excel or CSV file. It answers right away with 202 and the batch id.

  2. Wait

    A GET of the batch with wait=25: the request holds for up to 25 seconds and answers as soon as it changes. Repeat it until the state is done or failed.

  3. Download

    Once the state is done, download the ZIP: one PDF per row and a report of what happened in each.

The endpoint

A single version, v1, with a single resource: the batch. It uses the same templates, the same column matching and the same quotas as the Batches screen. Every request carries the Authorization: Bearer header with your token.

POST https://documentemplate.com/api/v1/batch

FieldWhat it does
templateIdrequiredThe template id; the template must be published. You can see it in the address when you open it (/templates/ID).
filerequiredThe spreadsheet: .xlsx or .csv up to 10 MB. The first row holds the column titles and every following row is a document.
mappingWhich column fills each field, as JSON: {"customer": "Name"}. A column title or its position (from 0) works. Without it, columns are matched by title, as the app proposes.
nameColumnColumn that names each file (its title or position). Without it, the one that looks like a name or, failing that, the row number.
outputFILES (one PDF per document, default) or MERGED (a single PDF with all of them).
formatPDF, which for now is the only download format.

Progress and result

GET /v1/batch/:idThe batch state: queued, generating, done or failed, with its progress and what happened in each row.
GET /v1/batch/:id?wait=25The same, but waiting up to that many seconds (maximum 25) for the batch to finish. This is the recommended way to wait.
GET /v1/batch/:id/resultThe ZIP with the documents and the batch-report.csv. Kept for 7 days after it finishes.

Examples

Send the sheet

curl
curl -X POST https://documentemplate.com/api/v1/batch \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -F templateId=TEMPLATE_ID \
  -F file=@customers.xlsx

Wait

curl
curl "https://documentemplate.com/api/v1/batch/BATCH_ID?wait=25" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Download

curl
curl -o documents.zip https://documentemplate.com/api/v1/batch/BATCH_ID/result \
  -H "Authorization: Bearer <YOUR_TOKEN>"

All together

JavaScript (Node 20+)
const API = 'https://documentemplate.com/api';
const headers = { Authorization: 'Bearer <YOUR_TOKEN>' };

// 1. Send the sheet: the batch is queued and the answer comes right away (202).
const form = new FormData();
form.append('templateId', 'TEMPLATE_ID');
form.append('file', new Blob([await readFile('customers.xlsx')]), 'customers.xlsx');
let batch = await (await fetch(`${API}/v1/batch`, { method: 'POST', headers, body: form })).json();

// 2. Wait: each request holds for up to 25 s and answers as soon as the state changes.
while (batch.state === 'queued' || batch.state === 'running') {
  batch = await (await fetch(`${API}/v1/batch/${batch.id}?wait=25`, { headers })).json();
}
if (batch.state === 'failed') throw new Error(batch.error);

// 3. Download the ZIP with the documents.
const zip = await fetch(`${API}/v1/batch/${batch.id}/result`, { headers });
await writeFile('documents.zip', Buffer.from(await zip.arrayBuffer()));

Quotas, errors and versions

Your plan's quotas are checked before anything starts: if the batch doesn't fit you get an error, and nothing is created or spent from your quota.

CodeWhat it does
202Batch accepted and queued. The response carries its id and the address to ask at.
400Malformed request: the template or the sheet is missing, a column doesn't exist, the template isn't published or the sheet can't be read.
401The token is missing, wrong, or has been regenerated or revoked.
403Your plan doesn't allow batches or the batch doesn't fit your quota: too many rows, too many stored documents or monthly PDFs. The message says which.
404The batch doesn't exist or belongs to another account.
429Too many requests. Wait a moment and try again.

The version is in the address (v1). Within a version fields are never removed or renamed: an incompatible change would ship as v2 and v1 would keep working for a while.

Start in a minute

Create your account and generate your token in the API section. Bulk generation is part of the Pro plan.

Create a free accountPricing