Fields API

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`	number	ID of the parent envelope
`envelopeItemId`	string	ID of the PDF item the field is placed on
`page`	number	Page number (1-indexed)
`positionX`	number	X coordinate as percentage (0-100)
`positionY`	number	Y coordinate as percentage (0-100)
`width`	number	Width as percentage of page (0-100)
`height`	number	Height as percentage of page (0-100)
`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": 789,
  "envelopeItemId": "envelope_item_xyz",
  "page": 1,
  "positionX": 10,
  "positionY": 80,
  "width": 30,
  "height": 5,
  "customText": "",
  "inserted": false,
  "fieldMeta": {
    "type": "signature",
    "required": true
  }
}

Field Types

Type	Description	Auto-filled
`SIGNATURE`	Drawn, typed, or uploaded signature	No
`FREE_SIGNATURE`	Unrestricted signature without validation	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
`documentId`	number	Yes	The document ID
`fields`	array	Yes	Array of field configurations

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 '{
    "documentId": 123,
    "fields": [
      {
        "type": "SIGNATURE",
        "recipientId": 456,
        "pageNumber": 1,
        "pageX": 10,
        "pageY": 80,
        "width": 30,
        "height": 5
      },
      {
        "type": "DATE",
        "recipientId": 456,
        "pageNumber": 1,
        "pageX": 50,
        "pageY": 80,
        "width": 20,
        "height": 3
      },
      {
        "type": "TEXT",
        "recipientId": 456,
        "pageNumber": 1,
        "pageX": 10,
        "pageY": 70,
        "width": 40,
        "height": 4,
        "fieldMeta": {
          "type": "text",
          "label": "Job Title",
          "placeholder": "Enter your job title",
          "required": true
        }
      }
    ]
  }'

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({
      documentId: 123,
      fields: [
        {
          type: 'SIGNATURE',
          recipientId: 456,
          pageNumber: 1,
          pageX: 10,
          pageY: 80,
          width: 30,
          height: 5,
        },
        {
          type: 'DATE',
          recipientId: 456,
          pageNumber: 1,
          pageX: 50,
          pageY: 80,
          width: 20,
          height: 3,
        },
        {
          type: 'TEXT',
          recipientId: 456,
          pageNumber: 1,
          pageX: 10,
          pageY: 70,
          width: 40,
          height: 4,
          fieldMeta: {
            type: 'text',
            label: 'Job Title',
            placeholder: 'Enter your job title',
            required: true,
          },
        },
      ],
    }),
  }
);

const { fields } = await response.json();
console.log(`Created ${fields.length} fields`);

Response

{
  "fields": [
    {
      "id": 101,
      "type": "SIGNATURE",
      "recipientId": 456,
      "page": 1,
      "positionX": 10,
      "positionY": 80,
      "width": 30,
      "height": 5
    },
    {
      "id": 102,
      "type": "DATE",
      "recipientId": 456,
      "page": 1,
      "positionX": 50,
      "positionY": 80,
      "width": 20,
      "height": 3
    },
    {
      "id": 103,
      "type": "TEXT",
      "recipientId": 456,
      "page": 1,
      "positionX": 10,
      "positionY": 70,
      "width": 40,
      "height": 4
    }
  ]
}

Update Fields

Update one or more fields in a single request.

POST /envelope/field/update-many

Request Body

Field	Type	Required	Description
`documentId`	number	Yes	The document ID
`fields`	array	Yes	Array of field update objects

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 '{
    "documentId": 123,
    "fields": [
      {
        "id": 101,
        "type": "SIGNATURE",
        "pageY": 85
      },
      {
        "id": 102,
        "type": "DATE",
        "pageY": 85
      }
    ]
  }'

const response = await fetch(
  'https://app.documenso.com/api/v2/envelope/field/update-many',
  {
    method: 'POST',
    headers: {
      Authorization: 'api_xxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      documentId: 123,
      fields: [
        { id: 101, type: 'SIGNATURE', pageY: 85 },
        { id: 102, type: 'DATE', pageY: 85 },
      ],
    }),
  }
);

const { fields } = await response.json();

Response

{
  "fields": [
    { "id": 101, "type": "SIGNATURE", "positionY": 85 },
    { "id": 102, "type": "DATE", "positionY": 85 }
  ]
}

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
  }'

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

const { success } = await response.json();

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  │ (pageX: 10,        │
  │    │         │  pageY: 20,        │
  │    └─────────┘  width: 30,        │
  │                 height: 5)        │
  │                                   │
(0,100) ─────────────────────────(100,100)

Example: Position a Signature at Bottom Right

const field = {
  type: 'SIGNATURE',
  recipientId: 123,
  pageNumber: 1,
  pageX: 60, // 60% from left
  pageY: 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.

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

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(documentId: number, recipientId: number) {
  const fields = [
    // Signature
    {
      type: 'SIGNATURE',
      recipientId,
      pageNumber: 1,
      pageX: 10,
      pageY: 80,
      width: 30,
      height: 8,
      fieldMeta: {
        type: 'signature',
        required: true,
      },
    },
    // Printed name
    {
      type: 'NAME',
      recipientId,
      pageNumber: 1,
      pageX: 10,
      pageY: 90,
      width: 30,
      height: 4,
      fieldMeta: {
        type: 'name',
        label: 'Printed Name',
      },
    },
    // Date
    {
      type: 'DATE',
      recipientId,
      pageNumber: 1,
      pageX: 50,
      pageY: 80,
      width: 20,
      height: 4,
      fieldMeta: {
        type: 'date',
        label: 'Date',
      },
    },
    // Job title
    {
      type: 'TEXT',
      recipientId,
      pageNumber: 1,
      pageX: 50,
      pageY: 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({ documentId, fields }),
  });

  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

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