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

# Document templates

> Templates used for sales and purchase documents — quotations, invoices, proforma invoices, and more

# Document templates

Document templates are the **layout and settings presets** used when you create documents in Heffl — not project templates or email templates. Each template belongs to one document type, for example:

* **Quotations** (`type: quotations`)
* **Invoices** (`type: invoices`)
* **Proforma invoices** (`type: proforma_invoices`)
* **Purchase orders** (`type: purchase_orders`)
* **Bills**, **sales orders**, **documents**, and other types supported in your workspace

They control PDF/HTML layout, numbering, signatures, and template-scoped custom fields. In API v2, each template has a prefixed string **id** (`tpl_` prefix). Use it as `templateId` when creating records that require a template (for example `POST /quotations`).

## List templates

Filter by document type to find templates for a specific workflow:

```bash theme={null}
curl "https://api.heffl.com/api/v2/document-templates?type=quotations" \
  -H "x-api-key: YOUR_API_KEY"
```

Optional query parameters:

| Parameter         | Description                                                                                                                  |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `type`            | Document type — `quotations`, `invoices`, `proforma_invoices`, `purchase_orders`, `bills`, `sales_orders`, `documents`, etc. |
| `search`          | Case-insensitive prefix match on template name                                                                               |
| `includeInactive` | When `true`, includes inactive templates                                                                                     |

Response:

```json theme={null}
{
  "data": [
    {
      "id": "tpl_abc123",
      "name": "Standard quotation",
      "type": "quotations",
      "isActive": true,
      "isSignatureRequired": false,
      "valueType": "DYNAMIC"
    }
  ]
}
```

## Get a template

Use this when you need template-scoped custom field keys before creating a quotation:

```bash theme={null}
curl "https://api.heffl.com/api/v2/document-templates/tpl_abc123" \
  -H "x-api-key: YOUR_API_KEY"
```

The response includes a `customFields` array. Use each `key` as a top-level `cf_*` field on `POST /quotations` (same convention as [Custom fields](https://docs.heffl.com/api-v2/custom-fields)).

## Create a quotation

1. List templates with `type=quotations` and pick an `id`.
2. Optionally call `GET /document-templates/{id}` for `customFields`.
3. Create the quotation with `templateId`:

```bash theme={null}
curl -X POST "https://api.heffl.com/api/v2/quotations" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "clt_abc123",
    "templateId": "tpl_abc123",
    "date": "2026-05-31T00:00:00.000Z",
    "quotationProducts": [
      { "name": "Discovery workshop", "quantity": 1, "price": 2500 }
    ]
  }'
```

`templateId` cannot be changed after creation. See [API v2 overview — Quotations](https://docs.heffl.com/api-v2/introduction#quotations).

## Related

* [ID prefixes](https://docs.heffl.com/api-v2/id-prefixes) — `tpl_` template IDs
* [Custom fields](https://docs.heffl.com/api-v2/custom-fields) — team-wide field definitions; template detail also lists template-scoped fields