The Field object
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_offsetandy_offsetto 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, andpageto 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
inputfields, which anchor from the top-left and expand downward as content grows.
Field types
Requires the recipient to sign the document by drawing or adopting a signature. height and width define dimensions.
Requires the recipient to provide their initials. Uses a fixed 1:1 aspect ratio derived from height.
Requires the recipient to have another individual witness their signature. Witnesses must enter their full name and email address.
Prints the date and time when the recipient completes the envelope. Supports font styling and formatting options.
Creates a free-text input box. Height expands dynamically as the recipient types.
Creates a single checkbox. Checked boxes display an “X”; unchecked boxes print nothing.
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/PMa— am/pm
Example format: DD/MM/YYYY hh:mm a
Attributes
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
The pixel-based width of the field.
- For
signatureandwitnessfields, a 2.5:1 width-to-height ratio is recommended. - For
initials, width is automatically derived from height using a 1:1 ratio.
An array of selectable options for dropdown fields.
Each option includes a value (what is stored) and option (what is shown on the document).
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.
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.
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.
Timestamp indicating when the field was created, in ISO 8601 format.