Generate documents
Generate documents
The POST /2.0/docgen_batches endpoint allows you to generate a document using Box Doc Gen template as input.
Prerequisites
Before you start using Box Doc Gen API, follow the steps listed in the get started with Box Doc Gen guide to create a custom app and a Box Doc Gen template.
Send a request
To generate a document or a set of documents,
use the POST /2.0/docgen_batches endpoint.
Parameters
To make a call, you need to pass the following parameters. Mandatory parameters are in bold.
| Parameter | Description | Example |
|---|---|---|
file.id | ID of the file to be marked as Box Doc Gen template. | 12345678 |
file.type | The type of provided input. The value is always file. | file |
file_version | The file version of a template. | 12345 |
input_source | The input source for generated document. The value has to be api for all the API-based document generation requests. | api |
output_type | The output file type. | docx |
destination_folder.id | The ID of the folder where the generated document will be stored. | 12345678 |
destination_folder.type | The type of the destination item. Since the generated files are stored in folders, the value is always folder. | file |
document_generation_data.generated_file_name | The name of the generated file. | New_Template |
document_generation_data.user_input | The JSON data to be used to generate document. | {"id": 2, "name": "Ink Cartridge", "type": "non-fragile"} |
Use case
When your Box Doc Gen template and JSON data is ready, you can make a request to Box Doc Gen API to generate documents.
A sample call looks as follows:
cURL
curl -L 'https://api.box.com/2.0/docgen_batches' \
-H 'box-version: 2025.0' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-D '{
"file": {
"id": "12345678",
"type": "file"
},
"input_source": "api",
"destination_folder": {
"id": "12345678",
"type": "folder"
},
"output_type": "docx",
"document_generation_data": [
{
"generated_file_name": "Image test",
"user_input": {
"order": {
"id": "12305",
"date": "18-08-2023",
"country": "US",
"expiryDate": "18-08-2024",
"currency": "$",
"amount": 5060.5,
"taxRate": 10,
"requester": "John",
"approver": "Smith",
"department": "Procurement",
"paymentTerms": "30 days",
"deliveryTerms": "30 days",
"deliveryDate": "18-09-2023",
"vendor": {
"company": "Example company",
"address": {
"street": "Example street",
"city": "Example city",
"zip": "EX-456"
}
},
"products": [
{
"id": 1,
"name": "A4 Papers",
"type": "non-fragile",
"quantity": 100,
"price": 29,
"amount": 2900
},
{
"id": 2,
"name": "Ink Cartridge",
"type": "non-fragile",
"quantity": 40,
"price": 39,
"amount": 1560
},
{
"id": 3,
"name": "Adhesive tape",
"type": "non-fragile",
"quantity": 20,
"price": 30,
"amount": 600.5
}
]
}
}
}
]`TypeScript Gen
await client.docgen.createDocgenBatchV2025R0({
file: new FileReferenceV2025R0({ id: uploadedFile.id }),
inputSource: 'api',
destinationFolder: new DocGenBatchCreateRequestV2025R0DestinationFolderField({
id: folder.id,
}),
outputType: 'pdf',
documentGenerationData: [
{
generatedFileName: 'test',
userInput: { ['abc']: 'xyz' },
} satisfies DocGenDocumentGenerationDataV2025R0,
],
} satisfies DocGenBatchCreateRequestV2025R0);Python Gen
client.docgen.create_docgen_batch_v2025_r0(
FileReferenceV2025R0(id=uploaded_file.id),
"api",
CreateDocgenBatchV2025R0DestinationFolder(id=folder.id),
"pdf",
[
DocGenDocumentGenerationDataV2025R0(
generated_file_name="test", user_input={"abc": "xyz"}
)
],
).NET Gen
await client.Docgen.CreateDocgenBatchV2025R0Async(requestBody: new DocGenBatchCreateRequestV2025R0(file: new FileReferenceV2025R0(id: uploadedFile.Id), inputSource: "api", destinationFolder: new DocGenBatchCreateRequestV2025R0DestinationFolderField(id: folder.Id), outputType: "pdf", documentGenerationData: Array.AsReadOnly(new [] {new DocGenDocumentGenerationDataV2025R0(generatedFileName: "test", userInput: new Dictionary<string, object>() { { "abc", "xyz" } })})));Swift Gen (Beta)
try await client.docgen.createDocgenBatchV2025R0(requestBody: DocGenBatchCreateRequestV2025R0(file: FileReferenceV2025R0(id: uploadedFile.id), inputSource: "api", destinationFolder: DocGenBatchCreateRequestV2025R0DestinationFolderField(id: folder.id), outputType: "pdf", documentGenerationData: [DocGenDocumentGenerationDataV2025R0(generatedFileName: "test", userInput: ["abc": "xyz"])]))When the request is being processed, each entry in the document_generation_data array is treated as a separate document generation job that Box Doc Gen adds to the document generation queue.
Generated documents will be saved in the designated folder.