# signing.templates.preview

Render a PDF preview of a template (templateId) or unsaved template text (body, fields, signerRoles) with merge values and recipients on the organization letterhead. Returns pdfBase64, the page count, and the labels of required fields that are still empty. Nothing is stored.

`GET | POST /api/v1/accounting/signing.templates.preview`

Permissions: `accounting:read` · Roles: admin, finance

MCP tool: `accounting_signing_templates_preview`

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `templateId` | string (ID) |  | The ID of the related record. |
| `title` | string |  | A short title. 1–200 characters. |
| `body` | string |  | 1–200000 characters. |
| `fields` | array of objects |  | at most 100 items. |
| `fields[].key` | string | Yes | Matches ^[a-zA-Z][a-zA-Z0-9_.]{0,80}$. |
| `fields[].label` | string | Yes | 1–120 characters. |
| `fields[].required` | boolean |  | Default `false`. |
| `fields[].defaultValue` | string |  | at most 5000 characters. |
| `fields[].multiline` | boolean |  |  |
| `fields[].markdown` | boolean |  |  |
| `fields[].help` | string |  | at most 300 characters. |
| `fields[].source` | enum |  | Where the record came from. One of: `company`, `counterparty`, `contractor`, `agreement`. |
| `fields[].type` | enum |  | One of: `date`, `choice`, `email`, `phone`, `address`, `job`. |
| `fields[].options` | array of strings |  | 1–40 items; each 1–120 characters. |
| `fields[].allowOther` | boolean |  |  |
| `signerRoles` | array of objects |  | at most 10 items. |
| `signerRoles[].role` | string | Yes | A person's access level in the company. Matches ^[a-z][a-z0-9_]{0,40}$. |
| `signerRoles[].label` | string | Yes | 1–80 characters. |
| `signerRoles[].partyLabelField` | string | Yes | Matches ^[a-zA-Z][a-zA-Z0-9_.]{0,80}$. |
| `signerRoles[].order` | integer | Yes | 1 to 20. |
| `signerRoles[].defaultInternal` | boolean |  | Default `false`. |
| `letterhead` | boolean |  |  |
| `footer` | string or null |  |  |
| `logoAssetId` | string (ID) or null |  |  |
| `values` | map |  | Default `{}`. |
| `recipients` | array of objects |  | at most 20 items. |
| `recipients[].kind` | enum | Yes | Which kind of record or job this is. One of: `signer`, `cc`. |
| `recipients[].signerRole` | string or null |  |  |
| `recipients[].name` | string | Yes | A display name. 1–200 characters. |
| `recipients[].email` | string (email) | Yes | An email address. at most 320 characters. |
| `recipients[].title` | string or null |  | A short title. |
| `recipients[].company` | string or null |  |  |
| `recipients[].order` | integer |  | 1 to 20. |
| `recipients[].userId` | string or null |  | The ID of a person in your company. |
| `subjectType` | enum |  | The kind of record this is about, such as entry, invoice or mail. One of: `contractor`, `party`, `invoice`. |
| `subjectId` | string |  | The ID of the record this is about. 1–200 characters. |
| `jobRoleId` | string (ID) |  | The ID of the related record. |
| `jobRoleVersion` | integer |  | 1 to 100000. |
| `engagement` | object |  | No other fields. |
| `engagement.rate` | object | Yes | No other fields. |
| `engagement.rate.amountMinor` | string | Yes | An amount in cents (the currency's smallest unit), written as a whole-number string such as "1250" for $12.50. Matches ^[1-9]\d{0,14}$. |
| `engagement.rate.currency` | string | Yes | Three-letter currency code, such as CAD or USD. |
| `engagement.rate.unit` | enum | Yes | One of: `hour`, `day`, `week`, `month`, `year`, `fixed`. |
| `engagement.basis` | enum | Yes | One of: `job`, `one_off`. |
| `engagement.note` | string or null |  | A short note, kept with the record. |
| `engagement.startDate` | string (date) or null |  |  |
| `engagement.endDate` | string (date) or null |  |  |
| `engagement.noticeDays` | integer or null |  |  |

## Example request

```bash
curl -G https://app.getoatmilk.com/api/v1/accounting/signing.templates.preview \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  --data-urlencode 'templateId=7f0f6c1e-1c1f-4b5e-9c8d-2f5e8e3c1a10'
```

Reference page: https://app.getoatmilk.com/docs/api/signing.templates.preview