For AI agents: markdown of this page — /docs-content-en/entities/doc-templates.md documentation index — /llms.txt

Document templates

A document template is a .docx file with placeholder markers from which Bitrix24 builds completed documents with substituted values.

Bitrix24 API: documentgenerator.template.* Scope: documentgenerator

Create template

POST /v1/doc-templates

Creates a document template from a .docx file. The file is passed in one of two ways:

  • file — .docx content as a base64 string;
  • fileId — the identifier of a file uploaded to Disk in advance.

Request fields (body)

Field Type Req. Description
name string yes Template name
numeratorId number yes Numerator identifier
region string yes Region, for example ru
file string * .docx file content as a base64 string. Alternative to the fileId field
fileId number * Disk file identifier. Source: upload via POST /v1/files/upload. Alternative to the file field
code string no Symbolic code of the template
active string no Template activity: "Y" or "N"
withStamps string no Use stamps and signatures: "Y" or "N"
sort number no Sort index
users array no Identifiers of employees who have access to the template

* The file and fileId fields are mutually exclusive: one of the two is passed.

To obtain fileId, upload the .docx file via POST /v1/files/upload — use the id value from the response as fileId.

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": "us",
    "fileId": 9175
  }'

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": "us",
    "fileId": 9175
  }'

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: 'ru',
    fileId: 9175,
  }),
})

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: 'ru',
    fileId: 9175,
  }),
})

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

Alternative — pass the .docx file content directly in the file field (base64):

JSON 
{
  "name": "Contract template",
  "numeratorId": 1,
  "region": "us",
  "file": "<base64 .docx content>"
}

Response fields

The full object of the created template is returned. 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 Activity: "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 identifiers of users who have access to the template
isDeleted boolean Whether the template is marked deleted
sort number Sort index
createTime string Creation date (ISO 8601)
updateTime string Last change date (ISO 8601)
download string Download URL of the document built from the template
downloadMachine string Download URL with a token for programmatic access

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 209,
    "name": "Contract template",
    "region": "us",
    "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:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_FILE_OR_FILE_ID",
    "message": "POST /v1/doc-templates requires either \"file\" (base64-encoded .docx content) or \"fileId\" (Disk file ID). Neither was provided."
  }
}

Errors

HTTP Code Description
400 MISSING_FILE_OR_FILE_ID Neither file nor fileId was passed
400 CONFLICTING_FILE_FIELDS Both file and fileId were passed
400 MISSING_REQUIRED_FIELD name, numeratorId, or region is missing
400 INVALID_PARAMS name/region is not a string, or numeratorId is not a positive integer
415 UNSUPPORTED_MEDIA_TYPE Request sent with multipart/form-data
413 FST_ERR_CTP_BODY_TOO_LARGE The multipart/form-data request body contains data
403 SCOPE_DENIED The key lacks the documentgenerator scope
401 TOKEN_MISSING The key has no configured tokens

Full list of common API errors — Errors.

See also