Skip to main content

Batches & Downloads

List generation batches, read one with its documents and per-document files, retry missing PDFs, and download a document as Word or PDF or a whole batch as ZIP.

A batch is the result of one POST /v1/doc-gen/jobs. It carries its status (running, completed or failed), the template ids and names, who created it, whether it is kept in the workspace, whether PDF conversion was available (pdfAvailable), and its documents. Each document has its own status (pending, ready or failed), the values with their origins, its audit events, its files (kind docx or pdf, name and size in bytes), an error and, when the Word file was made but the PDF was not, a pdfError.

The history route returns summaries, newest first: the same batch fields, with documents as a count of the documents the key's minting user may read, plus failed (documents with status failed) and pdf_missing (documents with a PDF error). limit runs from 1 to 50 and defaults to 50. A batch none of whose documents that person may read is reported as not found by the single-batch route, and the download routes apply the same check per document.

File retention follows save_to_workspace. A batch kept in the workspace keeps its files under the batch. A batch generated with save_to_workspace: false is download-only: filesExpireAt gives the deletion time (24 hours after generation), filesExpired turns true once the files are gone, each document's files is then empty, and the values and history stay. The download, ZIP and PDF retry routes answer 410 from that moment.

GET/v1/doc-gen/jobs

Query parameters

limitintegerMost batches to return, 1 to 50. Default: 50
GET/v1/doc-gen/jobs/{id}

Response fields

id, status, erroruuid, string, string | nullThe batch, its status (running, completed or failed) and a failure message.
templateIds, templateNamesarrayThe templates the batch was generated from.
createdAt, bystringWhen the batch was created and who created it.
savedToWorkspace, pdfAvailablebooleanWhether the files are kept in the workspace, and whether PDF conversion was available.
filesExpireAt, filesExpiredstring | null, booleanWhen the files of a batch not kept in the workspace are deleted, and whether they are already gone.
documents[]arrayPer document: id, templateId, templateName, recordId, recordLabel, values, events, status (pending, ready or failed), files[], error, pdfError.
eventsarrayAlways empty; each document carries its own events.

Response: Completed batch (excerpt)

{
  "id": "e61a0c97-2b4f-4d38-a5c1-7f90d3b8e426",
  "templateIds": ["3b1f6a52-8c0e-4f0a-9d5e-2a7c1e4b9d10"],
  "templateNames": ["contract-letter"],
  "createdAt": "2026-10-21T09:31:07.000Z",
  "by": "api:5d1c0e7a",
  "status": "completed",
  "error": null,
  "savedToWorkspace": true,
  "pdfAvailable": true,
  "filesExpireAt": null,
  "filesExpired": false,
  "documents": [
    {
      "id": "0b9d2f64-71c3-4e58-8a16-c5e4d7a39f10",
      "templateId": "3b1f6a52-8c0e-4f0a-9d5e-2a7c1e4b9d10",
      "templateName": "contract-letter",
      "recordId": "rec_0417",
      "recordLabel": "C-2026-0417",
      "status": "ready",
      "files": [
        { "kind": "docx", "name": "contract-letter C-2026-0417.docx", "size": 41873 },
        { "kind": "pdf", "name": "contract-letter C-2026-0417.pdf", "size": 96412 }
      ],
      "error": null,
      "pdfError": null,
      "values": {},
      "events": []
    }
  ],
  "events": []
}
POST/v1/doc-gen/jobs/{id}/pdf
GET/v1/doc-gen/jobs/{id}/documents/{doc}/file

Path and query parameters

id*uuidThe batch id.
doc*uuidThe document id within the batch.
kindstringdocx or pdf. Any value other than pdf returns the Word file. Default: docx
GET/v1/doc-gen/jobs/{id}/zip

cURL: Retry PDFs, then download the archive

curl -X POST "https://api.talonic.com/v1/doc-gen/jobs/$JOB_ID/pdf" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

curl -OJ "https://api.talonic.com/v1/doc-gen/jobs/$JOB_ID/zip" \
  -H "Authorization: Bearer $TALONIC_API_KEY"
Without PDF conversion a batch still keeps its Word files and reports pdfAvailable: false. A PDF that fails where conversion is configured is kept as pdfError on its document, and the batch's error says how many are missing. Make them again with POST /v1/doc-gen/jobs/{id}/pdf rather than generating the batch a second time.

Frequently asked questions

Why does a download return 410?+
The batch was generated with save_to_workspace set to false and the 24-hour download window has passed, so its files are deleted. The values and the history stay on the batch. Generate the batch again, with save_to_workspace left at its default of true when the files should be kept.
Can I download a PDF when pdfAvailable is false?+
No. Without PDF conversion the batch keeps its Word files only, so download kind=docx. When conversion is available again, POST /v1/doc-gen/jobs/{id}/pdf converts the stored Word files of ready documents that have no PDF.
Why is a batch reported as not found when it exists?+
The key's minting user may read none of its documents under Sources IAM. A generated document is readable only by people who may read every source document it was filled from, so a batch you cannot read in any part is indistinguishable from an unknown id.

Related

Document Generation Overview
Generate Documents
Status & Issues
Error Format