Fields

Fields are the interactive elements placed on document pages that recipients fill in during signing. Each field is assigned to a recipient and positioned on a specific page at precise coordinates.

Fields work the same way on both envelopes and templates.

Properties

Property	Type	Description
`id`	string	Unique identifier for the field.
`identifier`	string	A stable slug you define for API references (e.g. `"counterparty_signature"`). Must be unique within the envelope or template.
`type`	string	Field type. See below.
`label`	string	Display label shown above the field during signing.
`tooltip`	string	Optional helper text shown on hover.
`required`	boolean	If `true`, the recipient must complete this field before submitting.
`readonly`	boolean	If `true`, the field is pre-filled and cannot be edited by the recipient.
`recipientId`	string	The recipient this field is assigned to.
`value`	object	Pre-filled value. Type-specific.
`config`	object	Type-specific configuration.
`views`	array	Placement definitions. A field can appear on multiple pages.
`submittedAt`	datetime	When the recipient submitted this field.

Field types

Type	Description
`simple_signature`	Drawn or typed signature.
`biometric_signature`	Signature with biometric data capture (pressure, speed, stroke order).
`text`	Free-form text input.
`checkbox`	Single boolean checkbox — checked or unchecked.
`radio`	One selection from a predefined group of options.
`binary_choice`	A two-option choice, typically Accept / Decline.

Placement (`views`)

Each entry in the views array defines where the field appears on the document. A single field can appear on multiple pages — useful for initials that repeat on every page.

Property	Type	Required	Description
`documentId`	string	✅	ID of the document where the field is placed.
`page`	number	✅	Zero-based page index within the document.
`location.x`	number	✅	Horizontal position in points from the left edge of the page.
`location.y`	number	✅	Vertical position in points from the top edge of the page.
`size.width`	number	✅	Field width in points.
`size.height`	number	✅	Field height in points.

tip

PDF coordinates use points (1 pt = 1/72 inch). A standard A4 page is 595 × 842 pt. A US Letter page is 612 × 792 pt.

Placing initials on every page

{
  "type": "simple_signature",
  "label": "Initials",
  "views": [
    { "documentId": "doc_...", "page": 0, "location": { "x": 480, "y": 780 }, "size": { "width": 80, "height": 30 } },
    { "documentId": "doc_...", "page": 1, "location": { "x": 480, "y": 780 }, "size": { "width": 80, "height": 30 } },
    { "documentId": "doc_...", "page": 2, "location": { "x": 480, "y": 780 }, "size": { "width": 80, "height": 30 } }
  ]
}

Adding fields

All fields for an envelope or template can be submitted in a single request.

Envelope

POST /api/v1/key/envelopes/{envelopeId}/fields

Template

POST /api/v1/key/templates/{templateId}/fields

{
  "fields": [
    {
      "type": "simple_signature",
      "recipientId": "rcp_...",
      "identifier": "counterparty_signature",
      "label": "Signature",
      "required": true,
      "config": {},
      "views": [
        {
          "documentId": "doc_...",
          "page": 2,
          "location": { "x": 320, "y": 640 },
          "size": { "width": 200, "height": 60 }
        }
      ]
    }
  ]
}

Updating and removing fields

Individual fields can be updated or removed while the envelope is in draft status (or at any time on a template).

Update a field

PATCH /api/v1/key/envelopes/{envelopeId}/fields/{fieldId}
PATCH /api/v1/key/templates/{templateId}/fields/{fieldId}

Remove a field

DELETE /api/v1/key/envelopes/{envelopeId}/fields/{fieldId}
DELETE /api/v1/key/templates/{templateId}/fields/{fieldId}

Properties​

Field types​

Placement (views)​

Placing initials on every page​

Adding fields​

Updating and removing fields​