Templates - SpitShake

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:

{
  "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 below).
`submitters`	array	The submitter roles (see 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.

{
  "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.

{
  "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 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

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:

Preset validation — Use the validation property with a preset name for common patterns (SSN, email, phone, etc.).
Custom regex — Use the pattern property with any regular expression string for custom formats.

Example: field with preset validation

{
  "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

{
  "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.

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"

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();

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.

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.

curl -X POST "$DOCUTRUST_URL/api/templates/html" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice Template",
    "html": "<html><body><h1>Invoice #{{invoice_number}}</h1><p>Amount: ${{amount}}</p><p>Due: {{due_date}}</p></body></html>"
  }'

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

curl "$DOCUTRUST_URL/api/templates/tpl_7VQhP2tM9xA1kR8bN" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN"

Response:

{
  "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

curl "$DOCUTRUST_URL/api/templates?limit=25" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN"

Results are paginated using cursor-based pagination. See the Pagination guide for details. Response:

{
  "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

curl "$DOCUTRUST_URL/api/templates?folder_name=Legal+Contracts&limit=25" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN"

Filter by external ID

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.

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

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`)

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

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.

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:

{
  "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).

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:

{
  "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.

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:

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:

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:

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:

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.

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.

{
  "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

{
  "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:

{
  "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:

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:

{
  "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.

​Template object

​Submitter roles

​Field schema

​Field properties

​Field areas

​Field types

​Field validation

​Example: field with preset validation

​Example: field with custom regex pattern

​Validation presets

​Creating templates

​From PDF

​From DOCX

​From HTML

​Retrieving templates

​Get a single template

​List all templates

​Filter by folder

​Filter by external ID

​Updating templates

​Fixing auto-mapping safely (API)

​1) Validate proposed remap

​2) Preview remap (dry_run)

​3) Apply remap

​Validation checks returned by API

​Cloning templates

​Merging templates

​AI field detection

​Managing documents

​Replace or add documents

​Download a document PDF

​Thumbnails

​Archiving templates

​Formula fields

​Formula syntax

​Supported operators

​Full example: invoice with tax

​Dynamic payment pricing

​Conditional document display

​Configuration

​Condition properties

​Full example

​Document upload limits

Template object

Submitter roles

Field schema

Field properties

Field areas

Field types

Field validation

Example: field with preset validation

Example: field with custom regex pattern

Validation presets

Creating templates

From PDF

From DOCX

From HTML

Retrieving templates

Get a single template

List all templates

Filter by folder

Filter by external ID

Updating templates

Fixing auto-mapping safely (API)

1) Validate proposed remap

2) Preview remap (`dry_run`)

3) Apply remap

Validation checks returned by API

Cloning templates

Merging templates

AI field detection

Managing documents

Replace or add documents

Download a document PDF

Thumbnails

Archiving templates

Formula fields

Formula syntax

Supported operators

Full example: invoice with tax

Dynamic payment pricing

Conditional document display

Configuration

Condition properties

Full example

Document upload limits