Document Merge Async

This endpoint initiates an asynchronous operation to merge multiple source documents into a single PDF, preserving the order specified in the request. Just like synchronous merge endpoint, it supports platforms like Storage, Salesforce, and OneDrive. Unlike the synchronous version, it returns immediately and processes the requested operation in the background. The result can be tracked or received via promise or callback, depending on your integration setup. This approach is ideal for handling large files, slower systems, or when non-blocking execution is preferred.

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

externalContext A contextual reference used to link the document generation request to an external system, process, or transaction. Often used for traceability or auditing purposes.

sourceDocuments Identifies the input documents (e.g., Word, Excel, or PDF files) and their properties, serving as the inputs for the merge and conversion process to create a unified target document.

targetDocument Defines the properties of the output document resulting from merging the source documents. It specifies the document's metadata, format (typically PDF for merged outputs), delivery method, storage location, and processing options, determining how the merged document is saved and managed.

targetDocument.options.salesforce Specifies how the document will be stored or associated with records in Salesforce. Includes fields such as fileId, fileType, fileParentId, and ownerId.

targetDocument.options.onedrive Specifies how the document will be shared or stored via Microsoft OneDrive. Includes permission settings like anonymous access, edit/view rights, and user-specific sharing.

TypeScript Definitions

Use the request body type in TypeScript.

externalContext?

sourceDocuments?array<>

targetDocument?

data?

Response Body

`application/json`

curl -X POST "https://example.com/documents/document/merge/async" \  -H "Content-Type: application/json" \  -d '{    "externalContext": {      "id": "req-2026-0007421"    },    "sourceDocuments": [      {        "urn": "e3b0c442-98fc-4e1a-8a3d-2c1b5f6e9a70",        "loadMethod": "Storage",        "order": 1,        "remove": "none"      },      {        "urn": "5d8e9f0a-1b2c-43d4-95e6-7f8a9b0c1d2e",        "loadMethod": "Storage",        "order": 2,        "remove": "none"      }    ],    "targetDocument": {      "name": "Q3 Sales Report - Merged",      "fileFormat": "pdf",      "deliveryMethod": "Storage",      "path": "root",      "options": {        "pdfSaveOptions": "{ \\"ConformanceLevel\\": \\"PdfA3a\\", \\"Version\\": \\"PDF_1_7\\", \\"ImageDpi\\": 750 }",        "salesforce": {          "networkId": "0DMXYZ0000000AAAA",          "fileId": "069AZ0000004CvXYAW",          "fileType": "File",          "fileParentId": "0013P00000MvR7oQAF",          "ownerId": "0053P00000MvR7oQAF"        },        "onedrive": {          "viewAnonymous": true,          "editAnonymous": true,          "editUsers": [            "user@example.com"          ],          "viewUsers": [            "user@example.com"          ]        }      }    },    "data": {      "embedded": "key:value"    }  }'

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

{  "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/merge/async",  "dateTime": "2026-07-14T09:30:00.000Z",  "userId": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d",  "operationId": "25a9d0ecbf31291d4163601cad29bbde"}

Authorization

Header Parameters

Request Body

Response Body

201application/json

400application/json

`application/json`

`application/json`