Skip to main content

Generate Documents

Fill documents without storing them using POST /v1/doc-gen/drafts, or generate a batch of Word and PDF files with POST /v1/doc-gen/jobs, with origins per value.

Drafts and batches take the same request. It names the templates (template_id, with with_pair to add the template's companion, or an explicit template_ids list of 1 to 10), the data_product_id, and the record_ids of the rows (1 to 500). The platform fills each chosen template for each chosen row on the server, so a call produces templates times rows documents, and a batch holds at most 500 of them: a larger request is refused with 422.

POST /v1/doc-gen/drafts returns the filled documents and stores nothing. Each document lists its values with their origin, filled and total counts, and missing, the fields that would print empty, each with the type of its source. It needs only the read scope but, as a POST, a member or above behind the key. POST /v1/doc-gen/jobs does the same fill and then generates a Word file and, where PDF conversion is available, a PDF for each document. The batch is returned while it runs, and the files appear as the documents become ready.

Values can be set in the request. values applies to every document by field key: a field entered per document takes the value as entered, a passage decided per document takes yes or no, and any other field takes it as an edit over the fill. documents sets values for single documents (a record_id, an optional template_id, and the values) and wins over values. profile replaces the writer details for this batch only. The request is refused with 422 while documents leave fields empty, unless allow_missing is true, in which case an empty field is left out of the document. A control that was a line of its own then takes its line with it.

POST/v1/doc-gen/drafts

Body fields (drafts and jobs)

template_iduuidOne template. Use this or template_ids.
template_idsuuid[]1 to 10 templates. Use this or template_id.
with_pairbooleanAlso generate the template's companion.
data_product_id*uuidThe data product whose rows fill the templates.
record_ids*string[]1 to 500 row ids of the data product, as returned by the records route.
valuesobjectString values for every document, by field key.
documentsobject[]Up to 5000 entries { record_id (required), template_id?, values (required) } for single documents; they win over values.
profileobjectWriter details for this batch only (name, kuerzel, titel, bereich, unterschrift). The saved profile is unchanged.
save_to_workspacebooleanJobs: when false, the files are deleted 24 hours after generation. Default: true
allow_missingbooleanJobs: generate although some documents leave fields empty.
dry_runbooleanJobs: fill and report, but create no batch; job is null in the response.

Response fields (documents[])

template_id, template_nameuuid, stringThe template the document is filled from.
record_id, record_labelstringThe row.
filled, totalintegerFields with a value, and fields on the sheet.
missing[]arrayFields that would print empty: key, label and source, the type of the field's source.
valuesobjectBy field key: { value, origin }. origin.type is one of product, reference, extract, case, user, rule, today, edited, party, variant, lookup, condition, left_out, fixed, not_needed, empty, with further properties depending on the type.

cURL: Draft one document and inspect what is missing

curl -X POST "https://api.talonic.com/v1/doc-gen/drafts" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "'$TEMPLATE_ID'",
    "data_product_id": "'$PRODUCT_ID'",
    "record_ids": ["'$RECORD_ID'"],
    "values": { "closing_remark": "With kind regards" }
  }'

Response: 201 Draft with origins and a missing field

{
  "templates": [{ "id": "3b1f6a52-8c0e-4f0a-9d5e-2a7c1e4b9d10", "name": "contract-letter" }],
  "documents": [
    {
      "template_id": "3b1f6a52-8c0e-4f0a-9d5e-2a7c1e4b9d10",
      "template_name": "contract-letter",
      "record_id": "rec_0417",
      "record_label": "C-2026-0417",
      "filled": 11,
      "total": 12,
      "missing": [{ "key": "reference_line", "label": "Reference line", "source": "reference" }],
      "values": {
        "addressee": { "value": "Nordwind Energie GmbH", "origin": { "type": "product" } },
        "closing_remark": { "value": "With kind regards", "origin": { "type": "edited" } }
      }
    }
  ]
}
POST/v1/doc-gen/jobs

cURL: Generate despite one empty field

curl -X POST "https://api.talonic.com/v1/doc-gen/jobs" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_ids": ["'$TEMPLATE_ID'"],
    "data_product_id": "'$PRODUCT_ID'",
    "record_ids": ["'$RECORD_ID'"],
    "allow_missing": true,
    "save_to_workspace": true
  }'
Generation continues after the response. The batch starts as running; poll GET /v1/doc-gen/jobs/{id} until its status is completed or failed. See Batches & Downloads for the batch shape and the file routes.

Frequently asked questions

What is the difference between drafts and a dry-run job?+
Both fill documents and store nothing. A draft needs only the read scope and returns templates and documents. A job with dry_run: true needs the write scope, returns the same documents plus a null job, and is the quick way to check that a real request would not be refused.
Why was my job refused with 422?+
Either the batch exceeds 500 documents (templates times rows), or documents leave fields empty and allow_missing is not true. Inspect missing in a draft, enter the values with values or documents, or set allow_missing to generate with those fields left out.
What does an empty field look like in the generated file?+
With allow_missing, a field left empty is left out of the file: the control prints nothing, and a control that was a line of its own takes its line with it unless it is the only paragraph of a table cell. The output keeps its content controls so Word can edit it.
How do I override one value for one document?+
Add an entry to documents with the record_id (and template_id when the batch has several templates) and the values to set. Entries in documents win over the batch-wide values.

Related

Document Generation Overview
Data Products & Records
Batches & Downloads
Rules & Writer Profile