Fields API

Documents and templates are being deprecated and replaced by envelopes. Read the migration guide here.

This guide may not reflect the latest endpoints or parameters. For an always up-to-date reference, see the OpenAPI Reference.

Field Object

Property	Type	Description
`id`	number	Unique field identifier
`secondaryId`	string	Secondary identifier for audit logs
`type`	string	Field type (see Field Types)
`recipientId`	number	ID of the recipient assigned to this field
`envelopeId`	string	ID of the parent envelope
`envelopeItemId`	string	ID of the PDF item the field is placed on
`page`	number	Page number (1-indexed)
`positionX`	string	X coordinate as percentage (0-100), a decimal serialized as a string
`positionY`	string	Y coordinate as percentage (0-100), a decimal serialized as a string
`width`	string	Width as percentage of page (0-100), a decimal serialized as a string
`height`	string	Height as percentage of page (0-100), a decimal serialized as a string
`customText`	string	Value entered by the recipient
`inserted`	boolean	Whether the field has been completed
`fieldMeta`	object \| null	Type-specific configuration options

Example Field Object

{
  "id": 456,
  "secondaryId": "field_abc123",
  "type": "SIGNATURE",
  "recipientId": 123,
  "envelopeId": "envelope_abcdefhiklmnorst",
  "envelopeItemId": "envelope_item_abcdefhiklmnorst",
  "page": 1,
  "positionX": "10",
  "positionY": "80",
  "width": "30",
  "height": "5",
  "customText": "",
  "inserted": false,
  "fieldMeta": {
    "type": "signature",
    "required": true,
    "overflow": "auto"
  }
}

Field Types

Type	Description	Auto-filled
`SIGNATURE`	Drawn, typed, or uploaded signature	No
`FREE_SIGNATURE`	Legacy free-form signature. Accepted by the v2 create schema but rejected by the v1 API and unsupported in the signing UI — avoid in new integrations	No
`INITIALS`	Recipient's initials	No
`NAME`	Recipient's full name	Yes
`EMAIL`	Recipient's email address	Yes
`DATE`	Date the field was completed	Yes
`TEXT`	Free-form text input	No
`NUMBER`	Numeric input with optional validation	No
`RADIO`	Single selection from options	No
`CHECKBOX`	Multiple selections from options	No
`DROPDOWN`	Single selection from a dropdown menu	No

Parameter	Type	Description
`fieldId`	number	The field ID

Create Fields

Add one or more fields to a document.


POST /envelope/field/create-many

Request Body

Field	Type	Required	Description
`envelopeId`	string	Yes	The envelope ID
`data`	array	Yes	Array of field configurations

Each entry in data requires a type, a recipientId, and a position — either explicit coordinates (page, positionX, positionY, width, height) or a text placeholder (placeholder with optional width, height, and matchAll). Optional per-entry properties: envelopeItemId (which PDF in the envelope to place the field on; defaults to the first item) and fieldMeta.

Code Examples

curl -X POST "https://app.documenso.com/api/v2/envelope/field/create-many" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "envelopeId": "envelope_abcdefhiklmnorst",
    "data": [
      {
        "type": "SIGNATURE",
        "recipientId": 456,
        "page": 1,
        "positionX": 10,
        "positionY": 80,
        "width": 30,
        "height": 5
      },
      {
        "type": "DATE",
        "recipientId": 456,
        "page": 1,
        "positionX": 50,
        "positionY": 80,
        "width": 20,
        "height": 3
      },
      {
        "type": "TEXT",
        "recipientId": 456,
        "page": 1,
        "positionX": 10,
        "positionY": 70,
        "width": 40,
        "height": 4,
        "fieldMeta": {
          "type": "text",
          "label": "Job Title",
          "placeholder": "Enter your job title",
          "required": true
        }
      }
    ]
  }'

Response

{
  "data": [
    {
      "id": 101,
      "secondaryId": "field_abc123",
      "envelopeId": "envelope_abcdefhiklmnorst",
      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
      "type": "SIGNATURE",
      "recipientId": 456,
      "page": 1,
      "positionX": "10",
      "positionY": "80",
      "width": "30",
      "height": "5",
      "customText": "",
      "inserted": false,
      "fieldMeta": {
        "type": "signature",
        "fontSize": 18,
        "overflow": "auto"
      }
    },
    {
      "id": 102,
      "secondaryId": "field_def456",
      "envelopeId": "envelope_abcdefhiklmnorst",
      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
      "type": "DATE",
      "recipientId": 456,
      "page": 1,
      "positionX": "50",
      "positionY": "80",
      "width": "20",
      "height": "3",
      "customText": "",
      "inserted": false,
      "fieldMeta": {
        "type": "date",
        "fontSize": 12,
        "textAlign": "left",
        "overflow": "auto"
      }
    },
    {
      "id": 103,
      "secondaryId": "field_ghi789",
      "envelopeId": "envelope_abcdefhiklmnorst",
      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
      "type": "TEXT",
      "recipientId": 456,
      "page": 1,
      "positionX": "10",
      "positionY": "70",
      "width": "40",
      "height": "4",
      "customText": "",
      "inserted": false,
      "fieldMeta": {
        "type": "text",
        "label": "Job Title",
        "placeholder": "Enter your job title",
        "required": true
      }
    }
  ]
}

