This guide covers how to merge multiple documents into a single output file. It assumes you're already familiar with the basic generation flow covered in Generate Document.
Only PDF files can be merged — each source document must already be a PDF.
Merge works on documents already in Doctavian storage, so upload each source PDF first as multipart form-data:
POST https://api.doctavian.com/v1/documents/document/upload
Authorization: Bearer <token>
x-api-key: <api-key>
Content-Type: multipart/form-data
file: <your PDF>The response returns an id for each uploaded file — this is what you'll pass as urn in the merge request:
{
"result": {
"data": {
"files": [
{
"id": "cf7cf043-7a1f-4eb3-b3be-06f5c144af1e",
"fileName": "part-one.pdf"
}
]
},
"statusCode": 201,
"message": "Created"
}
}Repeat for each PDF you want to include in the merge.
Like Data Sources and templates, source documents aren't limited to Storage. See Data Sources for what each load method expects.
Send a single call to POST /documents/document/merge. The request is very similar to a generate request, with two main sections:
urn and an order controlling its position in the final documentdocument object on a generate requestPOST https://api.doctavian.com/v1/documents/document/merge
Authorization: Bearer <token>
x-api-key: <api-key>
Content-Type: application/json
{
"sourceDocuments": [
{
"urn": "cf7cf043-7a1f-4eb3-b3be-06f5c144af1e",
"loadMethod": "Storage",
"order": 1,
"remove": "none"
},
{
"urn": "1a2b3c4d-5e6f-4a1b-9c8d-7e6f5a4b3c2d",
"loadMethod": "Storage",
"order": 2,
"remove": "none"
}
],
"targetDocument": {
"name": "combined-contract",
"fileFormat": "pdf",
"deliveryMethod": "Storage",
"path": "root",
"locale": "en",
"timezone": "Europe/Dublin"
}
}The order value determines each document's position in the merged output — 1 comes first, 2 comes second, and so on.
A successful call returns 201 Created with the merged document's URN:
{
"result": {
"statusCode": 201,
"message": "Created",
"data": {
"document": {
"deliveryMethod": "Storage",
"name": "combined-contract",
"fileFormat": "pdf",
"urn": "d54882e3-e5a0-4c2f-a436-0ee5b1e39d5a"
}
}
},
"consumption": [
{ "dimension": "documents-merged", "value": 2 }
]
}Download the merged file with GET /documents/document/{documentId}/download, using the returned urn as the documentId.
See the full merge request and response schema in the API Reference.
For merging large batches of documents, use POST /documents/document/merge/async instead of the synchronous endpoint. The request body is identical to the one above — same sourceDocuments and targetDocument structure — with one addition: you need an x-client-authorization header so Doctavian knows where to send the callback once the merge completes.
POST https://api.doctavian.com/v1/documents/document/merge/async
Authorization: Bearer <token>
x-api-key: <api-key>
x-client-authorization: <client-token>
Content-Type: application/json
{
"sourceDocuments": [
{
"urn": "cf7cf043-7a1f-4eb3-b3be-06f5c144af1e",
"loadMethod": "Storage",
"order": 1,
"remove": "none"
},
{
"urn": "1a2b3c4d-5e6f-4a1b-9c8d-7e6f5a4b3c2d",
"loadMethod": "Storage",
"order": 2,
"remove": "none"
}
],
"targetDocument": {
"name": "combined-contract",
"fileFormat": "pdf",
"deliveryMethod": "Storage",
"path": "root",
"locale": "en",
"timezone": "Europe/Dublin"
}
}A successful call returns 201 Created. Rather than waiting for the merged document in the response, Doctavian processes the request in the background and calls back to the destination configured in your x-client-authorization token once it's done. See Building the signed headers for how to construct that token.
/documents/document/uploadsourceDocuments and ordertargetDocument controls the output format and delivery, same as a generate request