Fields API (v1) - Documenso

API v1 is deprecated. For new integrations, please use API v2.

Overview

Fields are interactive elements placed on document pages that recipients need to fill out or sign. Each field is assigned to a specific recipient and positioned using percentage-based coordinates.

Field Object

{
  "id": 1,
  "documentId": 123,
  "recipientId": 456,
  "type": "SIGNATURE",
  "pageNumber": 1,
  "pageX": 10,
  "pageY": 80,
  "pageWidth": 30,
  "pageHeight": 5,
  "customText": "",
  "fieldMeta": {
    "type": "signature",
    "required": true
  },
  "inserted": false
}

Properties

Field	Type	Description
`id`	number	Unique field identifier
`documentId`	number	ID of the parent document
`recipientId`	number	ID of the recipient assigned to this field
`type`	string	Field type (see Field Types)
`pageNumber`	number	Page number (1-indexed)
`pageX`	number	X position as percentage (0-100)
`pageY`	number	Y position as percentage (0-100)
`pageWidth`	number	Width as percentage of page (0-100)
`pageHeight`	number	Height as percentage of page (0-100)
`customText`	string	Value entered by recipient
`fieldMeta`	object \| null	Type-specific configuration
`inserted`	boolean	Whether field has been completed

Field Types

Signature Fields

Type	Description	Auto-filled
`SIGNATURE`	Full signature (drawn, typed, or uploaded)	No
`FREE_SIGNATURE`	Unrestricted signature field	No
`INITIALS`	Recipient’s initials	No

Auto-filled Fields

Type	Description	Value
`NAME`	Recipient’s full name	From recipient object
`EMAIL`	Recipient’s email	From recipient object
`DATE`	Current date when field is completed	Auto-generated

Form Fields

Type	Description	Validation
`TEXT`	Free-form text input	Optional
`NUMBER`	Numeric input	Optional min/max
`CHECKBOX`	Multiple selections	Required items
`RADIO`	Single selection from options	Required
`DROPDOWN`	Dropdown selection	Required

Add Field

Add one or more fields to a document in DRAFT status.

POST /api/v1/documents/:id/fields

Path Parameters

Parameter	Type	Description
`id`	number	The document ID

Request Body

You can add a single field or multiple fields in one request: Single Field:

Field	Type	Required	Description
`recipientId`	number	Yes	ID of recipient for this field
`type`	string	Yes	Field type
`pageNumber`	number	Yes	Page number (1-indexed)
`pageX`	number	Yes	X position (0-100)
`pageY`	number	Yes	Y position (0-100)
`pageWidth`	number	Yes	Width (0-100)
`pageHeight`	number	Yes	Height (0-100)
`fieldMeta`	object	No	Type-specific options

Multiple Fields: Pass an array of field objects with the same schema.

Positioning Guide

Field positions use percentages relative to the PDF page:

pageX: Horizontal position from left edge (0 = left, 100 = right)
pageY: Vertical position from top edge (0 = top, 100 = bottom)
pageWidth: Field width as percentage of page width
pageHeight: Field height as percentage of page height

(0,0)                    (100,0)
  ┌─────────────────────────┐
  │                         │
  │    (10,20)              │
  │    ┌────────┐           │
  │    │ Field  │           │
  │    └────────┘           │
  │                         │
  └─────────────────────────┘
(0,100)                  (100,100)

Code Examples

Tab Title
Tab Title

# Add a single signature field
curl -X POST "https://app.documenso.com/api/v1/documents/123/fields" \
  -H "Authorization: Bearer api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SIGNATURE",
    "recipientId": 1,
    "pageNumber": 1,
    "pageX": 10,
    "pageY": 80,
    "pageWidth": 30,
    "pageHeight": 5,
    "fieldMeta": {}
  }'

# Add multiple fields at once
curl -X POST "https://app.documenso.com/api/v1/documents/123/fields" \
  -H "Authorization: Bearer api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "type": "SIGNATURE",
      "recipientId": 1,
      "pageNumber": 1,
      "pageX": 10,
      "pageY": 80,
      "pageWidth": 30,
      "pageHeight": 5,
      "fieldMeta": {}
    },
    {
      "type": "DATE",
      "recipientId": 1,
      "pageNumber": 1,
      "pageX": 50,
      "pageY": 80,
      "pageWidth": 20,
      "pageHeight": 3,
      "fieldMeta": {}
    },
    {
      "type": "TEXT",
      "recipientId": 1,
      "pageNumber": 1,
      "pageX": 10,
      "pageY": 70,
      "pageWidth": 40,
      "pageHeight": 4,
      "fieldMeta": {
        "type": "text",
        "label": "Job Title",
        "required": true
      }
    }
  ]'

