Glossary

A reference of key terms and concepts used throughout DocuTrust’s documentation, API, and user interface.

Template

A reusable document with field definitions and submitter roles. Templates are created by uploading a PDF, DOCX, or HTML file and then defining fields (text inputs, signature areas, date pickers, checkboxes, etc.) on the document pages using the visual Builder. Each template can be used to create multiple submissions. Templates store their field definitions in a schema JSON column and their submitter roles in a submitters JSON column. Example: An “Employment Agreement” template with fields for employee name, start date, salary, and signature, assigned to two roles: “Employee” and “HR Manager”.

Submission

An instance of a template sent to specific people for signing. When you create a submission, DocuTrust generates a copy of the template document and assigns it to the specified submitters. Each submission tracks its own lifecycle independently. Statuses:

Status	Description
`draft`	Saved but not yet sent to any submitters. Can be edited and sent later.
`pending`	Active and waiting for one or more submitters to complete their fields.
`completed`	All submitters have completed their fields. The signed document is finalized.
`expired`	The submission passed its `expire_at` timestamp before all submitters finished.
`archived`	Moved to the archive. The submission and its documents are retained but hidden from the default view.

Submitter

An individual signer within a submission. Each submitter is assigned a role (matching one of the template’s defined roles), an email address, and optionally a name, phone number, and external ID. Submitters access their signing page via a unique URL. Statuses:

Status	Value	Description
`waiting`	0	The submitter has not yet been invited to sign (e.g., waiting for a previous submitter in sequential order).
`sent`	1	The signing invitation has been sent to the submitter’s email.
`opened`	2	The submitter has opened the signing link in their browser.
`completed`	3	The submitter has completed all required fields and submitted their responses.
`declined`	4	The submitter has declined to sign the document.
`expired`	5	The submission expired before this submitter could complete their fields.

Field

An input area on a document that a submitter fills in during the signing process. Fields are defined in the template schema and positioned on specific pages of the document. Each field has a type that determines what kind of input it accepts. Field types:

Type	Description
`text`	Free-form text input.
`signature`	A drawn, typed, or uploaded signature.
`initials`	A smaller signature area for initialing pages.
`date`	A date picker.
`checkbox`	A boolean checkbox.
`radio`	A group of radio buttons (select one).
`select`	A dropdown menu.
`number`	A numeric input.
`phone`	A phone number input with formatting.
`image`	An uploaded image (e.g., photo ID, company logo).
`stamp`	A pre-defined stamp or seal.
`cells`	Individual character cells (e.g., for account numbers or codes).

Schema

The JSON array of field definitions stored on a template. Each field in the schema includes properties such as uuid, name, type, submitter_uuid (which role the field belongs to), required, default_value, and areas (where the field is placed on the document). The schema is the source of truth for what data a template collects. Example schema entry:

{
  "uuid": "f7a1b2c3-d4e5-6789-abcd-ef0123456789",
  "name": "Employee Signature",
  "type": "signature",
  "submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
  "required": true,
  "default_value": null,
  "readonly": false,
  "areas": [
    {
      "page": 2,
      "x": 0.08,
      "y": 0.72,
      "w": 0.35,
      "h": 0.05
    }
  ]
}

Slug

A unique URL-safe identifier for submissions and submitters. Slugs are randomly generated alphanumeric strings that serve as public-facing identifiers in URLs. Unlike integer IDs, slugs are non-sequential and non-guessable, which prevents enumeration attacks. Usage: The submitter slug is used in the signing URL: https://your-app.com/s/SUBMITTER_SLUG

Role

A named signing position in a template that maps to a submitter. Roles define which fields each signer is responsible for. When creating a submission, each submitter is assigned a role that must match one of the roles defined in the template. Examples: “First Party”, “Second Party”, “Witness”, “Employee”, “Manager”, “Landlord”, “Tenant”. A template with two roles (“Employee” and “HR Manager”) requires two submitters when creating a submission, each assigned to one of those roles.

Areas

The positioned regions on a document page where a field appears visually. Each area is defined by a page number and percentage-based coordinates (x, y, w, h) relative to the page dimensions. A single field can have multiple areas if it should appear on multiple pages. Coordinate system:

Property	Type	Description
`page`	integer	The page number (0-indexed) where the area appears.
`x`	float	Horizontal position of the area’s left edge, as a percentage of page width (0.0 to 1.0).
`y`	float	Vertical position of the area’s top edge, as a percentage of page height (0.0 to 1.0).
`w`	float	Width of the area, as a percentage of page width (0.0 to 1.0).
`h`	float	Height of the area, as a percentage of page height (0.0 to 1.0).

Example: An area at { "page": 0, "x": 0.08, "y": 0.72, "w": 0.35, "h": 0.05 } is positioned 8% from the left edge, 72% from the top, and spans 35% of the page width by 5% of the page height on the first page.

Signing URL

The URL a submitter visits to view and sign their document. Each submitter receives a unique signing URL based on their slug. The URL is valid until the submitter completes their fields, declines to sign, or the submission expires. Format: https://your-app.com/s/SUBMITTER_SLUG The signing URL can be delivered via email (automatic), returned from the API for custom delivery, or embedded in an iframe within your application.

External ID

Your system’s identifier attached to templates or submitters for cross-referencing. External IDs allow you to link DocuTrust resources back to records in your own database without maintaining a separate mapping table. Usage examples:

Attach a customer ID from your CRM to a submitter: "external_id": "cust_12345"
Attach an internal document reference to a template: "external_id": "contract-v3-2026"
Query resources by external ID: GET /api/submitters?external_id=cust_12345

External IDs are optional, free-form strings with no uniqueness constraint enforced by DocuTrust.

​Glossary

​Template

​Submission

​Submitter

​Field

​Schema

​Slug

​Role

​Areas

​Signing URL

​External ID