Document templates

A document template is a .docx file with placeholders that Bitrix24 fills in with real values to produce ready-to-use documents.

Bitrix24 API: documentgenerator.template.* Scope: documentgenerator; creation from fileId additionally requires disk

Create template

POST /v1/doc-templates

Creates a renderable document template from a .docx file. Pass exactly one source: the file content as a base64 string in file, or a Disk object ID in fileId. The platform downloads the Disk file and imports its content through the same path as file.

Both variants require the documentgenerator scope. The fileId variant additionally requires disk because the platform reads the Disk object.

Request fields (body)

Field	Type	Req.	Description
`name`	string	yes	Template name
`numeratorId`	number	yes	Numerator identifier
`region`	string	yes	Region, for example `uk`
`file`	string	one of two	`.docx` file content as a base64 string. Requires only `documentgenerator`
`fileId`	number \| string	one of two	Positive Disk object ID. Additionally requires `disk`; a decimal string is accepted for compatibility
`code`	string	no	Symbolic code of the template
`active`	string	no	Whether the template is active: `"Y"` or `"N"`
`withStamps`	string	no	Whether to use stamps and signatures: `"Y"` or `"N"`
`sort`	number	no	Sort index
`users`	array	no	Identifiers of employees who have access to the template

Examples

curl — personal key

Terminal

curl -X POST "https://vibecode.bitrix24.com/v1/doc-templates" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract template",
    "numeratorId": 1,
    "region": "uk",
    "file": "<base64 .docx content>"
  }'

curl — OAuth application

Terminal

curl -X POST "https://vibecode.bitrix24.com/v1/doc-templates" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract template",
    "numeratorId": 1,
    "region": "uk",
    "file": "<base64 .docx content>"
  }'

JavaScript — personal key

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/doc-templates', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Contract template',
    numeratorId: 1,
    region: 'uk',
    file: '<base64 .docx content>',
  }),
})

const { success, data } = await res.json()
console.log('Template ID:', data.id)

JavaScript — OAuth application

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/doc-templates', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Contract template',
    numeratorId: 1,
    region: 'uk',
    file: '<base64 .docx content>',
  }),
})

const { success, data } = await res.json()

To use a file from Disk, first upload the .docx through POST /v1/files/upload, then pass the returned id in fileId instead of file in one of the examples above. Such a request requires both the documentgenerator and disk scopes on the key.

Response fields

Returns the full object of the created template. Response status — 201.

Field	Type	Description
`id`	number	Identifier of the created template
`name`	string	Template name
`region`	string	Region
`code`	string	Symbolic code of the template
`active`	string	Whether the template is active: `"Y"` or `"N"`
`moduleId`	string	Identifier of the template's source module
`numeratorId`	number	Numerator identifier
`withStamps`	string	Use of stamps and signatures: `"Y"` or `"N"`
`providers`	object	Mapping of the template's data providers
`users`	object	Mapping of user identifiers with access to the template
`isDeleted`	boolean	Whether the template is marked as deleted
`sort`	number	Sort index
`createTime`	string	Creation date (ISO 8601)
`updateTime`	string	Last update date (ISO 8601)
`download`	string	Download URL of the document built from the template
`downloadMachine`	string	Download URL with a token for programmatic access

If the response contains fileId, it is a file ID from the internal Document Generator registry, not the Disk object ID supplied in the request. Do not use it with /v1/files endpoints.

Limits

The JSON body may be up to 3 MiB.
The .docx may be up to 2 MiB after decoding file or downloading fileId.
Exceeding either limit returns 413 PAYLOAD_TOO_LARGE before a template is created.

Response example

JSON

{
  "success": true,
  "data": {
    "id": 209,
    "name": "Contract template",
    "region": "uk",
    "code": null,
    "download": "/bitrix/services/main/ajax.php?action=documentgenerator.api.template.download&SITE_ID=s1&id=209",
    "active": "Y",
    "moduleId": "rest",
    "numeratorId": 1,
    "withStamps": "N",
    "providers": {
      "bitrix\\documentgenerator\\dataprovider\\rest": "bitrix\\documentgenerator\\dataprovider\\rest"
    },
    "users": {
      "U1": "U1"
    },
    "isDeleted": false,
    "sort": 500,
    "createTime": "2026-05-12T09:03:38.000Z",
    "updateTime": "2026-05-12T09:03:38.000Z",
    "downloadMachine": "https://<portal>/rest/1/<token>/documentgenerator.api.template.download/?token=<token>"
  }
}

Error response example

400 — no file passed: