## 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 the same way 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 | Required | 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 ```bash 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": "" }' ``` ### curl — OAuth application ```bash 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": "" }' ``` ### 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: '', }), }) 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: '', }), }) const { success, data } = await res.json() ``` To use a file from Disk, first upload the `.docx` through [`POST /v1/files/upload`](/docs/entities/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 The response status is `201`. | Field | Type | Description | |------|-----|---------| | `success` | boolean | Always `true` on success | | `data` | object | The created template | | `data.id` | number | Identifier of the created template | | `data.name` | string | Template name | | `data.region` | string | Region | | `data.code` | string/null | Symbolic code of the template. `null` if not passed | | `data.active` | string | Whether the template is active: `"Y"` or `"N"` | | `data.moduleId` | string | Identifier of the template's source module. For templates in this section, it is `rest` | | `data.numeratorId` | number | Numerator identifier | | `data.withStamps` | string | Use of stamps and signatures: `"Y"` or `"N"` | | `data.providers` | object | Mapping of the template's data providers | | `data.users` | object | Mapping of user identifiers with access to the template | | `data.isDeleted` | boolean | Whether the template is marked as deleted | | `data.sort` | number | Sort index | | `data.createTime` | string | Creation date (ISO 8601) | | `data.updateTime` | string | Last update date (ISO 8601) | | `data.timezone` | string/null | Template time zone. `null` if not set | | `data.download` | string | Download URL of the document built from the template | | `data.downloadMachine` | string | URL for downloading the template file through the Vibecode API — [`GET /v1/doc-templates/:id/download`](/docs/entities/doc-templates/download). Requires `X-Api-Key` with the `documentgenerator` scope | 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", "timezone": null, "downloadMachine": "https://vibecode.bitrix24.com/v1/doc-templates/209/download" } } ``` ## Error response example 400 — no file passed: ```json { "success": false, "error": { "code": "MISSING_FILE_OR_FILE_ID", "message": "POST /v1/doc-templates requires exactly one source: \"file\" with base64-encoded .docx content, or \"fileId\" with a Disk object ID (requires disk scope)." } } ``` ## 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, `numeratorId` is not a positive integer, or `fileId` is not a positive safe integer ID | | 400 | `READONLY_FIELD` | The body contains a read-only field, for example the owner module `moduleId`, which the platform assigns | | 415 | `UNSUPPORTED_MEDIA_TYPE` | Request sent with `multipart/form-data` | | 413 | `PAYLOAD_TOO_LARGE` | The JSON body exceeds 3 MiB or the decoded/downloaded file exceeds 2 MiB | | 403 | `SCOPE_DENIED` | The key lacks `documentgenerator`, or the `fileId` variant lacks the additional `disk` scope | | 404 | `DOWNLOAD_URL_NOT_FOUND` | Bitrix24 returned no download address for the Disk object | | 502 | `DOWNLOAD_FAILED` | The Disk file could not be downloaded; the response does not expose the download address or network error text | | 401 | `TOKEN_MISSING` | The key has no configured tokens | Full list of common API errors — [Errors](/docs/errors). ## See also - [Get template](/docs/entities/doc-templates/get) - [Update template](/docs/entities/doc-templates/update) - [List templates](/docs/entities/doc-templates/list)