Reusable Saved Fields

Saved fields let you create reusable field configurations that can be applied across multiple templates. Instead of re-configuring the same field properties (type, validation, default value, options) every time you create a template, save a field once and reuse it everywhere.

How it works

Configure a field with the desired properties (type, validation, options, default value, etc.).
Save it via the API or the template builder UI.
When creating or editing a template, select the saved field to instantly apply its configuration.
Changes to a saved field do not retroactively update templates that already use it — each template gets a copy at the time of application.

API endpoints

List saved fields

Retrieve all saved fields for your account. GET /api/settings/saved_fields

curl "$DOCUTRUST_URL/api/settings/saved_fields" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN"

Response:

{
  "data": [
    {
      "id": 1,
      "name": "Full Legal Name",
      "type": "text",
      "required": true,
      "readonly": false,
      "key": "full_legal_name",
      "default_value": "",
      "placeholder": "Enter your full legal name as it appears on government ID",
      "validation": null,
      "pattern": null,
      "options": null,
      "description": "Standard name field for legal documents. Requires the signer to enter their full legal name.",
      "created_at": "2026-04-01T09:00:00.000Z",
      "updated_at": "2026-04-01T09:00:00.000Z"
    },
    {
      "id": 2,
      "name": "SSN",
      "type": "text",
      "required": true,
      "readonly": false,
      "key": "ssn",
      "default_value": "",
      "placeholder": "123-45-6789",
      "validation": "ssn",
      "pattern": null,
      "options": null,
      "description": "Social Security Number with format validation (XXX-XX-XXXX).",
      "created_at": "2026-04-01T09:05:00.000Z",
      "updated_at": "2026-04-01T09:05:00.000Z"
    },
    {
      "id": 3,
      "name": "US State",
      "type": "select",
      "required": true,
      "readonly": false,
      "key": "us_state",
      "default_value": null,
      "placeholder": "Select a state",
      "validation": null,
      "pattern": null,
      "options": [
        "Alabama", "Alaska", "Arizona", "Arkansas", "California",
        "Colorado", "Connecticut", "Delaware", "Florida", "Georgia",
        "Hawaii", "Idaho", "Illinois", "Indiana", "Iowa",
        "Kansas", "Kentucky", "Louisiana", "Maine", "Maryland",
        "Massachusetts", "Michigan", "Minnesota", "Mississippi", "Missouri",
        "Montana", "Nebraska", "Nevada", "New Hampshire", "New Jersey",
        "New Mexico", "New York", "North Carolina", "North Dakota", "Ohio",
        "Oklahoma", "Oregon", "Pennsylvania", "Rhode Island", "South Carolina",
        "South Dakota", "Tennessee", "Texas", "Utah", "Vermont",
        "Virginia", "Washington", "West Virginia", "Wisconsin", "Wyoming"
      ],
      "description": "Dropdown with all 50 US states.",
      "created_at": "2026-04-01T09:10:00.000Z",
      "updated_at": "2026-04-01T09:10:00.000Z"
    },
    {
      "id": 4,
      "name": "Standard Signature",
      "type": "signature",
      "required": true,
      "readonly": false,
      "key": "signature",
      "default_value": null,
      "placeholder": null,
      "validation": null,
      "pattern": null,
      "options": null,
      "description": "Standard signature field for all document types.",
      "created_at": "2026-04-01T09:15:00.000Z",
      "updated_at": "2026-04-01T09:15:00.000Z"
    },
    {
      "id": 5,
      "name": "EIN",
      "type": "text",
      "required": true,
      "readonly": false,
      "key": "ein",
      "default_value": "",
      "placeholder": "12-3456789",
      "validation": "ein",
      "pattern": null,
      "options": null,
      "description": "Employer Identification Number with format validation (XX-XXXXXXX).",
      "created_at": "2026-04-01T09:20:00.000Z",
      "updated_at": "2026-04-01T09:20:00.000Z"
    },
    {
      "id": 6,
      "name": "Payment Method",
      "type": "select",
      "required": false,
      "readonly": false,
      "key": "payment_method",
      "default_value": "Credit Card",
      "placeholder": "Select payment method",
      "validation": null,
      "pattern": null,
      "options": ["Credit Card", "Bank Transfer", "Check", "PayPal", "Wire Transfer"],
      "description": "Standard payment method dropdown with common options.",
      "created_at": "2026-04-01T09:25:00.000Z",
      "updated_at": "2026-04-01T09:25:00.000Z"
    },
    {
      "id": 7,
      "name": "US Phone",
      "type": "text",
      "required": false,
      "readonly": false,
      "key": "phone_us",
      "default_value": "",
      "placeholder": "(555) 123-4567",
      "validation": "phone_us",
      "pattern": null,
      "options": null,
      "description": "US phone number with format validation.",
      "created_at": "2026-04-01T09:30:00.000Z",
      "updated_at": "2026-04-01T09:30:00.000Z"
    },
    {
      "id": 8,
      "name": "Invoice Number",
      "type": "text",
      "required": true,
      "readonly": false,
      "key": "invoice_number",
      "default_value": "",
      "placeholder": "INV-2026-0001",
      "validation": null,
      "pattern": "^INV-\\d{4}-\\d{4}$",
      "options": null,
      "description": "Invoice number with custom regex pattern validation (INV-YYYY-NNNN).",
      "created_at": "2026-04-01T09:35:00.000Z",
      "updated_at": "2026-04-01T09:35:00.000Z"
    }
  ],
  "pagination": {
    "count": 8,
    "next": null,
    "prev": null
  }
}

