Document Generate Async

Initiates the same document generation as documents-document-generate — specify a template, supply the data to populate it, and configure the output format, storage location, and delivery method — but asynchronously.

This endpoint returns 201 with an empty body as soon as the request is accepted and queued. That response only acknowledges receipt; it does not mean the document was generated, and it carries no document metadata.

The result arrives at your callback URL, not in the response to this call. Once generation finishes, Doctavian sends a POST to the URL formed by joining the iss and dest claims of the X-Client-Authorization token supplied on this request, authenticating itself with that token's sub claim. Your endpoint should return any success status to acknowledge receipt.

The callback body is the generation outcome, in one of two shapes. On success it is the DocumentGenerateResponse envelope — the identical shape the synchronous documents-document-generate operation returns as its 201 body, carrying result.data.document (the generated document's deliveryMethod, name, fileFormat, urn, and, for drive deliveries, uri and the sharing links) plus consumption. On failure it is the standard ErrorResponse error envelope, with the cause in error.innerErrors[]. Both shapes carry the same externalContext, origin, dateTime, userId, and operationId metadata; result and consumption appear only on success, error only on failure. Correlate a callback back to the request that produced it through externalContext, which is echoed back unchanged from the request body.

A 400 from this endpoint means the request was rejected before being queued, so no callback follows it.

Use this endpoint instead of the synchronous variant when generation is expected to take long enough that you don't want the calling request to block, or when your integration is callback-driven.

Authorization

AuthorizationBearer <token>

JWT token to authenticate the request.

In: header

X-Api-Key<token>

API key, sent as a request header.

In: header

Header Parameters

X-Client-Authorization?string

This does not authenticate the async request itself — that's Authorization. It authenticates Doctavian's callback to your service once the async result is ready.

Generate it by calling POST /common/client/token with the claims below as plain JSON. That endpoint signs and encrypts the payload for you and returns the ready-to-use token in result.data.token — you never construct or sign this token yourself.

Required claims: sub (the access token your callback endpoint accepts from Doctavian), iss (base URL of the service receiving the callback), dest (the callback route, e.g. /temp/callback — combined with iss to form the full callback URL). Optional claims: oid, client_id, full_name, email, locale, zoneinfo. You don't need to set iat or exp — the token endpoint handles timing.

iss and dest cannot resolve back to Doctavian's own API — that combination is rejected to prevent a callback loop.

If this header is missing on an async request, the response is 400 X_CLIENT_AUTH_ERROR ("header is missing for async operations").

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/async" \  -H "X-Client-Authorization: eyJhbGciOiJIUzI1NiJ9.example-client-callback-token" \  -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        }      }    }  }'

Empty

{  "error": {    "statusCode": 400,    "message": "Bad Request",    "innerErrors": [      {        "code": "X_CLIENT_AUTH_ERROR",        "message": "header is missing for async operations",        "userMessage": "This request can't be accepted without a callback authorization header."      }    ]  },  "externalContext": {    "actionRequestId": "req-2026-0007421"  },  "origin": "POST https://api.doctavian.com/v1/documents/document/generate/async",  "dateTime": "2026-07-14T09:30:00.000Z",  "userId": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d",  "operationId": "38a1de72cef5aba1c0b26dd712239827"}

Authorization

Header Parameters

Request Body

Response Body

201

400application/json

`application/json`