Document Generate

Generates a document from a template and delivers it, synchronously. Supply three things: the template to generate from, the data that populates it, and the document configuration describing the output and where it goes.

The call blocks until generation finishes and returns the outcome directly — 201 with the generated file's identity and usage metrics, or 400 with the reason it failed. Nothing is written to the delivery target when the request fails.

Templates may be Microsoft formats (docx, xlsx, pptx) held in Storage or OneDrive, or Google Workspace formats (gdoc, gsheet, gslide) held in Google Drive, and the output can be delivered to Storage, OneDrive, or Google Drive with optional sharing links. pdf can be produced from any template. The template's own content drives what the data is used for — merge fields, expressions, repeaters, tables — and it can pull in further templates through an Include directive, listed in template.relatedItems. Data comes either from a stored file used as-is, or from an external API queried at generation time via the GraphQL load method.

Which format can be loaded from where, which output formats a given template can produce, and where each output format can be delivered are all validated together; the request body description sets out those rules in one place.

Use documents-document-generate-async instead when generation may take long enough that you don't want to hold the connection open, or when your integration is callback-driven. That variant acknowledges immediately with an empty 201 and delivers this same result to a callback URL.

Authorization

AuthorizationBearer <token>

JWT token to authenticate the request.

In: header

X-Api-Key<token>

API key, sent as a request header.

In: header

Request Body

application/json

The request has three mandatory top-level sections — template, data, and document — plus an optional externalContext, an arbitrary JSON object echoed back unchanged so you can match a response to the request that produced it.

template identifies the file to generate from. Locate it either by url alone, or by urn + loadMethod together; supplying neither pair means the template can't be resolved and the request fails with TEMPLATE_NOT_FOUND. template.relatedItems lists additional templates the primary template pulls in via an Include directive, each matched to that directive by its name. template.options, and each related item's own options, carry load settings for the template file format.

data identifies the source of the values consumed by the template's merge fields, expressions, and other data-driven elements. urn and loadMethod are both always mandatory — unlike template, there is no url alternative. variables layers static or computed values on top of that source; embedded writes custom metadata into the output file's properties rather than its visible content.

document configures the output. timezone, locale, name, fileFormat, deliveryMethod, and path are all mandatory. document.options carries save settings for the output format, Google-engine tuning in googleGenerate, and sharing settings in onedrive or googleDrive — whichever matches deliveryMethod; the other is ignored.

The three sections constrain each other. These combinations are validated, and an invalid one fails the request rather than producing a document:

template.fileFormat must be consistent with template.loadMethod. gdoc, gsheet, and gslide are Google Workspace formats, loadable only when loadMethod is GoogleDrive; docx, xlsx, and pptx are Microsoft formats, loadable only from Storage or OneDrive.
document.fileFormat must match template.fileFormat, with two exceptions: pdf can be produced from any template, and csv can be produced only from an xlsx template.
document.deliveryMethod is constrained by document.fileFormat. Google formats can only be delivered to GoogleDrive; Microsoft formats to Storage or OneDrive; pdf and csv to any of the three.
document.path is relative to the root of the target selected by deliveryMethod, and that root is spelled differently per target: "root" for Storage, "" for OneDrive and GoogleDrive. Concatenate any subfolder onto that root rather than replacing it.
Inside template.options and document.options, only the property matching the relevant format is read — docxLoadOptions for a docx template, pdfSaveOptions for pdf output, and so on. The Google formats don't pass through GemBox and have no load or save options.

TypeScript Definitions

Use the request body type in TypeScript.

Request body for generating a document from a template. Defines which template to use, what data populates it, and how the resulting file is formatted and delivered.

externalContext?

Optional, arbitrary JSON object supplied by the caller to correlate this request with an external system, process, or transaction (e.g. an order ID or a trace ID from your own system). Its shape isn't validated or interpreted by Doctavian — any JSON object is accepted — and the same object is returned unchanged as externalContext in the response envelope, so you can match a response back to the request that produced it. Omit it if you don't need this correlation.

template*

The template used to generate the final document. Locating the template file requires either url alone, or urn together with loadMethod — supplying neither pair means the template can't be resolved and the request fails with a 400 response.

data*