import { initClient } from '@ts-rest/core';
import { ApiContractV1 } from '@documenso/api/v1/contract';

const client = initClient(ApiContractV1, {
  baseUrl: 'https://app.documenso.com/api/v1',
  baseHeaders: {
    authorization: 'Bearer api_xxxxxxxxxxxxxxxx',
  },
});

// Add a single signature field
const { status, body } = await client.createField({
  params: { id: '123' },
  body: {
    type: 'SIGNATURE',
    recipientId: 1,
    pageNumber: 1,
    pageX: 10,
    pageY: 80,
    pageWidth: 30,
    pageHeight: 5,
    fieldMeta: {},
  },
});

if (status === 200) {
  if (Array.isArray(body.fields)) {
    console.log(`Added ${body.fields.length} fields`);
  } else {
    console.log(`Added field ${body.fields.id}`);
  }
}

// Add multiple fields at once
const multipleFieldsResponse = await client.createField({
  params: { id: '123' },
  body: [
    {
      type: 'SIGNATURE',
      recipientId: 1,
      pageNumber: 1,
      pageX: 10,
      pageY: 80,
      pageWidth: 30,
      pageHeight: 5,
      fieldMeta: {},
    },
    {
      type: 'DATE',
      recipientId: 1,
      pageNumber: 1,
      pageX: 50,
      pageY: 80,
      pageWidth: 20,
      pageHeight: 3,
      fieldMeta: {},
    },
  ],
});

Response

{
  "fields": {
    "id": 1,
    "documentId": 123,
    "recipientId": 1,
    "type": "SIGNATURE",
    "pageNumber": 1,
    "pageX": 10,
    "pageY": 80,
    "pageWidth": 30,
    "pageHeight": 5,
    "customText": "",
    "fieldMeta": {},
    "inserted": false
  },
  "documentId": 123
}

For multiple fields, the response includes an array in the fields property.

You can only add fields to documents in DRAFT status. Once sent, fields cannot be added or modified.

Update Field

Update a field’s position or configuration before the document is sent.

PATCH /api/v1/documents/:id/fields/:fieldId

Path Parameters

Parameter	Type	Description
`id`	number	The document ID
`fieldId`	number	The field ID

Request Body

All fields are optional. Only include what you want to update:

Field	Type	Description
`recipientId`	number	Reassign to different recipient
`type`	string	Change field type
`pageNumber`	number	Move to different page
`pageX`	number	Update X position
`pageY`	number	Update Y position
`pageWidth`	number	Update width
`pageHeight`	number	Update height
`fieldMeta`	object	Update configuration

Code Examples

Tab Title
Tab Title

# Move field position
curl -X PATCH "https://app.documenso.com/api/v1/documents/123/fields/1" \
  -H "Authorization: Bearer api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "pageX": 20,
    "pageY": 75
  }'

# Resize field
curl -X PATCH "https://app.documenso.com/api/v1/documents/123/fields/1" \
  -H "Authorization: Bearer api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "pageWidth": 40,
    "pageHeight": 6
  }'

# Reassign to different recipient
curl -X PATCH "https://app.documenso.com/api/v1/documents/123/fields/1" \
  -H "Authorization: Bearer api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientId": 2
  }'

// Move field to new position
const { status, body } = await client.updateField({
  params: { id: '123', fieldId: '1' },
  body: {
    pageX: 20,
    pageY: 75,
  },
});

// Update field metadata
const metaUpdate = await client.updateField({
  params: { id: '123', fieldId: '1' },
  body: {
    fieldMeta: {
      type: 'text',
      label: 'Updated Label',
      required: true,
      placeholder: 'Enter text here',
    },
  },
});

Response

Returns the updated field object.

Remove Field

Delete a field from a document in DRAFT status.

DELETE /api/v1/documents/:id/fields/:fieldId

Path Parameters

Parameter	Type	Description
`id`	number	The document ID
`fieldId`	number	The field ID

Code Examples

Tab Title
Tab Title

curl -X DELETE "https://app.documenso.com/api/v1/documents/123/fields/1" \
  -H "Authorization: Bearer api_xxxxxxxxxxxxxxxx"

const { status, body } = await client.deleteField({
  params: { id: '123', fieldId: '1' },
  body: null,
});

if (status === 200) {
  console.log(`Deleted field ${body.id}`);
}

