> ## Documentation Index
> Fetch the complete documentation index at: https://docs.annature.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# The Field object

Fields are a required property of [recipients](/api-reference/recipients/recipient-object) 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

<ParamField path="signature">
  Requires the recipient to sign the document by drawing or adopting a signature. `height` and `width` define dimensions.
</ParamField>

<ParamField path="initials">
  Requires the recipient to provide their initials. Uses a fixed 1:1 aspect ratio derived from `height`.
</ParamField>

<ParamField path="witness">
  Requires the recipient to have another individual witness their signature. Witnesses must enter their full name and email address.
</ParamField>

<ParamField path="date">
  Prints the date and time when the recipient completes the envelope. Supports font styling and formatting options.
</ParamField>

<ParamField path="input">
  Creates a free-text input box. Height expands dynamically as the recipient types.
</ParamField>

<ParamField path="checkbox">
  Creates a single checkbox. Checked boxes display an “X”; unchecked boxes print nothing.
</ParamField>

<ParamField path="dropdown">
  Creates a dropdown menu. The selected option is printed on the document.
</ParamField>

## 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

***

<ParamField path="id" type="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.
</ParamField>

<ParamField path="type" 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.
</ParamField>

<ParamField path="page" type="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.
</ParamField>

<ParamField path="anchor" type="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`.
</ParamField>

<ParamField path="x_coordinate" type="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.
</ParamField>

<ParamField path="y_coordinate" type="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)`.
</ParamField>

<ParamField path="required" type="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.
</ParamField>

<ParamField path="read_only" type="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.
</ParamField>

<ParamField path="collaborative" type="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.
</ParamField>

<ParamField path="value" type="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.
</ParamField>

<ParamField path="checked" type="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.
</ParamField>

<ParamField path="height" type="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.
</ParamField>

<ParamField path="width" type="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.
</ParamField>

<ParamField path="options" type="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).

  <Expandable title="child arguments">
    <ResponseField name="value" type="string">
      The internal value that will be saved for the dropdown when selected.
    </ResponseField>

    <ResponseField name="option" type="string">
      The label that appears to the recipient and is printed on the document.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="font_size" type="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.
</ParamField>

<ParamField path="font_type" 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.
</ParamField>

<ParamField path="date_format" type="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](#date-formats) section.
</ParamField>

<ParamField path="created" type="string">
  Timestamp indicating when the field was created, in ISO 8601 format.
</ParamField>

<RequestExample>
  ```bash Endpoints theme={null}
  GET /v1/fields
  GET /v1/fields/:id
  GET /v1/fields/:id/attachments
  ```
</RequestExample>

<ResponseExample>
  ```json Account Object theme={null}
  {
    "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"
  }
  ```
</ResponseExample>