Update Fields

Update one or more fields in a single request.

POST /envelope/field/update-many

Request Body

Field	Type	Required	Description
`envelopeId`	string	Yes	The envelope ID
`data`	array	Yes	Array of field update objects

Each entry in data requires the field id and type. Position properties (page, positionX, positionY, width, height), envelopeItemId, and fieldMeta are optional — only supplied values are updated. Placeholder positioning is not supported when updating; use coordinates.

Code Examples

curl -X POST "https://app.documenso.com/api/v2/envelope/field/update-many" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "envelopeId": "envelope_abcdefhiklmnorst",
    "data": [
      {
        "id": 101,
        "type": "SIGNATURE",
        "positionY": 85
      },
      {
        "id": 102,
        "type": "DATE",
        "positionY": 85
      }
    ]
  }'

Response

{
  "data": [
    {
      "id": 101,
      "secondaryId": "field_abc123",
      "envelopeId": "envelope_abcdefhiklmnorst",
      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
      "type": "SIGNATURE",
      "recipientId": 456,
      "page": 1,
      "positionX": "10",
      "positionY": "85",
      "width": "30",
      "height": "5",
      "customText": "",
      "inserted": false,
      "fieldMeta": {
        "type": "signature",
        "fontSize": 18,
        "overflow": "auto"
      }
    },
    {
      "id": 102,
      "secondaryId": "field_def456",
      "envelopeId": "envelope_abcdefhiklmnorst",
      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
      "type": "DATE",
      "recipientId": 456,
      "page": 1,
      "positionX": "50",
      "positionY": "85",
      "width": "20",
      "height": "3",
      "customText": "",
      "inserted": false,
      "fieldMeta": {
        "type": "date",
        "fontSize": 12,
        "textAlign": "left",
        "overflow": "auto"
      }
    }
  ]
}

Delete Field

Remove a field from a document.

POST /envelope/field/delete

Request Body

Field	Type	Required	Description
`fieldId`	number	Yes	The field ID

Code Examples

curl -X POST "https://app.documenso.com/api/v2/envelope/field/delete" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fieldId": 456
  }'

Response

{
  "success": true
}

Field Positioning

Fields use percentage-based coordinates relative to the PDF page dimensions.

Property	Range	Description
`positionX`	0-100	Horizontal position from left edge (0 = left edge)
`positionY`	0-100	Vertical position from top edge (0 = top edge)
`width`	0-100	Field width as percentage of page width
`height`	0-100	Field height as percentage of page height
`page`	1+	Page number (1-indexed)

Coordinate System

(0,0) ─────────────────────────── (100,0)
  │                                   │
  │    ┌─────────┐                    │
  │    │  Field  │ (positionX: 10,    │
  │    │         │  positionY: 20,    │
  │    └─────────┘  width: 30,        │
  │                 height: 5)        │
  │                                   │
(0,100) ─────────────────────────(100,100)

Example: Position a Signature at Bottom Right

const field = {
  type: 'SIGNATURE',
  recipientId: 123,
  page: 1,
  positionX: 60, // 60% from left
  positionY: 85, // 85% from top (near bottom)
  width: 30, // 30% of page width
  height: 8, // 8% of page height
};

Placeholder-Based Field Positioning

Instead of specifying exact coordinates, you can position fields using placeholder text embedded in your PDF. Include placeholder markers such as {{signature, r1}} in your document, and Documenso will create fields at those locations when the document is uploaded.

This approach is useful when generating PDFs programmatically or using templates with consistent layouts.

Placeholder support is only available in envelope.* endpoints. POST /template/use does not support placeholder parsing.

See the PDF Placeholders guide for the full placeholder format reference, including supported field types, recipient identifiers, and field options.

Placeholder Positioning via the API

POST /envelope/field/create-many accepts a placeholder position in place of coordinates. Instead of page, positionX, positionY, width, and height, pass:

Field	Type	Required	Description
`placeholder`	string	Yes	Text to search for in the PDF (e.g. `{{name}}`). The field is placed at the bounding box of the first match.
`width`	number	No	Override the field width. Defaults to the width of the matched text.
`height`	number	No	Override the field height. Defaults to the height of the matched text.
`matchAll`	boolean	No	Create a field at every occurrence of the placeholder instead of only the first.

{
  "envelopeId": "envelope_abcdefhiklmnorst",
  "data": [
    {
      "type": "SIGNATURE",
      "recipientId": 456,
      "placeholder": "{{signature}}",
      "matchAll": true
    }
  ]
}

POST /envelope/field/update-many does not accept placeholders — field updates are coordinate-only.

Field Meta Options

Each field type supports specific configuration through fieldMeta.

Common Options

All field types support these base options:

