> ## 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.
# Reusable Saved Fields
> Save field configurations for reuse across templates.
# 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
1. Configure a field with the desired properties (type, validation, options, default value, etc.).
2. Save it via the API or the template builder UI.
3. When creating or editing a template, select the saved field to instantly apply its configuration.
4. 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`
```bash theme={null}
curl "$DOCUTRUST_URL/api/settings/saved_fields" \
-H "X-Auth-Token: $DOCUTRUST_TOKEN"
```
**Response:**
```json theme={null}
{
"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`
```bash theme={null}
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):**
```json theme={null}
{
"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`
```bash theme={null}
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):**
```json theme={null}
{
"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:
```bash theme={null}
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.