Fields

Fields are form elements placed on a document page — signatures, text inputs, checkboxes, dates, and more. Fields can only be modified on documents in draft status.

Field types

Type	Description
`signature`	Electronic signature
`initials`	Signer’s initials
`stamp`	Company stamp/seal
`name`	Auto-filled signer name
`email`	Auto-filled signer email
`company`	Company name input
`title`	Job title input
`phone`	Phone number input
`id_number`	ID/passport number
`address`	Address input
`date_signed`	Auto-filled signing date
`date`	Date picker
`text`	Single-line text
`textarea`	Multi-line text
`number`	Numeric input
`checkbox`	Single checkbox
`checkbox_group`	Group of checkboxes
`radio_group`	Radio button group
`dropdown`	Dropdown select
`attachment`	File attachment field
`image`	Image upload field
`approval`	Approval button
`note`	Read-only text note
`formula`	Calculated field
`payment`	Payment field

List fields

GET /api/v1/documents/{id}/fields

Returns all fields on a document, ordered by page and vertical position.

Required scope: documents.read

curl -X GET https://app.insigner.co/api/v1/documents/cm5x9abc123/fields \
  -H "Authorization: Bearer isk_YOUR_API_KEY"

const res = await fetch(
  'https://app.insigner.co/api/v1/documents/cm5x9abc123/fields',
  { headers: { 'Authorization': 'Bearer isk_YOUR_API_KEY' } }
);
const { data } = await res.json();

res = requests.get(
    "https://app.insigner.co/api/v1/documents/cm5x9abc123/fields",
    headers={"Authorization": "Bearer isk_YOUR_API_KEY"}
)

Response

{
  "data": [
    {
      "id": "fld_abc123",
      "type": "signature",
      "label": "Client Signature",
      "page": 1,
      "x": 100,
      "y": 650,
      "width": 200,
      "height": 60,
      "required": true,
      "readOnly": false,
      "assignedTo": 0,
      "placeholder": null,
      "defaultValue": null,
      "options": null,
      "validation": null,
      "group": null,
      "format": null,
      "documentId": "cm5x9abc123"
    }
  ]
}

Create a field

POST /api/v1/documents/{id}/fields

Adds a field to a draft document. Maximum 500 fields per document.

Required scope: documents.write

Request body

Field	Type	Required	Description
`type`	`string`	✅	Field type (see field types)
`label`	`string`	✅	Field label (1–200 chars)
`page`	`integer`	—	Page number (default: `1`, min: 1)
`x`	`number`	✅	X position in pixels (0–2000)
`y`	`number`	✅	Y position in pixels (0–5000)
`width`	`number`	✅	Width in pixels (10–2000)
`height`	`number`	✅	Height in pixels (10–2000)
`required`	`boolean`	—	Whether the field is required (default: `true`)
`readOnly`	`boolean`	—	Whether the field is read-only (default: `false`)
`placeholder`	`string`	—	Placeholder text (max 500 chars)
`defaultValue`	`string`	—	Default value (max 1000 chars)
`options`	`string`	—	Options for dropdown/radio/checkbox groups (max 2000 chars)
`validation`	`string`	—	Validation rule (max 500 chars)
`group`	`string`	—	Group name for checkbox/radio groups (max 100 chars)
`format`	`string`	—	Display format (max 100 chars)
`assignedTo`	`integer`	—	Signer index (0-based, default: `0`)

curl -X POST https://app.insigner.co/api/v1/documents/cm5x9abc123/fields \
  -H "Authorization: Bearer isk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "signature",
    "label": "Client Signature",
    "page": 1,
    "x": 100,
    "y": 650,
    "width": 200,
    "height": 60,
    "required": true,
    "assignedTo": 0
  }'

const res = await fetch(
  'https://app.insigner.co/api/v1/documents/cm5x9abc123/fields',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer isk_YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'signature',
      label: 'Client Signature',
      page: 1,
      x: 100, y: 650,
      width: 200, height: 60,
      required: true,
      assignedTo: 0
    })
  }
);
const { data } = await res.json();

res = requests.post(
    "https://app.insigner.co/api/v1/documents/cm5x9abc123/fields",
    headers={"Authorization": "Bearer isk_YOUR_API_KEY"},
    json={
        "type": "signature",
        "label": "Client Signature",
        "page": 1,
        "x": 100, "y": 650,
        "width": 200, "height": 60,
        "required": True,
        "assignedTo": 0
    }
)

Response 201 Created

{
  "data": {
    "id": "fld_abc123",
    "type": "signature",
    "label": "Client Signature",
    "page": 1,
    "x": 100,
    "y": 650,
    "width": 200,
    "height": 60,
    "required": true,
    "readOnly": false,
    "assignedTo": 0,
    "documentId": "cm5x9abc123"
  }
}

Update a field

PATCH /api/v1/documents/{id}/fields/{fieldId}

Updates a field on a draft document. All fields from the create body are accepted but optional.

Required scope: documents.write

curl -X PATCH https://app.insigner.co/api/v1/documents/cm5x9abc123/fields/fld_abc123 \
  -H "Authorization: Bearer isk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "x": 150,
    "y": 700,
    "required": false
  }'

const res = await fetch(
  'https://app.insigner.co/api/v1/documents/cm5x9abc123/fields/fld_abc123',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer isk_YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ x: 150, y: 700, required: false })
  }
);

res = requests.patch(
    "https://app.insigner.co/api/v1/documents/cm5x9abc123/fields/fld_abc123",
    headers={"Authorization": "Bearer isk_YOUR_API_KEY"},
    json={"x": 150, "y": 700, "required": False}
)

Response: Updated field object.

Delete a field

DELETE /api/v1/documents/{id}/fields/{fieldId}

Removes a field from a draft document.

Required scope: documents.write

curl -X DELETE https://app.insigner.co/api/v1/documents/cm5x9abc123/fields/fld_abc123 \
  -H "Authorization: Bearer isk_YOUR_API_KEY"

await fetch(
  'https://app.insigner.co/api/v1/documents/cm5x9abc123/fields/fld_abc123',
  {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer isk_YOUR_API_KEY' }
  }
);

requests.delete(
    "https://app.insigner.co/api/v1/documents/cm5x9abc123/fields/fld_abc123",
    headers={"Authorization": "Bearer isk_YOUR_API_KEY"}
)

Response: 204 No Content