> ## Documentation Index
> Fetch the complete documentation index at: https://platform.doodocs.kz/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> Find a template and read its variable_schema

A document is created from a **template** — or from a file you already have, see
[Uploading your own document](/en/guides/documents/uploads). The template defines the
print form and the set of variables filled in when a document is created. These variables are
described in `variable_schema` — a JSON schema that `template_values` in the
`POST /documents` body must conform to.

The workflow is simple: find a template → read its `variable_schema` → prepare
`template_values` per that schema. All template reading is covered by the
`documents:read` scope.

## Searching templates

`GET /document_templates` returns **active templates only**, page by page. Narrow the
selection with the `search` parameter by name:

```bash theme={null}
curl -H "X-API-Key: ddp_YOUR_KEY" \
  "https://app.doodocs.kz/api/developer/v1/document_templates?search=%D0%BF%D1%80%D0%B8%D1%91%D0%BC&limit=20"
```

```json theme={null}
{
  "templates": [
    {
      "id": "tpl_7c1a…",
      "name": "Employment order",
      "version": 3
    }
  ],
  "next_page_token": ""
}
```

<Note>
  The list follows the general [pagination](/en/api-reference/pagination): `limit`
  (defaults to `100`, maximum `1000`) and an opaque `page_token`. Inactive templates are
  not returned through the Developer API.
</Note>

## Reading the variable schema

`GET /document_templates/{template_id}` returns the template together with its
`variable_schema`:

```bash theme={null}
curl -H "X-API-Key: ddp_YOUR_KEY" \
  https://app.doodocs.kz/api/developer/v1/document_templates/tpl_7c1a…
```

```json theme={null}
{
  "id": "tpl_7c1a…",
  "name": "Employment order",
  "version": 3,
  "variable_schema": {
    "type": "object",
    "required": ["employee_full_name", "position", "start_date"],
    "properties": {
      "employee_full_name": { "type": "string", "title": "Employee full name" },
      "position":           { "type": "string", "title": "Position" },
      "start_date":         { "type": "string", "format": "date", "title": "Hire date" },
      "salary":             { "type": "number", "title": "Salary" }
    }
  }
}
```

The contents of `variable_schema` depend on the specific template — read it before
creating a document rather than relying on memory. For the "Employment order" template
in the example, `template_values` is assembled from the three required fields:

```json theme={null}
{
  "template_values": {
    "employee_full_name": "Kulyash Baiseitova",
    "position": "HR Manager",
    "start_date": "2026-02-10",
    "salary": 650000
  }
}
```

<Tip>
  Pin the template version: pass `template_version` in `POST /documents` equal to the
  `version` from the response. That way the document is created against the schema you
  read, even if the template is updated later.
</Tip>

<Warning>
  If `template_values` does not conform to the template's `variable_schema` (a required
  field is missing, a wrong type), `POST /documents` returns `400`. Check your values
  against the schema before sending.
</Warning>

## Next

<Columns cols={2}>
  <Card title="Signing" icon="pen" href="/en/guides/documents/signing">
    Create a document from a template and run it through the route.
  </Card>

  <Card title="Documents overview" icon="file-lines" href="/en/guides/documents/overview">
    Statuses, object structure, and files.
  </Card>
</Columns>