Field Types

Overview

Documenso provides 11 distinct field types for collecting information from document recipients. Each field type serves specific purposes and supports various customization options.

Available Field Types

enum FieldType {
  SIGNATURE
  FREE_SIGNATURE
  INITIALS
  NAME
  EMAIL
  DATE
  TEXT
  NUMBER
  RADIO
  CHECKBOX
  DROPDOWN
}

Signature Fields

SIGNATURE

The primary signature field for legally binding signatures. Characteristics:

Recipients can draw, type, or upload their signature
Signature image is embedded in the PDF
Cryptographically sealed in the final document
Required for most legal agreements

Configuration:

{
  type: FieldType.SIGNATURE,
  fieldMeta: {
    type: 'signature',
    fontSize: 14,
    label: 'Signature',
    required: true
  }
}

Signature Methods:

Draw: Freehand signature using mouse/touch
Type: Typed name in signature font (Caveat)
Upload: Upload signature image (PNG/JPG)

Settings Control:

documentMeta: {
  typedSignatureEnabled: true,   // Allow typed signatures
  uploadSignatureEnabled: true,  // Allow uploaded signatures
  drawSignatureEnabled: true     // Allow drawn signatures
}

Use Cases:

Contract signatures
Agreement acceptance
Authorization forms
Legal documents

Signature fields are the only fields that create a verifiable signature record in the signing certificate.

FREE_SIGNATURE

A deprecated field type for backward compatibility. Use SIGNATURE instead.

INITIALS

For recipient initials, typically used to acknowledge specific clauses. Characteristics:

Smaller than signature field
Same input methods as signature
Often used multiple times per document
Indicates acknowledgment of specific sections

Configuration:

{
  type: FieldType.INITIALS,
  fieldMeta: {
    type: 'initials',
    fontSize: 12,
    textAlign: 'left',
    required: true
  }
}

Use Cases:

Acknowledging contract clauses
Page-by-page acknowledgment
Terms and conditions acceptance
Waiver sections
Risk disclosures

Identity Fields

NAME

Collects the recipient’s full name as text. Characteristics:

Text input field
Can be pre-filled from recipient data
Rendered as text in final PDF
Supports text alignment

Configuration:

{
  type: FieldType.NAME,
  fieldMeta: {
    type: 'name',
    fontSize: 12,
    textAlign: 'left',
    label: 'Full Name',
    placeholder: 'Enter your full name',
    required: true
  }
}

Use Cases:

Printed name below signature
Legal name entry
Witness names
Company representative names

EMAIL

Collects an email address from the recipient. Characteristics:

Text input with email validation
Can be pre-filled from recipient email
Validates email format
Supports text alignment

Configuration:

{
  type: FieldType.EMAIL,
  fieldMeta: {
    type: 'email',
    fontSize: 12,
    textAlign: 'left',
    label: 'Email Address',
    placeholder: '[email protected]',
    required: true
  }
}

Use Cases:

Contact information
Notification addresses
Alternative email collection
Company email verification

DATE

Collects or displays a date value. Characteristics:

Date picker interface
Can auto-fill with signing date
Formatted according to document settings
Timezone-aware

Configuration:

{
  type: FieldType.DATE,
  fieldMeta: {
    type: 'date',
    fontSize: 12,
    textAlign: 'left',
    label: 'Date',
    required: true
  }
}

Date Format: Controlled by document metadata:

documentMeta: {
  dateFormat: 'yyyy-MM-dd hh:mm a',  // Default format
  timezone: 'America/New_York'        // Timezone for dates
}

Use Cases:

Signature date
Effective date
Start/end dates
Birth dates
Event dates

Text Input Fields

TEXT

General-purpose text input field with advanced formatting options. Characteristics:

Single or multi-line text
Character limit support
Custom styling options
Line height and letter spacing control
Vertical alignment options

Configuration:

