# Templates

> Creating reusable envelopes and generating documents from them.

In Legaldoc, a template isn't a separate resource: it's an envelope with `type: "TEMPLATE"`. It's created, given recipients and fields, and distributed the same way as any envelope (see [Integration Guide](/en/guides/integration-guide/)) — the difference is that a `TEMPLATE` envelope isn't signed directly, it's used as a base to generate real documents.

## Create a document from a template

```http
POST /envelope/use
```

Takes a template's `envelopeId` and creates a new `DOCUMENT`-type envelope from it.

| Field | Type | Required | Description |
|---|---|---|---|
| `envelopeId` | string | Yes | ID of the template to use. |
| `recipients` | array | Yes | Real recipients, mapped by `id` to the recipients defined in the template. |
| `distributeDocument` | boolean | No | If `true`, distributes the document immediately after creating it. |
| `externalId` | string | No | Your own identifier for the generated document. |
| `folderId` | string | No | Folder to create the document in. |
| `customDocumentData` | array | No | Replaces one or more of the template's PDFs with new files (see below). |
| `prefillFields` | array | No | Prefills values into template fields (see below). |

Each recipient in `recipients` requires `id` (the recipient's ID in the template) and `email`; `name` and `signingOrder` are optional and override what's defined in the template.

See the full spec in the [API Reference](/en/api/operations/envelope-use/).

### Replacing the template's PDF

If you need to generate the PDF dynamically but reuse the recipients and fields already configured in the template, use `customDocumentData` to map each of the template's files (by its `envelopeItemId`) to a new file:

```jsonc
{
  "envelopeId": "envelope_template_123",
  "recipients": [{ "id": 1, "email": "signer@example.com", "name": "Real Name" }],
  "customDocumentData": [
    { "identifier": "envelope_item_xyz", "envelopeItemId": "envelope_item_xyz" }
  ]
}
```

The replacement PDF must keep the same page layout as the original — the template's fields are positioned according to the original coordinates, and a layout change misaligns them.

### Prefilling field values

`prefillFields` lets you fill in template fields before distributing — useful when you already know the value (for example, pulling it from your own system) and don't want to ask the signer for it:

```jsonc
{
  "envelopeId": "envelope_template_123",
  "recipients": [{ "id": 1, "email": "signer@example.com" }],
  "prefillFields": [
    { "id": 101, "type": "text", "value": "Senior Software Engineer" },
    { "id": 102, "type": "number", "value": "120000" },
    { "id": 103, "type": "checkbox", "value": ["health", "life-insurance"] }
  ]
}
```

Each `prefillField`'s `type` must match the actual type of the field in the template.

---

## See also

- [Envelopes](/en/resources/envelopes/) — listing templates by filtering on `type=TEMPLATE`
- [Fields](/en/resources/fields/) — field types and their options
- [Integration Guide](/en/guides/integration-guide/) — the general creation and signing flow