> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spitshake.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Templates
> Create and manage document templates with field schemas, submitter roles, and multiple document formats.
A template is the foundation of every signing workflow in DocuTrust. It combines a source document (PDF, DOCX, or HTML) with a field schema that defines what data signers need to provide and where it appears on the document.
## Template object
Every template returned by the API includes these fields:
```json theme={null}
{
"id": "tpl_7VQhP2tM9xA1kR8bN",
"name": "Service Agreement",
"slug": "qk7x9m2p",
"external_id": "contract-sa-2026",
"folder_name": "Legal Contracts",
"source": "builder",
"shared": true,
"field_count": 8,
"submitter_count": 2,
"schema": [],
"submitters": [
{
"uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Client"
},
{
"uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "Company Representative"
}
],
"thumbnail_url": "/api/templates/tpl_7VQhP2tM9xA1kR8bN/documents/thumbnail",
"created_at": "2026-04-01T09:00:00.000Z",
"updated_at": "2026-04-08T14:30:00.000Z"
}
```
| Field | Type | Description |
| ----------------- | -------------- | -------------------------------------------------------------------------------- |
| `id` | string | Public template identifier (for example, `tpl_7VQhP2tM9xA1kR8bN`). |
| `name` | string | Human-readable template name. |
| `slug` | string | URL-safe unique identifier for public links. |
| `external_id` | string or null | Your custom identifier for mapping to external systems. |
| `folder_name` | string | The folder this template is organized under in the dashboard. |
| `source` | string | How the template was created: `builder`, `api`, `import`, or `clone`. |
| `shared` | boolean | Whether the template is visible to all users in the account or only its creator. |
| `field_count` | integer | Total number of fields defined in the schema. |
| `submitter_count` | integer | Number of submitter roles defined. |
| `schema` | array | The field schema (see [Field schema](#field-schema) below). |
| `submitters` | array | The submitter roles (see [Submitter roles](#submitter-roles) below). |
| `thumbnail_url` | string or null | URL to the first-page thumbnail image, or null if not yet generated. |
| `created_at` | string | ISO 8601 creation timestamp. |
| `updated_at` | string | ISO 8601 last-modified timestamp. |
## Submitter roles
Every template defines one or more submitter roles. Each role represents a party who will sign or fill fields in the document. When creating a submission, you map real people to these roles.
```json theme={null}
{
"submitters": [
{
"uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Client"
},
{
"uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "Company Representative"
}
]
}
```
| Field | Type | Description |
| ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid` | string | Unique identifier for this submitter role within the template. Used to assign fields to roles. |
| `name` | string | Human-readable role name (e.g., "Client", "Witness", "Notary"). Submitters in a submission must specify a `role` matching this name. |
## Field schema
The `schema` array defines every fillable field in the template. Each field specifies its type, position on the document, which submitter role it belongs to, and optional defaults or constraints.
```json theme={null}
{
"schema": [
{
"uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"name": "Full Name",
"type": "text",
"submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"required": true,
"readonly": false,
"key": "full_name",
"default_value": "",
"placeholder": "Enter your full legal name",
"options": null,
"areas": [
{
"page": 0,
"x": 0.12,
"y": 0.45,
"w": 0.35,
"h": 0.03,
"attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
},
{
"uuid": "d4e5f6a7-b8c9-0123-def0-345678901234",
"name": "Signature",
"type": "signature",
"submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"required": true,
"readonly": false,
"key": "client_signature",
"default_value": null,
"placeholder": null,
"options": null,
"areas": [
{
"page": 2,
"x": 0.10,
"y": 0.72,
"w": 0.30,
"h": 0.06,
"attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
},
{
"uuid": "e5f6a7b8-c9d0-1234-ef01-456789012345",
"name": "Agreement Date",
"type": "date",
"submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"required": true,
"readonly": false,
"key": "agreement_date",
"default_value": "today",
"placeholder": "MM/DD/YYYY",
"options": null,
"areas": [
{
"page": 2,
"x": 0.55,
"y": 0.72,
"w": 0.20,
"h": 0.03,
"attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
},
{
"uuid": "f6a7b8c9-d0e1-2345-f012-567890123456",
"name": "Payment Method",
"type": "select",
"submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"required": false,
"readonly": false,
"key": "payment_method",
"default_value": "Credit Card",
"placeholder": "Select payment method",
"options": ["Credit Card", "Bank Transfer", "Check", "PayPal"],
"areas": [
{
"page": 1,
"x": 0.12,
"y": 0.60,
"w": 0.35,
"h": 0.04,
"attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
}
]
}
```
### Field properties
| Field | Type | Description |
| ---------------- | -------------- | --------------------------------------------------------------------------------------------------------------------- |
| `uuid` | string | Unique identifier for this field within the template. |
| `name` | string | Human-readable field label shown to the signer. |
| `type` | string | The field type. See [Field types](#field-types) below. |
| `submitter_uuid` | string | UUID of the submitter role responsible for filling this field. |
| `required` | boolean | Whether the signer must fill this field before completing the form. |
| `readonly` | boolean | Whether the field is pre-filled and cannot be changed by the signer. |
| `key` | string | Machine-readable key for pre-filling and reading values via the API. Must be unique within the template. |
| `default_value` | string or null | The default value shown when the signer opens the form. For date fields, use `"today"` to auto-fill the current date. |
| `placeholder` | string or null | Placeholder text shown when the field is empty. |
| `options` | array or null | Available choices for `select` and `radio` field types. Null for all other types. |
| `areas` | array | Positions where this field renders on the document. See [Field areas](#field-areas). |
### Field areas
Each field has one or more areas defining its visual position on the document pages.
| Property | Type | Description |
| ----------------- | ------- | ------------------------------------------------------------------------------------ |
| `page` | integer | Zero-indexed page number (0 = first page). |
| `x` | float | Horizontal position as a fraction of page width (0.0 = left edge, 1.0 = right edge). |
| `y` | float | Vertical position as a fraction of page height (0.0 = top edge, 1.0 = bottom edge). |
| `w` | float | Width as a fraction of page width. |
| `h` | float | Height as a fraction of page height. |
| `attachment_uuid` | string | UUID of the document attachment this area belongs to (for multi-document templates). |
### Field types
DocuTrust supports 19 field types:
| Type | Description | `options` used | Notes |
| -------------------- | ---------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------- |
| `text` | Single-line text input | No | General-purpose text entry. |
| `signature` | Signature capture | No | Accepts drawn, typed, or uploaded signatures. |
| `initials` | Initials capture | No | Smaller version of signature for initialing pages. |
| `date` | Date picker | No | Use `default_value: "today"` for auto-fill. |
| `checkbox` | Single checkbox | No | Boolean true/false. |
| `select` | Dropdown select | Yes | Signer picks one option from the `options` array. |
| `radio` | Radio button group | Yes | Signer picks one option from the `options` array. |
| `file` | File upload | No | Signer uploads a file (e.g., ID scan, supporting document). |
| `image` | Image capture/upload | No | Signer uploads or captures an image (e.g., photo ID). |
| `stamp` | Stamp/seal placement | No | Signer places a stamp image (e.g., corporate seal). |
| `payment` | Payment collection | No | Collects payment via integrated payment processor. |
| `phone_verification` | SMS phone verification | No | Signer enters phone number, receives SMS OTP, and verifies. |
| `cells` | Multi-cell text grid | No | Fixed-width cells for structured data (e.g., SSN, account numbers). |
| `number` | Numeric input | No | Accepts only numeric values. |
| `multi_select` | Multiple choice select | Yes | Signer picks one or more options from the `options` array. |
| `heading` | Section heading | No | Display-only heading text (not fillable). |
| `paragraph` | Paragraph text | No | Display-only paragraph text (not fillable). |
| `label` | Field label | No | Display-only label (not fillable). |
| `html` | Custom HTML content | No | Renders custom HTML on the signing form (not fillable). |
| `date_now` | Current date (auto) | No | Auto-populates with the current date when the signer opens the form. Read-only -- the signer cannot change the value. |
## Field validation
Add validation rules to text fields to enforce specific input formats. Validation is checked when the signer submits their form -- invalid values display an error message and prevent completion until corrected.
There are two ways to add validation to a field:
1. **Preset validation** -- Use the `validation` property with a preset name for common patterns (SSN, email, phone, etc.).
2. **Custom regex** -- Use the `pattern` property with any regular expression string for custom formats.
### Example: field with preset validation
```json theme={null}
{
"uuid": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
"name": "SSN",
"type": "text",
"submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"required": true,
"readonly": false,
"key": "ssn",
"default_value": "",
"placeholder": "123-45-6789",
"validation": "ssn",
"pattern": null,
"options": null,
"areas": [
{
"page": 0,
"x": 0.12,
"y": 0.35,
"w": 0.25,
"h": 0.03,
"attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
}
```
### Example: field with custom regex pattern
```json theme={null}
{
"uuid": "a2b3c4d5-e6f7-8901-bcde-f12345678901",
"name": "Invoice Number",
"type": "text",
"submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"required": true,
"readonly": false,
"key": "invoice_number",
"default_value": "",
"placeholder": "INV-2026-0001",
"validation": null,
"pattern": "^INV-\\d{4}-\\d{4}$",
"options": null,
"areas": [
{
"page": 0,
"x": 0.55,
"y": 0.35,
"w": 0.25,
"h": 0.03,
"attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
}
```
### Validation presets
DocuTrust includes 11 built-in validation presets. Use the `validation` property on a text field to apply one:
| Preset | Pattern | Description |
| -------------- | -------------------------------------------- | -------------------------------------------------------------------- |
| `ssn` | `^\d{3}-\d{2}-\d{4}$` | US Social Security Number (format: 123-45-6789). |
| `ein` | `^\d{2}-\d{7}$` | US Employer Identification Number (format: 12-3456789). |
| `email` | `^[^\s@]+@[^\s@]+\.[^\s@]+$` | Email address. |
| `url` | `^https?://[^\s]+$` | URL starting with http\:// or https\://. |
| `zip` | `^\d{5}(-\d{4})?$` | US ZIP code, 5 digits or ZIP+4 (format: 12345 or 12345-6789). |
| `zip_us` | `^\d{5}$` | US ZIP code, 5 digits only (format: 12345). |
| `numeric` | `^\d+$` | Digits only (no decimals, no separators). |
| `alpha` | `^[a-zA-Z]+$` | Letters only (no spaces, numbers, or special characters). |
| `alphanumeric` | `^[a-zA-Z0-9]+$` | Letters and digits only (no spaces or special characters). |
| `phone_us` | `^\(?[2-9]\d{2}\)?[-.\s]?\d{3}[-.\s]?\d{4}$` | US phone number (formats: (555) 123-4567, 555-123-4567, 5551234567). |
| `phone_intl` | `^\+[1-9]\d{6,14}$` | International phone number in E.164 format (format: +15551234567). |
When both `validation` and `pattern` are set on a field, the `pattern` regex takes precedence. The `validation` preset is ignored in that case.
Validation only applies to `text` and `cells` field types. Other field types (date, number, select, etc.) have their own built-in format enforcement.
## Creating templates
### From PDF
Upload one or more PDF files to create a template. DocuTrust extracts pages and creates a blank field schema that you can populate later.
```bash cURL theme={null}
curl -X POST "$DOCUTRUST_URL/api/templates/pdf" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN" \
-F "files[]=@/path/to/document.pdf" \
-F "name=Service Agreement" \
-F "external_id=sa-2026-001" \
-F "folder_name=Legal Contracts"
```
```javascript Node.js theme={null}
const fs = require("fs");
const form = new FormData();
form.append("files[]", new Blob([fs.readFileSync("./document.pdf")]), "document.pdf");
form.append("name", "Service Agreement");
form.append("external_id", "sa-2026-001");
form.append("folder_name", "Legal Contracts");
const response = await fetch(`${process.env.DOCUTRUST_URL}/api/templates/pdf`, {
method: "POST",
headers: { "X-Auth-Token": process.env.DOCUTRUST_TOKEN },
body: form,
});
const template = await response.json();
```
```python Python theme={null}
import requests
import os
url = f"{os.environ['DOCUTRUST_URL']}/api/templates/pdf"
headers = {"X-Auth-Token": os.environ["DOCUTRUST_TOKEN"]}
with open("document.pdf", "rb") as f:
files = {"files[]": ("document.pdf", f, "application/pdf")}
data = {
"name": "Service Agreement",
"external_id": "sa-2026-001",
"folder_name": "Legal Contracts",
}
response = requests.post(url, headers=headers, files=files, data=data)
template = response.json()
```
### From DOCX
Upload a Word document. DocuTrust converts it to PDF internally while preserving layout and formatting.
```bash theme={null}
curl -X POST "$DOCUTRUST_URL/api/templates/docx" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN" \
-F "file=@/path/to/document.docx" \
-F "name=Employment Contract"
```
### From HTML
Send raw HTML to create a template. This is useful for programmatically generating documents with dynamic layouts.
```bash theme={null}
curl -X POST "$DOCUTRUST_URL/api/templates/html" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Invoice Template",
"html": "Invoice #{{invoice_number}}
Amount: ${{amount}}
Due: {{due_date}}
"
}'
```
Use double-brace tokens like `{{invoice_number}}` in your HTML. These can be pre-filled via the API when creating submissions.
## Retrieving templates
### Get a single template
```bash theme={null}
curl "$DOCUTRUST_URL/api/templates/tpl_7VQhP2tM9xA1kR8bN" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN"
```
**Response:**
```json theme={null}
{
"id": "tpl_7VQhP2tM9xA1kR8bN",
"name": "Service Agreement",
"slug": "qk7x9m2p",
"external_id": "contract-sa-2026",
"folder_name": "Legal Contracts",
"source": "builder",
"shared": true,
"field_count": 8,
"submitter_count": 2,
"schema": [
{
"uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"name": "Full Name",
"type": "text",
"submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"required": true,
"readonly": false,
"key": "full_name",
"default_value": "",
"placeholder": "Enter your full legal name",
"options": null,
"areas": [
{
"page": 0,
"x": 0.12,
"y": 0.45,
"w": 0.35,
"h": 0.03,
"attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
},
{
"uuid": "d4e5f6a7-b8c9-0123-def0-345678901234",
"name": "Signature",
"type": "signature",
"submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"required": true,
"readonly": false,
"key": "client_signature",
"default_value": null,
"placeholder": null,
"options": null,
"areas": [
{
"page": 2,
"x": 0.10,
"y": 0.72,
"w": 0.30,
"h": 0.06,
"attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
}
],
"submitters": [
{
"uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Client"
},
{
"uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "Company Representative"
}
],
"thumbnail_url": "/api/templates/tpl_7VQhP2tM9xA1kR8bN/documents/thumbnail",
"created_at": "2026-04-01T09:00:00.000Z",
"updated_at": "2026-04-08T14:30:00.000Z"
}
```
### List all templates
```bash theme={null}
curl "$DOCUTRUST_URL/api/templates?limit=25" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN"
```
Results are paginated using cursor-based pagination. See the [Pagination guide](/guides/pagination) for details.
**Response:**
```json theme={null}
{
"data": [
{
"id": "tpl_7VQhP2tM9xA1kR8bN",
"name": "Service Agreement",
"slug": "qk7x9m2p",
"external_id": "contract-sa-2026",
"folder_name": "Legal Contracts",
"source": "builder",
"shared": true,
"field_count": 8,
"submitter_count": 2,
"schema": [],
"submitters": [
{
"uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Client"
},
{
"uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "Company Representative"
}
],
"thumbnail_url": "/api/templates/tpl_7VQhP2tM9xA1kR8bN/documents/thumbnail",
"created_at": "2026-04-01T09:00:00.000Z",
"updated_at": "2026-04-08T14:30:00.000Z"
},
{
"id": "tpl_2bJ9nQ8wY6rT5mK1p",
"name": "NDA - Standard",
"slug": "m2n9p4q7",
"external_id": null,
"folder_name": "Legal Contracts",
"source": "api",
"shared": false,
"field_count": 5,
"submitter_count": 2,
"schema": [],
"submitters": [
{
"uuid": "e5f6a7b8-c9d0-1234-ef01-456789012345",
"name": "Disclosing Party"
},
{
"uuid": "f6a7b8c9-d0e1-2345-f012-567890123456",
"name": "Receiving Party"
}
],
"thumbnail_url": "/api/templates/tpl_2bJ9nQ8wY6rT5mK1p/documents/thumbnail",
"created_at": "2026-03-15T11:20:00.000Z",
"updated_at": "2026-03-20T16:45:00.000Z"
}
],
"pagination": {
"count": 2,
"next": 35,
"prev": null
}
}
```
### Filter by folder
```bash theme={null}
curl "$DOCUTRUST_URL/api/templates?folder_name=Legal+Contracts&limit=25" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN"
```
### Filter by external ID
```bash theme={null}
curl "$DOCUTRUST_URL/api/templates?external_id=contract-sa-2026" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN"
```
## Updating templates
Update a template's name, schema, submitters, folder, or sharing settings with a PUT request.
```bash theme={null}
curl -X PUT "$DOCUTRUST_URL/api/templates/tpl_7VQhP2tM9xA1kR8bN" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Service Agreement v2",
"external_id": "contract-sa-2026-v2",
"folder_name": "Legal Contracts",
"shared": true,
"submitters": [
{
"uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Client"
},
{
"uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "Company Representative"
}
],
"schema": [
{
"uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"name": "Full Name",
"type": "text",
"submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"required": true,
"readonly": false,
"key": "full_name",
"default_value": "",
"placeholder": "Enter your full legal name",
"options": null,
"areas": [
{
"page": 0,
"x": 0.12,
"y": 0.45,
"w": 0.35,
"h": 0.03,
"attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
}
]
}'
```
Updating the `schema` or `submitters` replaces the entire array. Always include all fields and roles you want to keep, not just the ones you are changing.
## Fixing auto-mapping safely (API)
If AI smart setup assigned fields to the wrong submitter, use these endpoints instead of replacing the full schema:
* `POST /api/templates/{id}/validate_assignments` — dry-run validator
* `POST /api/templates/{id}/remap_submitters` — apply targeted remaps
### 1) Validate proposed remap
```bash theme={null}
curl -X POST "$DOCUTRUST_URL/api/templates/tpl_7VQhP2tM9xA1kR8bN/validate_assignments" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"field_assignments": [
{
"field_uuid": "d4e5f6a7-b8c9-0123-def0-345678901234",
"submitter_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
],
"required_signature_submitter_uuids": [
"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"b2c3d4e5-f6a7-8901-bcde-f12345678901"
]
}'
```
### 2) Preview remap (`dry_run`)
```bash theme={null}
curl -X POST "$DOCUTRUST_URL/api/templates/tpl_7VQhP2tM9xA1kR8bN/remap_submitters" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"dry_run": true,
"field_assignments": [
{
"field_uuid": "d4e5f6a7-b8c9-0123-def0-345678901234",
"submitter_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
]
}'
```
### 3) Apply remap
```bash theme={null}
curl -X POST "$DOCUTRUST_URL/api/templates/tpl_7VQhP2tM9xA1kR8bN/remap_submitters" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"field_assignments": [
{
"field_uuid": "d4e5f6a7-b8c9-0123-def0-345678901234",
"submitter_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
]
}'
```
### Validation checks returned by API
The validator returns structured issues such as:
* `unknown_field_uuid`
* `unknown_submitter_uuid`
* `duplicate_field_assignment`
* `submitter_without_fields`
* `required_submitter_missing_signature`
## Cloning templates
Create an independent copy of an existing template. The clone gets a new ID and slug but inherits the schema, submitters, and documents.
```bash theme={null}
curl -X POST "$DOCUTRUST_URL/api/templates/tpl_7VQhP2tM9xA1kR8bN/clone" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Service Agreement - West Region"
}'
```
**Response:**
```json theme={null}
{
"id": "tpl_5cLm2R8qNx1vU9zK4",
"name": "Service Agreement - West Region",
"slug": "w4x8y2z6",
"external_id": null,
"folder_name": "Legal Contracts",
"source": "clone",
"shared": false,
"field_count": 8,
"submitter_count": 2,
"schema": [],
"submitters": [
{
"uuid": "11223344-5566-7788-99aa-bbccddeeff00",
"name": "Client"
},
{
"uuid": "22334455-6677-8899-aabb-ccddeeff0011",
"name": "Company Representative"
}
],
"thumbnail_url": null,
"created_at": "2026-04-08T15:00:00.000Z",
"updated_at": "2026-04-08T15:00:00.000Z"
}
```
The cloned template gets new submitter UUIDs. If you have code that references the original UUIDs, update it to use the new ones.
## Merging templates
Combine two or more templates into a single document. This is useful for assembling contracts from modular sections (e.g., terms + addendum + signature page).
```bash theme={null}
curl -X POST "$DOCUTRUST_URL/api/templates/merge" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"template_ids": ["tpl_7VQhP2tM9xA1kR8bN", "tpl_2bJ9nQ8wY6rT5mK1p"],
"name": "Combined Agreement + NDA"
}'
```
**Response:**
```json theme={null}
{
"id": "tpl_8wQ1mN6rZ3kT5yP2v",
"name": "Combined Agreement + NDA",
"slug": "v3w7x1y5",
"external_id": null,
"folder_name": "Default",
"source": "api",
"shared": false,
"field_count": 13,
"submitter_count": 2,
"schema": [],
"submitters": [
{
"uuid": "33445566-7788-99aa-bbcc-ddeeff001122",
"name": "Client"
},
{
"uuid": "44556677-8899-aabb-ccdd-eeff00112233",
"name": "Company Representative"
}
],
"thumbnail_url": null,
"created_at": "2026-04-08T15:05:00.000Z",
"updated_at": "2026-04-08T15:05:00.000Z"
}
```
Templates are merged in the order provided. Fields and pages from the second template appear after the first.
## AI field detection
DocuTrust can automatically analyze a template's document and detect where fields should be placed. This is especially useful for complex PDFs with many signature lines, date fields, and text blanks.
```bash theme={null}
curl -X POST "$DOCUTRUST_URL/api/templates/tpl_7VQhP2tM9xA1kR8bN/ai/smart_create" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
```
The AI analyzes the document, identifies field locations, assigns appropriate types, and updates the template schema. You can review and adjust the detected fields in the template builder or via the API.
Additional AI endpoints:
| Endpoint | Description |
| ----------------------------------------- | ----------------------------------------------------------- |
| `POST /api/templates/{id}/ai/analyze` | Analyze document structure without modifying the template. |
| `POST /api/templates/{id}/ai/smart_setup` | Full auto-setup: detect fields, assign roles, and set keys. |
| `POST /api/templates/{id}/ai/assign_keys` | Auto-assign machine-readable keys to existing fields. |
| `GET /api/templates/{id}/ai/status` | Check the status of a running AI analysis job. |
## Managing documents
### Replace or add documents
Upload new documents to an existing template:
```bash theme={null}
curl -X PUT "$DOCUTRUST_URL/api/templates/tpl_7VQhP2tM9xA1kR8bN/documents" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN" \
-F "files[]=@/path/to/updated-contract.pdf"
```
### Download a document PDF
Retrieve the original uploaded document:
```bash theme={null}
curl -O -J "$DOCUTRUST_URL/api/templates/tpl_7VQhP2tM9xA1kR8bN/documents/{document_id}/pdf" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN"
```
### Thumbnails
Get a thumbnail image of the first page:
```bash theme={null}
curl -O -J "$DOCUTRUST_URL/api/templates/tpl_7VQhP2tM9xA1kR8bN/documents/thumbnail" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN"
```
If a thumbnail has not been generated yet, trigger generation manually:
```bash theme={null}
curl -X POST "$DOCUTRUST_URL/api/templates/tpl_7VQhP2tM9xA1kR8bN/documents/generate_thumbnail" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN"
```
## Archiving templates
Archive a template to remove it from active use. Archived templates are not deleted -- existing submissions remain intact -- but no new submissions can be created from them.
```bash theme={null}
curl -X DELETE "$DOCUTRUST_URL/api/templates/tpl_7VQhP2tM9xA1kR8bN" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN"
```
This uses the HTTP DELETE method but performs a soft archive, not a permanent deletion. The template can still be retrieved via the API using its ID.
## Formula fields
Formula fields compute their value dynamically from other fields using arithmetic expressions. Use them for calculated totals, taxes, discounts, and other derived values.
### Formula syntax
Add a `formula` property to any `number` field in the template schema. The formula can reference other fields by name using `{Field Name}` syntax and supports standard arithmetic operators.
```json theme={null}
{
"uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Subtotal",
"type": "number",
"submitter_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"required": true,
"readonly": true,
"key": "subtotal",
"default_value": null,
"placeholder": null,
"formula": "{Quantity} * {Unit Price}",
"options": null,
"areas": [
{
"page": 0,
"x": 0.55,
"y": 0.45,
"w": 0.20,
"h": 0.03,
"attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
}
```
### Supported operators
| Operator | Description | Example |
| -------- | -------------- | ---------------------------------------- |
| `+` | Addition | `{Price} + {Shipping}` |
| `-` | Subtraction | `{Total} - {Discount}` |
| `*` | Multiplication | `{Quantity} * {Unit Price}` |
| `/` | Division | `{Total} / {Installments}` |
| `()` | Grouping | `({Subtotal} + {Tax}) * {Discount Rate}` |
### Full example: invoice with tax
```json theme={null}
{
"schema": [
{
"uuid": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
"name": "Quantity",
"type": "number",
"submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"required": true,
"readonly": false,
"key": "quantity",
"default_value": "1",
"placeholder": "Enter quantity",
"formula": null,
"options": null,
"areas": [
{
"page": 0,
"x": 0.12,
"y": 0.40,
"w": 0.15,
"h": 0.03,
"attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
},
{
"uuid": "f2b3c4d5-e6f7-8901-bcde-f12345678901",
"name": "Unit Price",
"type": "number",
"submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"required": true,
"readonly": false,
"key": "unit_price",
"default_value": "0",
"placeholder": "Enter price",
"formula": null,
"options": null,
"areas": [
{
"page": 0,
"x": 0.30,
"y": 0.40,
"w": 0.15,
"h": 0.03,
"attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
},
{
"uuid": "f3c4d5e6-f7a8-9012-cdef-123456789012",
"name": "Subtotal",
"type": "number",
"submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"required": true,
"readonly": true,
"key": "subtotal",
"default_value": null,
"placeholder": null,
"formula": "{Quantity} * {Unit Price}",
"options": null,
"areas": [
{
"page": 0,
"x": 0.55,
"y": 0.40,
"w": 0.15,
"h": 0.03,
"attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
},
{
"uuid": "f4d5e6f7-a8b9-0123-def0-234567890123",
"name": "Tax",
"type": "number",
"submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"required": true,
"readonly": true,
"key": "tax",
"default_value": null,
"placeholder": null,
"formula": "{Subtotal} * 0.0875",
"options": null,
"areas": [
{
"page": 0,
"x": 0.55,
"y": 0.45,
"w": 0.15,
"h": 0.03,
"attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
},
{
"uuid": "f5e6f7a8-b9c0-1234-ef01-345678901234",
"name": "Grand Total",
"type": "number",
"submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"required": true,
"readonly": true,
"key": "grand_total",
"default_value": null,
"placeholder": null,
"formula": "{Subtotal} + {Tax}",
"options": null,
"areas": [
{
"page": 0,
"x": 0.55,
"y": 0.50,
"w": 0.15,
"h": 0.03,
"attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
}
]
}
```
Formula evaluation uses safe arithmetic parsing -- no arbitrary code execution. Only numeric values, field references, arithmetic operators, and parentheses are allowed. Division by zero returns `0`.
Formula fields are typically set to `readonly: true` so the signer sees the computed value but cannot edit it. If you leave `readonly: false`, the signer can override the calculated value.
### Dynamic payment pricing
Combine formula fields with the `payment` field type to compute dynamic payment amounts based on signer input:
```json theme={null}
{
"uuid": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
"name": "Payment Amount",
"type": "payment",
"submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"required": true,
"readonly": false,
"key": "payment_amount",
"default_value": null,
"placeholder": null,
"formula": "{Grand Total}",
"options": null,
"areas": [
{
"page": 1,
"x": 0.12,
"y": 0.60,
"w": 0.35,
"h": 0.06,
"attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
}
```
## Conditional document display
Control which documents in a multi-document template are shown to the signer based on field values. Use the `document_conditions` property in the template `preferences` to define conditions.
### Configuration
Set `document_conditions` in the template preferences via `PUT /api/templates/:id`:
```bash theme={null}
curl -X PUT "$DOCUTRUST_URL/api/templates/tpl_7VQhP2tM9xA1kR8bN" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"preferences": {
"document_conditions": [
{
"document_id": 43,
"field_uuid": "f6a7b8c9-d0e1-2345-f012-567890123456",
"operator": "equals",
"value": "Premium"
},
{
"document_id": 44,
"field_uuid": "f6a7b8c9-d0e1-2345-f012-567890123456",
"operator": "equals",
"value": "Enterprise"
}
]
}
}'
```
### Condition properties
| Property | Type | Description |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `document_id` | integer | The ID of the document attachment to conditionally show or hide. |
| `field_uuid` | string | UUID of the field whose value is evaluated. |
| `operator` | string | Comparison operator: `"equals"`, `"not_equals"`, `"contains"`, `"not_contains"`, `"is_empty"`, `"is_not_empty"`. |
| `value` | string | The value to compare against. Not required for `is_empty` and `is_not_empty` operators. |
### Full example
A template with three documents -- a base agreement, a premium addendum, and an enterprise addendum -- where the addenda are shown conditionally based on the plan selection:
```json theme={null}
{
"preferences": {
"document_conditions": [
{
"document_id": 43,
"field_uuid": "f6a7b8c9-d0e1-2345-f012-567890123456",
"operator": "equals",
"value": "Premium"
},
{
"document_id": 44,
"field_uuid": "f6a7b8c9-d0e1-2345-f012-567890123456",
"operator": "equals",
"value": "Enterprise"
}
]
}
}
```
When the signer selects "Premium" from the `Payment Method` field (or any select/radio field referenced by `field_uuid`), document 43 (the premium addendum) is displayed. When they select "Enterprise", document 44 is shown instead. The base agreement document (without a condition) is always shown.
Conditions are evaluated in real time as the signer fills in fields. Documents appear or disappear dynamically without page reload.
## Document upload limits
Each decoded PDF, DOCX, or HTML source is limited to 25 MB by default, and each generated PDF is
limited to 100 pages. Multipart uploads are checked before reading, while Base64 uploads use
strict decoding and are checked both before and after decoding. DOCX and HTML sources are checked
before conversion; the resulting PDF is page-checked before any template or document is stored.
An over-limit request returns `422` naming the file and applicable limit. Self-hosted operators
may adjust `MAX_DOCUMENT_SIZE_MB` and `MAX_DOCUMENT_PAGES`; invalid or non-positive values fall
back to the defaults above.