{
  type: FieldType.TEXT,
  fieldMeta: {
    type: 'text',
    text: '',                    // Default value
    fontSize: 12,
    textAlign: 'left',
    label: 'Comments',
    placeholder: 'Enter text here',
    characterLimit: 500,         // Max characters
    required: true,
    readOnly: false,
    lineHeight: 1.5,            // Line spacing
    letterSpacing: 0,           // Character spacing
    verticalAlign: 'middle'     // top | middle | bottom
  }
}

Advanced Options:

Line Height: 1.0 to 10.0 (default: 1.0)
Letter Spacing: 0 to 100 (default: 0)
Vertical Align: top, middle, bottom
Text Align: left, center, right

Use Cases:

Comments and notes
Address fields
Job titles
Company names
Custom responses
Terms and conditions

NUMBER

Numeric input field with validation and formatting. Characteristics:

Numeric-only input
Min/max value validation
Number formatting support
Decimal support

Configuration:

{
  type: FieldType.NUMBER,
  fieldMeta: {
    type: 'number',
    value: '',                  // Default value
    fontSize: 12,
    textAlign: 'right',
    numberFormat: '0,0.00',     // Number format pattern
    minValue: 0,                // Minimum allowed value
    maxValue: 1000000,          // Maximum allowed value
    label: 'Amount',
    placeholder: '0.00',
    required: true,
    readOnly: false,
    lineHeight: 1,
    letterSpacing: 0,
    verticalAlign: 'middle'
  }
}

Number Formats:

'0,0' - 1,000
'0,0.00' - 1,000.00
'0.0000' - 1000.0000
Custom patterns supported

Use Cases:

Currency amounts
Quantities
Percentages
Measurements
Scores or ratings

Selection Fields

RADIO

Radio button group for single selection from multiple options. Characteristics:

Only one option can be selected
Visual radio button interface
Horizontal or vertical layout
Pre-defined option list

Configuration:

{
  type: FieldType.RADIO,
  fieldMeta: {
    type: 'radio',
    fontSize: 12,
    label: 'Select One',
    values: [
      { id: 1, checked: false, value: 'Option A' },
      { id: 2, checked: true, value: 'Option B' },  // Default selected
      { id: 3, checked: false, value: 'Option C' }
    ],
    direction: 'vertical',      // vertical | horizontal
    required: true,
    readOnly: false
  }
}

Layout Options:

Vertical: Options stacked (default)
Horizontal: Options side-by-side

Use Cases:

Yes/No choices
Agreement acceptance
Service tier selection
Payment method
Delivery options

CHECKBOX

Checkbox group for multiple selections with validation. Characteristics:

Multiple options can be selected
Visual checkbox interface
Validation rules for min/max selections
Horizontal or vertical layout

Configuration:

{
  type: FieldType.CHECKBOX,
  fieldMeta: {
    type: 'checkbox',
    fontSize: 12,
    label: 'Select All That Apply',
    values: [
      { id: 1, checked: false, value: 'Option A' },
      { id: 2, checked: true, value: 'Option B' },   // Pre-checked
      { id: 3, checked: false, value: 'Option C' }
    ],
    direction: 'vertical',           // vertical | horizontal
    validationRule: 'at_least',      // Validation type
    validationLength: 1,             // Required selections
    required: true,
    readOnly: false
  }
}

Validation Rules:

'at_least' - Minimum number of selections
'at_most' - Maximum number of selections
'exactly' - Exact number of selections

Validation Signs:

const checkboxValidationSigns = {
  at_least: '≥',  // Greater than or equal
  at_most: '≤',   // Less than or equal
  exactly: '='    // Exactly equal
};

Use Cases:

Terms acceptance (multiple terms)
Feature selections
Consent checkboxes
Multi-item acknowledgments
Preference selections

Dropdown menu for selecting from a list of options. Characteristics:

Space-efficient for many options
Single selection only
Searchable in UI
Default value support

Configuration:

{
  type: FieldType.DROPDOWN,
  fieldMeta: {
    type: 'dropdown',
    fontSize: 12,
    label: 'Select an Option',
    values: [
      { value: 'Option 1' },
      { value: 'Option 2' },
      { value: 'Option 3' },
      { value: 'Option 4' }
    ],
    defaultValue: 'Option 1',        // Pre-selected value
    required: true,
    readOnly: false
  }
}