The data source that supplies values consumed by the template's merge fields, expressions, and other data-driven elements (e.g. repeaters, tables). Unlike template, data has no url alternative — urn and loadMethod are both always mandatory.

document*

Configuration for the document produced by this request: how dates and numbers are formatted, the output file's name and format, and where it's delivered.

Response Body

`application/json`

curl -X POST "https://example.com/documents/document/generate" \  -H "Content-Type: application/json" \  -d '{    "externalContext": {      "actionRequestId": "req-2026-0007421"    },    "template": {      "name": "Standard Invoice",      "urn": "9f86d081-884c-4d30-8934-9c1e6cbcb9f5",      "fileFormat": "docx",      "loadMethod": "Storage",      "options": {        "docxLoadOptions": "{ \\"PreserveUnsupportedFeatures\\": true }"      },      "relatedItems": [        {          "name": "Invoice Terms Addendum",          "urn": "4b1e2f3a-5c6d-47e8-9a0b-1c2d3e4f5a6b",          "fileFormat": "docx",          "loadMethod": "Storage"        }      ]    },    "data": {      "loadMethod": "Storage",      "urn": "a4f8c9d2-6b3e-4f1a-9c7d-2e5b8a1f4d6c",      "variables": [        {          "name": "createdDate",          "value": "{!$now()}",          "type": "fieldExpression"        },        {          "name": "requestId",          "value": "{!requestId}",          "type": "graphql"        },        {          "name": "customerName",          "value": "Jane Doe",          "type": "global"        }      ],      "query": "{\\"query\\":\\"{Account {Name Description Owner.Username Id Opportunities {StageName OpportunityLineItems {Name}} Contacts {Id}}}\\"}",      "embedded": "{ \\"contractId\\": \\"12345\\" }"    },    "document": {      "timezone": "(GMT+00:00) Greenwich Mean Time (Europe/Dublin)",      "locale": "en_IE_EURO",      "name": "Q3 Sales Report",      "fileFormat": "docx",      "deliveryMethod": "Storage",      "path": "root",      "options": {        "pdfSaveOptions": "{ \\"ConformanceLevel\\": \\"PdfA3a\\", \\"Version\\": \\"PDF_1_7\\", \\"ImageDpi\\": 750, \\"SelectionType\\": \\"EntireFile\\" }",        "docxSaveOptions": "{}",        "onedrive": {          "viewAnonymous": true,          "editAnonymous": true,          "editUsers": [            "user@example.com"          ],          "viewUsers": [            "user@example.com"          ]        },        "googleDrive": {          "viewAnonymous": true,          "editAnonymous": true,          "editUsers": [            "user@example.com"          ],          "viewUsers": [            "user@example.com"          ]        },        "googleGenerate": {          "nativeMergeEnabled": true,          "nativeImageMergeEnabled": true        }      }    }  }'

{  "result": {    "statusCode": 201,    "message": "Created",    "data": {      "document": {        "deliveryMethod": "Storage",        "name": "Q3 Sales Report",        "fileFormat": "docx",        "urn": "c72f4a1e-9d3b-4c5f-8a6e-1b2c3d4e5f6a"      }    }  },  "consumption": [    {      "dimension": "pages-generated",      "value": 4    },    {      "dimension": "documents-generated",      "value": 1    }  ],  "externalContext": {    "actionRequestId": "req-2026-0007421"  },  "origin": "POST https://api.doctavian.com/v1/documents/document/generate",  "dateTime": "2026-07-14T09:30:00.000Z",  "userId": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d",  "operationId": "b5629806f22477783837ba2c1137f33d"}

{  "error": {    "statusCode": 400,    "message": "Bad Request",    "innerErrors": [      {        "code": "TEMPLATE_NOT_FOUND",        "message": "The specified template could not be located.",        "userMessage": "We couldn't generate your document. Please check the template reference and try again."      }    ]  },  "externalContext": {    "actionRequestId": "req-2026-0007421"  },  "origin": "POST https://api.doctavian.com/v1/documents/document/generate",  "dateTime": "2026-07-14T09:30:00.000Z",  "userId": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d",  "operationId": "a3780a46c0f0450f12a9e1280c3b8a37"}

Authorization

Request Body

Response Body

201application/json

400application/json

`application/json`

`application/json`