GET /v1/fields
GET /v1/fields/:id
GET /v1/fields/:id/attachments

{
  "id": "5f66f4705e35d5c49d2a7af7a896b8b4",
  "type": "signature",
  "page": 1,
  "anchor": "{{signature}}",
  "x_coordinate": 150,
  "y_coordinate": 400,
  "required": true,
  "read_only": false,
  "collaborative": false,
  "value": "foo",
  "checked": false,
  "height": 30,
  "width": 100,
  "options": [],
  "font_size": 12,
  "font_type": "courier",
  "date_format": "DD/MM/YYYY",
  "created": "2019-12-17T05:30:00Z"
}
Fields are a required property of recipients with the type of signer, and define where and how those recipients interact with the document. Each field is defined by its type property, with additional attributes used to control its placement, size, style, and behavior. Fields can be used to collect input, mark approvals, capture dates, or guide recipients through complex workflows.

​
Placement methods

There are two supported strategies for placing fields on a document:

​
Anchors (automatic placement)

Anchors allow fields to be automatically placed wherever a specific text string appears within the document.
  • All documents in the envelope are scanned for the anchor string.
  • A field is created directly over each match — the matched text is not removed or replaced.
  • For best results, render anchor strings using a text color that matches the background (e.g. white) so they remain invisible to recipients.
  • Anchors are positioned from the bottom-left of the matched text.
  • Use x_offset and y_offset to fine-tune placement.
  • Anchors near page edges may be ignored if placement would cause overflow.

​
Coordinates (fixed positioning)

Fields can also be positioned precisely using absolute coordinates.
  • Use x_coordinate, y_coordinate, and page to place a field at an exact location.
  • All coordinates are based on a 72 DPI render, with the origin (0, 0) in the bottom-left corner.
  • All field types anchor from the bottom-left, except input fields, which anchor from the top-left and expand downward as content grows.

​
Field types

​
signature
Requires the recipient to sign the document by drawing or adopting a signature. height and width define dimensions.
​
initials
Requires the recipient to provide their initials. Uses a fixed 1:1 aspect ratio derived from height.
​
witness
Requires the recipient to have another individual witness their signature. Witnesses must enter their full name and email address.
​
date
Prints the date and time when the recipient completes the envelope. Supports font styling and formatting options.
​
input
Creates a free-text input box. Height expands dynamically as the recipient types.
​
checkbox
Creates a single checkbox. Checked boxes display an “X”; unchecked boxes print nothing.
​
dropdown
Creates a dropdown menu. The selected option is printed on the document.

​
Date formats

For fields where the type is set to date, you can control how the date appears on the document using any combination of the tokens below. Supported format tokens:
  • D — Day (1–31)
  • DD — Day (01–31)
  • M — Month (1–12)
  • MM — Month (01–12)
  • MMM — Short month (Jan–Dec)
  • MMMM — Full month (January–December)
  • YY — Year (2-digit, e.g. 24)
  • YYYY — Year (4-digit, e.g. 2024)
  • H — Hour (0–23)
  • HH — Hour (00–23)
  • h — Hour (1–12)
  • hh — Hour (01–12)
  • mm — Minutes (00–59)
  • ss — Seconds (00–59)
  • A — AM/PM
  • a — am/pm
Example format: DD/MM/YYYY hh:mm a

​
Attributes

​
id
string
A user-defined identifier for the field. This must be unique across the entire envelope—including fields belonging to different recipients.Supplying a field ID allows fields to be referenced programmatically (e.g., to retrieve a specific field or track user interactions), but is entirely optional.
​
type
string
The field’s type determines the expected recipient input and how it renders on the document.Valid values include: signature, initials, witness, date, input, checkbox, and dropdown.Each type supports different behaviours and additional properties. Refer to the Field Types section for detailed descriptions.
​
page
integer
The page number on which to place the field. Pages are 1-indexed (the first page is 1).Required when using coordinates. If multiple documents are added to an envelope, page numbering continues as if all documents were merged into one.
​
anchor
string(100)
A string of text used for automatic placement of the field (referred to as an anchor).When this property is supplied, coordinates are not required. The anchor will be matched against all document text, and fields will be placed at each occurrence.Anchors are positioned using a bottom-left origin, and may be fine-tuned with x_offset and y_offset.
​
x_coordinate
integer
The absolute horizontal pixel position for the field.Used with y_coordinate and page to place a field at a specific location. Ignored when using anchors.
​
y_coordinate
integer
The absolute vertical pixel position for the field.Used with x_coordinate and page to enable fixed field placement. Documents should be rendered at 72 DPI with bottom-left origin at (0, 0).
​
required
boolean
Specifies whether the field must be completed before the recipient can finish signing.For:
  • input: at least one character must be entered.
  • checkbox: must be checked.
  • dropdown: a selection must be made.
For non-editable types (e.g., date), this flag is ignored.
​
read_only
boolean
Prevents the recipient from modifying the field’s value.Can be combined with value to print a static string onto the document that the recipient cannot change. Useful for pre-filled, informational fields.
​
collaborative
boolean
Allows the field’s value to be edited by multiple recipients.Used in workflows where later signers must confirm or modify information previously entered. Collaborative fields are rendered live and only finalised when the envelope is completed.
​
value
string
The initial value of the field.For input fields, this will be the starting text. For dropdown fields, it represents the default selected option. Will be updated upon recipient completion.
​
checked
boolean
Specifies whether a checkbox field should start in a checked state when the document loads.This is purely a presentation detail—recipients can still toggle the checkbox. The final result (i.e. whether it was left checked or unchecked) is recorded in the field’s value upon envelope completion.
​
height
integer
The pixel-based height of the field.For input, signature, witness, and initials fields, this defines the vertical size. Note that input fields grow downward as users type, starting from this height.
​
width
integer
The pixel-based width of the field.
  • For signature and witness fields, a 2.5:1 width-to-height ratio is recommended.
  • For initials, width is automatically derived from height using a 1:1 ratio.
​
options
array
An array of selectable options for dropdown fields.Each option includes a value (what is stored) and option (what is shown on the document).
​
font_size
integer
The pixel size of the font used to print text on the document.Applies to fields where visible text is rendered, such as input, dropdown, and date. Acceptable range is 8–32 pixels. Default is 12.
​
font_type
string
The font family used when rendering field text on the document.Acceptable values are courier and helvetica. Defaults to courier if not specified. Only applicable to input, dropdown, and date fields.
​
date_format
string
For fields where the type is set to date, this defines how the date appears on the document.Formats can be customised using tokens such as DD, MMMM, YYYY, etc. For a full list of supported tokens, refer to the Date formats section.
​
created
string
Timestamp indicating when the field was created, in ISO 8601 format.
GET /v1/fields
GET /v1/fields/:id
GET /v1/fields/:id/attachments

{
  "id": "5f66f4705e35d5c49d2a7af7a896b8b4",
  "type": "signature",
  "page": 1,
  "anchor": "{{signature}}",
  "x_coordinate": 150,
  "y_coordinate": 400,
  "required": true,
  "read_only": false,
  "collaborative": false,
  "value": "foo",
  "checked": false,
  "height": 30,
  "width": 100,
  "options": [],
  "font_size": 12,
  "font_type": "courier",
  "date_format": "DD/MM/YYYY",
  "created": "2019-12-17T05:30:00Z"
}