Use Cases:

Country selection
State/province selection
Department selection
Category selection
Long option lists (10+ options)

Field Metadata

All fields share common metadata properties:

Base Field Meta

type BaseFieldMeta = {
  label?: string;          // Field label displayed to user
  placeholder?: string;    // Placeholder text in empty field
  required?: boolean;      // Whether field must be completed
  readOnly?: boolean;      // Whether field is read-only
  fontSize?: number;       // Font size (8-96, default: 12)
};

Position and Size

All fields require positioning information:

type FieldPosition = {
  page: number;            // Page number (1-based)
  positionX: number;       // X coordinate (percentage: 0-100)
  positionY: number;       // Y coordinate (percentage: 0-100)
  width: number;           // Width (percentage: 0-100)
  height: number;          // Height (percentage: 0-100)
};

Field Assignment

Fields must be assigned to specific recipients:

type Field = {
  id: number;
  envelopeId: string;
  envelopeItemId: string;
  recipientId: number;      // Which recipient completes this field
  type: FieldType;
  page: number;
  positionX: Decimal;
  positionY: Decimal;
  width: Decimal;
  height: Decimal;
  customText: string;
  inserted: boolean;        // Whether field value is inserted in PDF
  fieldMeta: FieldMeta;
};

Field Validation

Required Fields

All recipient roles except VIEWER and CC must have fields assigned:

// Check for missing fields
const recipientsWithMissingFields = recipients.filter(r => {
  if (r.role === 'VIEWER' || r.role === 'CC') {
    return false;
  }
  const hasFields = fields.some(f => f.recipientId === r.id);
  return !hasFields;
});

Field Validation Rules

TEXT Fields:

Character limit validation
Required validation
Custom regex validation (future)

NUMBER Fields:

Min value validation
Max value validation
Number format validation
Required validation

CHECKBOX Fields:

// Validate checkbox selection count
validateCheckboxLength({
  validationRule: 'at_least',
  validationLength: 2,
  selectedCount: 1  // Fails validation
});

EMAIL Fields:

Email format validation (RFC 5322)
Max length: 254 characters
Required validation

Field Insertion

When a recipient completes a field, the value is inserted into the PDF:

// Mark field as inserted
await prisma.field.update({
  where: { id: fieldId },
  data: { inserted: true }
});

Insertion Process:

Recipient completes field
Value is validated
Field data is rendered into PDF at specified coordinates
inserted flag is set to true
Field becomes read-only

Best Practices

Field Placement

Position carefully
- Use percentage-based coordinates for responsive placement
- Ensure adequate space for content
- Avoid overlapping fields
Size appropriately
- Signature fields: Minimum 200x60 pixels
- Text fields: Fit expected content length
- Checkboxes/radios: 15x15 pixels per option
Group related fields
- Place related fields near each other
- Use consistent vertical alignment
- Maintain visual hierarchy

Field Configuration

Make fields user-friendly:

{
  label: 'Clear, descriptive label',
  placeholder: 'Example: John Smith',
  required: true,  // Only when truly required
  fontSize: 12     // Readable size
}

Use appropriate field types:

Don’t use TEXT for dates (use DATE)
Don’t use TEXT for numbers (use NUMBER)
Use DROPDOWN for 10+ options (not RADIO)
Use CHECKBOX for multi-select (not multiple RADIO groups)

Validation Strategy

// Good: Clear validation with helpful messages
{
  type: FieldType.TEXT,
  fieldMeta: {
    required: true,
    characterLimit: 100,
    label: 'Company Name',
    placeholder: 'Enter your company name (max 100 characters)'
  }
}

// Good: Reasonable number ranges
{
  type: FieldType.NUMBER,
  fieldMeta: {
    required: true,
    minValue: 0,
    maxValue: 999999.99,
    numberFormat: '0,0.00',
    label: 'Amount (USD)'
  }
}

API Examples

Add Fields to Document

