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

## 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`
- [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 `ru` |
| `file` | `.docx` content as a base64 string |
| `fileId` | Disk file identifier. Source: upload via `POST /v1/files/upload` |

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

## What to know before you start

1. Creation requires a file — either the content as base64 in the `file` field, or the `fileId` of a file already uploaded to Disk. Exactly one of the two is passed.
2. Required fields on creation: `name`, `numeratorId`, `region`.
3. Response fields come back in camelCase.
4. `/v1` endpoints accept JSON only; the `multipart/form-data` format is not supported.

## Typical scenario

1. Upload the `.docx` file via `POST /v1/files/upload` — the `id` field from the response becomes the `fileId` value.
2. Create a template with that `fileId` via [`POST /v1/doc-templates`](./doc-templates/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 |
|-------|----------|
| Max records per request | 5000 (`limit ≤ 5000`) |
| Auto-pagination | kicks in at `limit > 50` |
| `offset` on large selections | `limit ≤ 500` recommended at `offset ≥ 2500` |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| Rate limit | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Documents](/docs/entities/documents)
- [Entity API](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)