Create a saved field

Save a new reusable field configuration. POST /api/settings/saved_fields

curl -X POST "$DOCUTRUST_URL/api/settings/saved_fields" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Company EIN",
    "type": "text",
    "required": true,
    "readonly": false,
    "key": "company_ein",
    "default_value": "",
    "placeholder": "12-3456789",
    "validation": "ein",
    "pattern": null,
    "options": null,
    "description": "Employer Identification Number for company tax forms. Validates XX-XXXXXXX format."
  }'

Request parameters:

Parameter	Type	Required	Description
`name`	string	Yes	Human-readable field name.
`type`	string	Yes	Field type (`text`, `signature`, `date`, `number`, `select`, `radio`, `checkbox`, `file`, `image`, `stamp`, `cells`, `phone`, `initials`, `payment`, `phone_verification`, `multi_select`).
`required`	boolean	No	Whether the field is required. Defaults to `false`.
`readonly`	boolean	No	Whether the field is read-only. Defaults to `false`.
`key`	string	No	Machine-readable key for API pre-filling.
`default_value`	string or null	No	Default value shown when the signer opens the form.
`placeholder`	string or null	No	Placeholder text shown in empty fields.
`validation`	string or null	No	Validation preset name (e.g., `"ssn"`, `"ein"`, `"email"`, `"zip"`).
`pattern`	string or null	No	Custom regex validation pattern.
`options`	array or null	No	Available choices for `select`, `radio`, and `multi_select` fields.
`description`	string or null	No	Human-readable description for reference (not shown to signers).

Response (201 Created):

{
  "id": 9,
  "name": "Company EIN",
  "type": "text",
  "required": true,
  "readonly": false,
  "key": "company_ein",
  "default_value": "",
  "placeholder": "12-3456789",
  "validation": "ein",
  "pattern": null,
  "options": null,
  "description": "Employer Identification Number for company tax forms. Validates XX-XXXXXXX format.",
  "created_at": "2026-04-09T10:00:00.000Z",
  "updated_at": "2026-04-09T10:00:00.000Z"
}

Delete a saved field

Remove a saved field from your account. This does not affect templates that already use a copy of this field. DELETE /api/settings/saved_fields/:id

curl -X DELETE "$DOCUTRUST_URL/api/settings/saved_fields/9" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN"

Response: HTTP 204 No Content on success. Error response (404 Not Found):

{
  "error": "not_found",
  "message": "Saved field not found."
}

Using saved fields in templates

Via the template builder

In the template builder, the field palette includes a “Saved Fields” section below the standard field types. Click a saved field to place it on the document. The field inherits all saved properties (type, validation, default value, options, etc.).

Via the API

When creating or updating a template schema, reference a saved field by including its properties. There is no special reference syntax — you copy the configuration into the schema:

curl -X PUT "$DOCUTRUST_URL/api/templates/42" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": [
      {
        "uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "name": "Full Legal Name",
        "type": "text",
        "submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "required": true,
        "readonly": false,
        "key": "full_legal_name",
        "default_value": "",
        "placeholder": "Enter your full legal name as it appears on government ID",
        "validation": null,
        "pattern": null,
        "options": null,
        "areas": [
          {
            "page": 0,
            "x": 0.12,
            "y": 0.35,
            "w": 0.35,
            "h": 0.03,
            "attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
          }
        ]
      },
      {
        "uuid": "d4e5f6a7-b8c9-0123-def0-345678901234",
        "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.40,
            "w": 0.25,
            "h": 0.03,
            "attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
          }
        ]
      },
      {
        "uuid": "e5f6a7b8-c9d0-1234-ef01-456789012345",
        "name": "Standard Signature",
        "type": "signature",
        "submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "required": true,
        "readonly": false,
        "key": "signature",
        "default_value": null,
        "placeholder": null,
        "validation": null,
        "pattern": null,
        "options": null,
        "areas": [
          {
            "page": 1,
            "x": 0.10,
            "y": 0.72,
            "w": 0.30,
            "h": 0.06,
            "attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
          }
        ]
      }
    ]
  }'

Saved fields are copied into the template schema when applied. Updating or deleting a saved field does not change templates that already use it.

Use saved fields to enforce consistent field naming and validation across your organization. For example, save a “Company Name” field with a standard key, placeholder, and validation pattern so every template uses the same configuration.

The key property of a saved field should be unique across your organization’s field library. If two saved fields share the same key and are both applied to the same template, the values object will have key collisions when pre-filling or reading submission data.

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

Reusable Saved Fields

Reusable Saved Fields

How it works

API endpoints

List saved fields

Create a saved field

Delete a saved field

Using saved fields in templates

Via the template builder

Via the API

​Reusable Saved Fields

​How it works

​API endpoints

​List saved fields

​Create a saved field

​Delete a saved field

​Using saved fields in templates

​Via the template builder

​Via the API

Reusable Saved Fields

How it works

API endpoints

List saved fields

Create a saved field

Delete a saved field

Using saved fields in templates

Via the template builder

Via the API