Response

Returns the deleted field object.

Field Metadata

Different field types support different metadata configurations.

Text Field Metadata

{
  "type": "text",
  "label": "Job Title",
  "placeholder": "Enter your job title",
  "required": true,
  "characterLimit": 100
}

Number Field Metadata

{
  "type": "number",
  "label": "Salary",
  "required": true,
  "numberFormat": "CURRENCY",
  "minValue": 0,
  "maxValue": 1000000
}

Checkbox Field Metadata

{
  "type": "checkbox",
  "label": "Skills",
  "required": true,
  "values": [
    { "value": "JavaScript", "checked": false },
    { "value": "TypeScript", "checked": false },
    { "value": "Python", "checked": false }
  ],
  "validationRule": "AT_LEAST_ONE",
  "validationLength": 1
}

Radio Field Metadata

{
  "type": "radio",
  "label": "Employment Type",
  "required": true,
  "values": [
    { "value": "Full-time", "checked": false },
    { "value": "Part-time", "checked": false },
    { "value": "Contract", "checked": false }
  ]
}

{
  "type": "dropdown",
  "label": "Department",
  "required": true,
  "values": [
    { "value": "Engineering" },
    { "value": "Sales" },
    { "value": "Marketing" },
    { "value": "Operations" }
  ],
  "defaultValue": "Engineering"
}

Signature Field Metadata

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

Common Field Patterns

Standard Signature Block

const standardSignature = [
  {
    type: 'SIGNATURE',
    recipientId: 1,
    pageNumber: 1,
    pageX: 10,
    pageY: 85,
    pageWidth: 30,
    pageHeight: 5,
    fieldMeta: {},
  },
  {
    type: 'NAME',
    recipientId: 1,
    pageNumber: 1,
    pageX: 10,
    pageY: 90,
    pageWidth: 30,
    pageHeight: 3,
    fieldMeta: {},
  },
  {
    type: 'DATE',
    recipientId: 1,
    pageNumber: 1,
    pageX: 50,
    pageY: 85,
    pageWidth: 20,
    pageHeight: 3,
    fieldMeta: {},
  },
];

await client.createField({
  params: { id: documentId.toString() },
  body: standardSignature,
});

Form with Validation

const employeeForm = [
  {
    type: 'TEXT',
    recipientId: 1,
    pageNumber: 1,
    pageX: 10,
    pageY: 20,
    pageWidth: 40,
    pageHeight: 4,
    fieldMeta: {
      type: 'text',
      label: 'Full Name',
      required: true,
      characterLimit: 100,
    },
  },
  {
    type: 'NUMBER',
    recipientId: 1,
    pageNumber: 1,
    pageX: 10,
    pageY: 30,
    pageWidth: 20,
    pageHeight: 4,
    fieldMeta: {
      type: 'number',
      label: 'Employee ID',
      required: true,
      minValue: 1000,
      maxValue: 99999,
    },
  },
  {
    type: 'DROPDOWN',
    recipientId: 1,
    pageNumber: 1,
    pageX: 10,
    pageY: 40,
    pageWidth: 30,
    pageHeight: 4,
    fieldMeta: {
      type: 'dropdown',
      label: 'Department',
      required: true,
      values: [
        { value: 'Engineering' },
        { value: 'Sales' },
        { value: 'Marketing' },
      ],
    },
  },
];

Complete Example

import { initClient } from '@ts-rest/core';
import { ApiContractV1 } from '@documenso/api/v1/contract';
import fs from 'fs';

const client = initClient(ApiContractV1, {
  baseUrl: 'https://app.documenso.com/api/v1',
  baseHeaders: {
    authorization: 'Bearer api_xxxxxxxxxxxxxxxx',
  },
});

