# 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`

CRM templates live in [their own section](/docs/entities/crm-document-templates) and require `crm`; this section covers app templates (`moduleId: rest`).

## Operations

- [Create template](./doc-templates/create.md) — `POST /v1/doc-templates`
- [List templates](./doc-templates/list.md) — `GET /v1/doc-templates`
- [Get template](./doc-templates/get.md) — `GET /v1/doc-templates/:id`
- [Download REST template](./doc-templates/download.md) — `GET /v1/doc-templates/:id/download`, requires `X-Api-Key` with the `documentgenerator` scope
- [Update template](./doc-templates/update.md) — `PATCH /v1/doc-templates/:id`
- [Delete template](./doc-templates/delete.md) — `DELETE /v1/doc-templates/:id`
- [Search templates](./doc-templates/search.md) — `POST /v1/doc-templates/search`
- [Template fields](./doc-templates/fields.md) — `GET /v1/doc-templates/fields`
- [Aggregate templates](./doc-templates/aggregate.md) — `POST /v1/doc-templates/aggregate`

## Key fields

| Field | Description |
|------|---------|
| `name` | Template name |
| `numeratorId` | Numerator identifier |
| `region` | Region, for example `uk` |
| `file` | `.docx` content as a base64 string on creation. On update, replaces the template file |
| `fileId` | Drive object ID whose `.docx` content the platform imports on creation. Not applied on update |

Full field list — [Template fields](./doc-templates/fields.md).

## What to know before you start

1. On creation, pass exactly one source: `.docx` content as a base64 string in `file`, or a Drive object ID in `fileId`.
2. `file` requires only the `documentgenerator` scope; `fileId` requires both `documentgenerator` and `disk`.
3. The platform downloads the file referenced by `fileId` and imports its content the same way as a base64 `file`, so the created template can be used to generate documents.
4. Required fields on creation: `name`, `numeratorId`, `region`.
5. Response fields come back in camelCase. The `fileId` in the response refers to the internal Document Generator registry and is not a Drive object ID.
6. `/v1` endpoints accept JSON only. The `multipart/form-data` format is not supported.

## Typical scenario

1. Pass the `.docx` as a base64 string in `file`, or upload it to Drive first and pass the resulting ID in `fileId` to [`POST /v1/doc-templates`](./doc-templates/create.md).
2. Generate a document from the template via [`POST /v1/documents`](./documents/create.md).
3. Get, update, or delete a template by `id`: [`GET /v1/doc-templates/:id`](./doc-templates/get.md), [`PATCH /v1/doc-templates/:id`](./doc-templates/update.md), [`DELETE /v1/doc-templates/:id`](./doc-templates/delete.md).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Auto-pagination | enabled when `limit > 50` |
| `offset` on large result sets | `limit ≤ 500` recommended when `offset ≥ 2500` |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| JSON body on creation | up to 3 MiB |
| Template file on creation | up to 2 MiB after decoding `file` or downloading `fileId` |
| Rate limit | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Company requisites for document generation](/docs/recipes/document-requisites)
- [Documents](/docs/entities/documents)
- [Entity API](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)