Option	Type	Description
`label`	string	Display text shown near the field
`placeholder`	string	Hint text when field is empty
`required`	boolean	Whether field must be completed
`readOnly`	boolean	Lock field with a pre-filled value
`fontSize`	number	Text size in pixels (8-96, default: 12)

Signature Field

{
  "type": "SIGNATURE",
  "fieldMeta": {
    "type": "signature",
    "required": true
  }
}

Text Field

{
  "type": "TEXT",
  "fieldMeta": {
    "type": "text",
    "label": "Company Name",
    "placeholder": "Enter company name",
    "text": "Default value",
    "characterLimit": 100,
    "textAlign": "left",
    "required": true
  }
}

Option	Type	Description
`text`	string	Default value
`characterLimit`	number	Maximum characters allowed
`textAlign`	string	`left`, `center`, or `right`
`lineHeight`	number	Spacing between lines (1-10)
`letterSpacing`	number	Spacing between characters (0-100)

Number Field

{
  "type": "NUMBER",
  "fieldMeta": {
    "type": "number",
    "label": "Quantity",
    "minValue": 1,
    "maxValue": 100,
    "value": "10",
    "required": true
  }
}

Option	Type	Description
`value`	string	Default value
`minValue`	number	Minimum allowed value
`maxValue`	number	Maximum allowed value
`numberFormat`	string	Display format

Date Field

{
  "type": "DATE",
  "fieldMeta": {
    "type": "date",
    "textAlign": "left",
    "required": true
  }
}

Checkbox Field

{
  "type": "CHECKBOX",
  "fieldMeta": {
    "type": "checkbox",
    "label": "Agreements",
    "values": [
      { "id": 1, "value": "Terms of Service", "checked": false },
      { "id": 2, "value": "Privacy Policy", "checked": false }
    ],
    "validationRule": "min",
    "validationLength": 1,
    "direction": "vertical",
    "required": true
  }
}

Option	Type	Description
`values`	array	List of checkbox options
`validationRule`	string	Validation type for selections
`validationLength`	number	Number for validation rule
`direction`	string	`vertical` or `horizontal` layout

Radio Field

{
  "type": "RADIO",
  "fieldMeta": {
    "type": "radio",
    "label": "Payment Method",
    "values": [
      { "id": 1, "value": "Credit Card", "checked": false },
      { "id": 2, "value": "Bank Transfer", "checked": true },
      { "id": 3, "value": "Check", "checked": false }
    ],
    "direction": "vertical",
    "required": true
  }
}

{
  "type": "DROPDOWN",
  "fieldMeta": {
    "type": "dropdown",
    "label": "Country",
    "values": [{ "value": "United States" }, { "value": "Canada" }, { "value": "United Kingdom" }],
    "defaultValue": "United States",
    "required": true
  }
}

Option	Type	Description
`values`	array	List of dropdown options
`defaultValue`	string	Pre-selected option

Complete Example

Create a document with a signature block containing multiple field types:

async function addSignatureBlock(envelopeId: string, recipientId: number) {
  const data = [
    // Signature
    {
      type: 'SIGNATURE',
      recipientId,
      page: 1,
      positionX: 10,
      positionY: 80,
      width: 30,
      height: 8,
      fieldMeta: {
        type: 'signature',
        required: true,
      },
    },
    // Printed name
    {
      type: 'NAME',
      recipientId,
      page: 1,
      positionX: 10,
      positionY: 90,
      width: 30,
      height: 4,
      fieldMeta: {
        type: 'name',
        label: 'Printed Name',
      },
    },
    // Date
    {
      type: 'DATE',
      recipientId,
      page: 1,
      positionX: 50,
      positionY: 80,
      width: 20,
      height: 4,
      fieldMeta: {
        type: 'date',
        label: 'Date',
      },
    },
    // Job title
    {
      type: 'TEXT',
      recipientId,
      page: 1,
      positionX: 50,
      positionY: 90,
      width: 30,
      height: 4,
      fieldMeta: {
        type: 'text',
        label: 'Title',
        placeholder: 'Enter your job title',
      },
    },
  ];

  const response = await fetch('https://app.documenso.com/api/v2/envelope/field/create-many', {
    method: 'POST',
    headers: {
      Authorization: 'api_xxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ envelopeId, data }),
  });

  return response.json();
}

Error Responses

Status	Description
`400`	Invalid field configuration or document already sent
`401`	Invalid or missing API key
`404`	Document, recipient, or field not found
`500`	Server error

Fields cannot be modified after a document is sent for signing. Make all field changes while the document is in DRAFT status.

Field Object

Example Field Object

Field Types

Get Field

Path Parameters

Code Examples

Response

Create Fields

Request Body

Code Examples

Response

Update Fields

Request Body

Code Examples

Response

Delete Field

Request Body

Code Examples

Response

Field Positioning

Coordinate System

Example: Position a Signature at Bottom Right

Placeholder-Based Field Positioning

Placeholder Positioning via the API

Field Meta Options

Common Options

Signature Field

Text Field

Number Field

Date Field

Checkbox Field

Radio Field

Complete Example

Error Responses

See Also

On this page