async function createDocumentWithFields() {
  // 1. Create document
  const { body: createBody } = await client.createDocument({
    body: {
      title: 'Employment Agreement',
      recipients: [
        {
          name: 'John Doe',
          email: 'john@example.com',
          role: 'SIGNER',
        },
      ],
    },
  });

  const { uploadUrl, documentId, recipients } = createBody;
  const recipientId = recipients[0].recipientId;

  // 2. Upload PDF
  const pdfBuffer = fs.readFileSync('./employment-agreement.pdf');
  await fetch(uploadUrl, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/octet-stream' },
    body: pdfBuffer,
  });

  // 3. Add multiple fields
  await client.createField({
    params: { id: documentId.toString() },
    body: [
      // Signature block
      {
        type: 'SIGNATURE',
        recipientId,
        pageNumber: 5,
        pageX: 10,
        pageY: 85,
        pageWidth: 30,
        pageHeight: 5,
        fieldMeta: {},
      },
      {
        type: 'NAME',
        recipientId,
        pageNumber: 5,
        pageX: 10,
        pageY: 90,
        pageWidth: 30,
        pageHeight: 3,
        fieldMeta: {},
      },
      {
        type: 'DATE',
        recipientId,
        pageNumber: 5,
        pageX: 50,
        pageY: 85,
        pageWidth: 20,
        pageHeight: 3,
        fieldMeta: {},
      },
      // Form fields
      {
        type: 'TEXT',
        recipientId,
        pageNumber: 1,
        pageX: 10,
        pageY: 30,
        pageWidth: 40,
        pageHeight: 4,
        fieldMeta: {
          type: 'text',
          label: 'Job Title',
          required: true,
        },
      },
      {
        type: 'DROPDOWN',
        recipientId,
        pageNumber: 1,
        pageX: 10,
        pageY: 40,
        pageWidth: 30,
        pageHeight: 4,
        fieldMeta: {
          type: 'dropdown',
          label: 'Department',
          required: true,
          values: [
            { value: 'Engineering' },
            { value: 'Sales' },
            { value: 'Marketing' },
          ],
        },
      },
    ],
  });

  // 4. Send document
  await client.sendDocument({
    params: { id: documentId.toString() },
    body: { sendEmail: true },
  });

  console.log('Document created and sent with all fields!');
}

createDocumentWithFields().catch(console.error);

Best Practices

Add all fields for a recipient in a single batch request:

// Good: Single request
await client.createField({
  params: { id: '123' },
  body: [field1, field2, field3],
});

// Avoid: Multiple requests
await client.createField({ params: { id: '123' }, body: field1 });
await client.createField({ params: { id: '123' }, body: field2 });
await client.createField({ params: { id: '123' }, body: field3 });

2. Use Consistent Positioning

Maintain consistent alignment and spacing:

const leftMargin = 10;
const rightMargin = 10;
const lineHeight = 5;

const fields = [
  {
    type: 'SIGNATURE',
    pageX: leftMargin,
    pageY: 80,
    pageWidth: 30,
    pageHeight: lineHeight,
  },
  {
    type: 'DATE',
    pageX: 100 - rightMargin - 20,
    pageY: 80,
    pageWidth: 20,
    pageHeight: lineHeight,
  },
];

3. Validate Field Metadata

Ensure metadata matches the field type:

function getFieldMeta(type: string) {
  switch (type) {
    case 'TEXT':
      return { type: 'text', required: true };
    case 'NUMBER':
      return { type: 'number', required: true };
    case 'CHECKBOX':
      return { type: 'checkbox', values: [], required: true };
    default:
      return {};
  }
}

4. Test Field Positions

Before sending to recipients, test field positioning:

Create a test document
Add fields
Use the signing URL to preview
Adjust positions as needed
Delete the test document

​Overview

​Field Object

​Properties

​Field Types

​Signature Fields

​Auto-filled Fields

​Form Fields

​Add Field

​Path Parameters

​Request Body

​Positioning Guide

​Code Examples

​Response

​Update Field

​Path Parameters

​Request Body

​Code Examples

​Response

​Remove Field

​Path Parameters

​Code Examples

​Response

​Field Metadata

​Text Field Metadata

​Number Field Metadata

​Checkbox Field Metadata

​Radio Field Metadata

​Dropdown Field Metadata

​Signature Field Metadata

​Common Field Patterns

​Standard Signature Block

​Form with Validation

​Complete Example

​Best Practices

​1. Group Related Fields

​2. Use Consistent Positioning

​3. Validate Field Metadata

​4. Test Field Positions

​See Also

Overview

Field Object

Properties

Field Types

Signature Fields

Auto-filled Fields

Form Fields

Add Field

Path Parameters

Request Body

Positioning Guide

Code Examples

Response

Update Field

Path Parameters

Request Body

Code Examples

Response

Remove Field

Path Parameters

Code Examples

Response

Field Metadata

Text Field Metadata

Number Field Metadata

Checkbox Field Metadata

Radio Field Metadata

Dropdown Field Metadata

Signature Field Metadata

Common Field Patterns

Standard Signature Block

Form with Validation

Complete Example

Best Practices

1. Group Related Fields

2. Use Consistent Positioning

3. Validate Field Metadata

4. Test Field Positions

See Also