POST /api/v1/documents/:id/fields
{
  "fields": [
    {
      "type": "SIGNATURE",
      "recipientId": 1,
      "page": 1,
      "positionX": 10,
      "positionY": 80,
      "width": 30,
      "height": 8,
      "fieldMeta": {
        "type": "signature",
        "required": true
      }
    },
    {
      "type": "DATE",
      "recipientId": 1,
      "page": 1,
      "positionX": 50,
      "positionY": 80,
      "width": 20,
      "height": 5,
      "fieldMeta": {
        "type": "date",
        "required": true,
        "label": "Date Signed"
      }
    },
    {
      "type": "TEXT",
      "recipientId": 1,
      "page": 2,
      "positionX": 10,
      "positionY": 50,
      "width": 80,
      "height": 10,
      "fieldMeta": {
        "type": "text",
        "required": true,
        "label": "Comments",
        "placeholder": "Enter your comments here",
        "characterLimit": 500
      }
    }
  ]
}

Update Field Configuration

PUT /api/v1/documents/:id/fields/:fieldId
{
  "fieldMeta": {
    "type": "text",
    "required": true,
    "characterLimit": 1000,
    "fontSize": 14,
    "label": "Updated Label"
  }
}

Fields cannot be added, removed, or modified once a document is in PENDING, COMPLETED, or REJECTED status. All field configuration must be done in DRAFT state.

Field Type Summary

Field Type	Input Method	Validation	Required	Use Case
SIGNATURE	Draw/Type/Upload	Format	Yes	Legal signatures
INITIALS	Draw/Type/Upload	Format	Yes	Clause acknowledgment
NAME	Text	Length	Yes	Identity verification
EMAIL	Text	Email format	Yes	Contact info
DATE	Date picker	Date format	Yes	Dates and timestamps
TEXT	Text input	Length, custom	Optional	General text
NUMBER	Number input	Min/max, format	Optional	Numeric values
RADIO	Radio buttons	Selection	Yes	Single choice
CHECKBOX	Checkboxes	Count rules	Optional	Multiple choice
DROPDOWN	Dropdown menu	Selection	Yes	Long option lists

Get Started

Core Concepts

User Guide

Compliance & Security

Overview

Available Field Types

Signature Fields

SIGNATURE

FREE_SIGNATURE

INITIALS

Identity Fields

NAME

EMAIL

DATE

Text Input Fields

TEXT

NUMBER

Selection Fields

RADIO

CHECKBOX

Field Metadata

Base Field Meta

Position and Size

Field Assignment

Field Validation

Required Fields

Field Validation Rules

Field Insertion

Best Practices

Field Placement

Field Configuration

Validation Strategy

API Examples

Add Fields to Document

Update Field Configuration

Field Type Summary

Build docs developers (and LLMs) love

Get Started

Core Concepts

User Guide

Compliance & Security

​Overview

​Available Field Types

​Signature Fields

​SIGNATURE

​FREE_SIGNATURE

​INITIALS

​Identity Fields

​NAME

​EMAIL

​DATE

​Text Input Fields

​TEXT

​NUMBER

​Selection Fields

​RADIO

​CHECKBOX

​DROPDOWN

​Field Metadata

​Base Field Meta

​Position and Size

​Field Assignment

​Field Validation

​Required Fields

​Field Validation Rules

​Field Insertion

​Best Practices

​Field Placement

​Field Configuration

​Validation Strategy

​API Examples

​Add Fields to Document

​Update Field Configuration

​Field Type Summary

Build docs developers (and LLMs) love

Overview

Available Field Types

Signature Fields

SIGNATURE

FREE_SIGNATURE

INITIALS

Identity Fields

NAME

EMAIL

DATE

Text Input Fields

TEXT

NUMBER

Selection Fields

RADIO

CHECKBOX

DROPDOWN

Field Metadata

Base Field Meta

Position and Size

Field Assignment

Field Validation

Required Fields

Field Validation Rules

Field Insertion

Best Practices

Field Placement

Field Configuration

Validation Strategy

API Examples

Add Fields to Document

Update Field Configuration

Field Type Summary