---
title: "Create a new Field on a Document"
method: POST
path: "/signature_requests/{signatureRequestId}/documents/{documentId}/fields"
tags: ["Field"]
---

# Create a new Field on a Document

`POST /signature_requests/{signatureRequestId}/documents/{documentId}/fields`

Adds a Field to a given Document.

## Path parameters

- `signatureRequestId` string, uuid, required — The unique identifier for a resource.
- `documentId` string, uuid, required — The unique identifier for a resource.

## Request body

- union
  - object
    - `signer_id` string, uuid, required
    - `type` 'signature', required
    - `page` integer, required
    - `x` integer, required
    - `y` integer, required
    - `height` integer — Default value is 37
    - `width` integer — Default value is 85
    - `reason` string
    - `display` union — Controls what is shown within the signature field.
      - object
        - `layout` 'minimal', required — `minimal` (default): Only shows the signer’s signature visual. `detailed`: Adds extra detail to the signature field, including the signer’s full name, email, and the date of signature.
      - object
        - `layout` 'detailed', required — `minimal` (default): Only shows the signer’s signature visual. `detailed`: Adds extra detail to the signature field, including the signer’s full name, email, and the date of signature.
        - `options` SignatureDisplayOneOf1Options, required — Only applicable when `display.layout = detailed`.
          - `date_format` 'dd/MM/yyyy' | 'dd-MM-yyyy' | 'dd.MM.yyyy' | 'yyyy-MM-dd' | 'MM/dd/yyyy' | 'dd MMMM yyyy' | 'MMMM dd, yyyy' | 'MMM dd, yyyy' — Format used to display the date (e.g., `dd/MM/yyyy`, `MM/dd/yyyy`)
          - `time_format` 'null' | 'HH:mm' | 'hh:mm a', nullable — Format used to display the time. Can be null to display only the date, or a format like `HH:mm` or `hh:mm a`
          - `show_timezone` boolean, nullable — Boolean indicating whether to display the timezone abbreviation (e.g., `CEST`) next to the time.
          - `show_email` boolean — Boolean indicating whether to display the signer's email address.
  - object
    - `signer_id` string, uuid, required
    - `type` 'mention', required
    - `page` integer, required
    - `x` integer, required
    - `y` integer, required
    - `width` integer — If not set, the width is automatically calculated with the mention length.
    - `height` integer, nullable — The height must be calculated using the formula: "height = number_of_lines \* font_size \* line_height", where the line height is always set to 1.5.
    - `mention` string, safe-string, required — Content of the Mention.\ You can use dynamic tags when creating the Mention:\ • `%date%` will display the current date when the Signer sign the Signature Request (eg. "24-03-2025")\ • `%datetime%` will display the current date and time when the Signer signs the Signature Request (eg. "24-03-2025 10:30 UTC+0")\ This property is a [Safe String](https://developers.youtrust.com/reference/oas-specification#safe-string) allowing email.
    - `font` CreateFieldFont, nullable — If set, **width** and **height** properties become required. Otherwise, if not set or null, the default font will be used.
      - `family` 'Inconsolata' | 'Open Sans' | 'Lato' | 'Raleway' | 'Merriweather' | 'EB Garamond' | 'Comic Neue' | 'Monaco' | 'Helvetica' | 'Courier' | 'Times Roman', required
      - `color` string, required
      - `size` integer, required
      - `variants` FontVariants, required
        - `italic` boolean, required
        - `bold` boolean, required
    - `name` string, nullable — Name of the Field.
  - object
    - `signer_id` string, uuid, required
    - `type` 'signature_date', required
    - `page` integer, required
    - `x` integer, required
    - `y` integer, required
    - `font` CreateSignatureDateFieldFont, nullable — Font configuration (family, size, color, style variants).
      - `family` 'Inconsolata' | 'Open Sans' | 'Lato' | 'Raleway' | 'Merriweather' | 'EB Garamond' | 'Comic Neue' | 'Monaco' | 'Helvetica' | 'Courier' | 'Times Roman', required
      - `color` string, required
      - `size` integer, required
      - `variants` FontVariants, required
        - `italic` boolean, required
        - `bold` boolean, required
    - `name` string, nullable — Name of the Field.
    - `date_format` 'dd/MM/yyyy' | 'dd-MM-yyyy' | 'dd.MM.yyyy' | 'yyyy-MM-dd' | 'MM/dd/yyyy' | 'dd MMMM yyyy' | 'MMMM dd, yyyy' | 'MMM dd, yyyy' — Format used to display the date (e.g., `dd/MM/yyyy`, `MM/dd/yyyy`)
    - `time_format` 'null' | 'HH:mm' | 'hh:mm a', nullable — Format used to display the time. Can be null to display only the date, or a format like `HH:mm` or `hh:mm a`
    - `show_timezone` boolean, nullable — Boolean indicating whether to display the timezone abbreviation (e.g., `CEST`) next to the time.
    - `show_email` boolean — Boolean indicating whether to display the signer's email address.
    - `offset_unit` 'days' | 'weeks' | 'months' | 'years', nullable — Unit of time used to offset the signature date. When `null`, the field will display the exact signature date.
    - `offset_value` integer, nullable — Number of units to add to the signature date. Ignored if `offset_unit` is `null`. For example, use `offset_unit`: `"month"` and `offset_value: 3` to display "signature date + 3 months"
  - object
    - `signer_id` string, uuid, required
    - `type` 'text', required
    - `page` integer, required
    - `x` integer, required
    - `y` integer, required
    - `width` integer — If not set, the width is automatically calculated with the max_length value
    - `height` integer — The height must be calculated using the formula: "height = number_of_lines \* font_size \* line_height", where the line height is always set to 1.5.
    - `max_length` integer, required
    - `question` string, required — If you don't want any question, you can give an empty string.
    - `instruction` string, nullable
    - `optional` boolean
    - `font` CreateFieldFont, nullable — If set, **width** and **height** properties become required. Otherwise, if not set or null, the default font will be used.
      - `family` 'Inconsolata' | 'Open Sans' | 'Lato' | 'Raleway' | 'Merriweather' | 'EB Garamond' | 'Comic Neue' | 'Monaco' | 'Helvetica' | 'Courier' | 'Times Roman', required
      - `color` string, required
      - `size` integer, required
      - `variants` FontVariants, required
        - `italic` boolean, required
        - `bold` boolean, required
    - `name` string, nullable — Name of the Field.
    - `default_value` string, nullable — If a default value is provided, the Field will be pre-filled with this value. The Signer can modify it before signing unless the Field is set to `read-only`.
    - `read_only` boolean — If set to `true`, the Signer cannot modify the Field and the default value (if provided) will remain unchanged.
  - object
    - `signer_id` string, uuid, required
    - `type` 'checkbox', required
    - `page` integer, required
    - `x` integer, required
    - `y` integer, required
    - `size` integer
    - `optional` boolean
    - `name` string, nullable
    - `checked` boolean
    - `read_only` boolean — If set to `true`, the checkbox cannot be modified by the signer.
  - object
    - `signer_id` string, uuid, required
    - `type` 'radio_group', required
    - `page` integer, required
    - `optional` boolean
    - `name` string, nullable — Radio group's name
    - `read_only` boolean — If set to `true`, the radio button cannot be modified by the Signer.
    - `radios` RadioGroupRadiosInner[], required
      - `name` string, nullable — Radio button's name
      - `x` integer, required
      - `y` integer, required
      - `size` integer
      - `default_checked` boolean — Indicates whether the radio is initially checked (`true`) or unchecked (`false`).
  - object
    - `type` 'read_only_text', required
    - `page` integer, required
    - `x` integer, required
    - `y` integer, required
    - `width` integer, nullable — If not set, the width is automatically calculated with the read only text length.
    - `height` integer, nullable — The height must be calculated using the formula: "height = number_of_lines \* font_size \* line_height", where the line height is always set to 1.5.
    - `text` string, required
    - `font` CreateFieldFont, nullable — If set, **width** and **height** properties become required. Otherwise, if not set or null, the default font will be used.
      - `family` 'Inconsolata' | 'Open Sans' | 'Lato' | 'Raleway' | 'Merriweather' | 'EB Garamond' | 'Comic Neue' | 'Monaco' | 'Helvetica' | 'Courier' | 'Times Roman', required
      - `color` string, required
      - `size` integer, required
      - `variants` FontVariants, required
        - `italic` boolean, required
        - `bold` boolean, required
  - object
    - `signer_id` string, uuid, required
    - `type` 'signer_name', required
    - `page` integer, required
    - `x` integer, required
    - `y` integer, required
    - `font` CreateFieldFont, nullable — If set, **width** and **height** properties become required. Otherwise, if not set or null, the default font will be used.
      - `family` 'Inconsolata' | 'Open Sans' | 'Lato' | 'Raleway' | 'Merriweather' | 'EB Garamond' | 'Comic Neue' | 'Monaco' | 'Helvetica' | 'Courier' | 'Times Roman', required
      - `color` string, required
      - `size` integer, required
      - `variants` FontVariants, required
        - `italic` boolean, required
        - `bold` boolean, required
    - `name` string, nullable — Name of the Field.
    - `name_format` 'full_name' | 'first_name' | 'last_name' — Format used to display the signer's name.
  - object
    - `signer_id` string, uuid, required
    - `type` 'signer_email', required
    - `page` integer, required
    - `x` integer, required
    - `y` integer, required
    - `font` CreateFieldFont, nullable — If set, **width** and **height** properties become required. Otherwise, if not set or null, the default font will be used.
      - `family` 'Inconsolata' | 'Open Sans' | 'Lato' | 'Raleway' | 'Merriweather' | 'EB Garamond' | 'Comic Neue' | 'Monaco' | 'Helvetica' | 'Courier' | 'Times Roman', required
      - `color` string, required
      - `size` integer, required
      - `variants` FontVariants, required
        - `italic` boolean, required
        - `bold` boolean, required
    - `name` string, nullable — Name of the Field.

## Response `201`

Created

- union
  - FieldSignature
    - `id` string, uuid, required
    - `document_id` string, uuid, required
    - `signer_id` string, uuid, required
    - `type` 'signature', required
    - `height` integer, required
    - `width` integer, required
    - `page` integer, required
    - `x` integer, required
    - `y` integer, required
    - `reason` string, required
    - `display` union, required — Controls what is shown within the signature field.
      - object
        - `layout` 'minimal' | 'legacy', required — • `minimal` (default): Only shows the signer’s signature visual. • `detailed`: Adds extra detail to the signature field, including the signer’s full name, email, and the date of signature.
      - object
        - `layout` 'detailed', required — • `minimal` (default): Only shows the signer’s signature visual. • `detailed`: Adds extra detail to the signature field, including the signer’s full name, email, and the date of signature.
        - `options` SignatureDisplayOneOf1Options, required — Only applicable when `display.layout = detailed`.
          - `date_format` 'dd/MM/yyyy' | 'dd-MM-yyyy' | 'dd.MM.yyyy' | 'yyyy-MM-dd' | 'MM/dd/yyyy' | 'dd MMMM yyyy' | 'MMMM dd, yyyy' | 'MMM dd, yyyy' — Format used to display the date (e.g., `dd/MM/yyyy`, `MM/dd/yyyy`)
          - `time_format` 'null' | 'HH:mm' | 'hh:mm a', nullable — Format used to display the time. Can be null to display only the date, or a format like `HH:mm` or `hh:mm a`
          - `show_timezone` boolean, nullable — Boolean indicating whether to display the timezone abbreviation (e.g., `CEST`) next to the time.
          - `show_email` boolean — Boolean indicating whether to display the signer's email address.
  - FieldText
    - `id` string, uuid, required
    - `document_id` string, uuid, required
    - `signer_id` string, uuid, required
    - `type` 'text', required
    - `width` integer, required — If not set, the width is automatically calculated with the max_length value
    - `height` integer, required — The height must be calculated using the formula: "height = number_of_lines \* font_size \* line_height", where the line height is always set to 1.5.
    - `page` integer, required
    - `x` integer, required
    - `y` integer, required
    - `question` string, required
    - `instruction` string, nullable, required
    - `optional` boolean, required
    - `answer` string, nullable, required
    - `max_length` integer, required
    - `font` Font, required
      - `family` 'Inconsolata' | 'Open Sans' | 'Lato' | 'Raleway' | 'Merriweather' | 'EB Garamond' | 'Comic Neue' | 'Monaco' | 'Helvetica' | 'Courier' | 'Times Roman', required
      - `color` string, required
      - `size` integer, required
      - `variants` FontVariants, required
        - `italic` boolean, required
        - `bold` boolean, required
    - `name` string, nullable
    - `default_value` string, nullable
    - `read_only` boolean
  - FieldMention
    - `id` string, uuid, required
    - `document_id` string, uuid, required
    - `signer_id` string, uuid, required
    - `type` 'mention', required
    - `height` integer, required — The height must be calculated using the formula: "height = number_of_lines \* font_size \* line_height", where the line height is always set to 1.5.
    - `width` integer, required
    - `page` integer, required
    - `x` integer, required
    - `y` integer, required
    - `mention` string, required
    - `font` Font, required
      - `family` 'Inconsolata' | 'Open Sans' | 'Lato' | 'Raleway' | 'Merriweather' | 'EB Garamond' | 'Comic Neue' | 'Monaco' | 'Helvetica' | 'Courier' | 'Times Roman', required
      - `color` string, required
      - `size` integer, required
      - `variants` FontVariants, required
        - `italic` boolean, required
        - `bold` boolean, required
    - `name` string, nullable — Name of the Field.
  - FieldCheckbox
    - `id` string, uuid, required
    - `document_id` string, uuid, required
    - `signer_id` string, uuid, required
    - `type` 'checkbox', required
    - `name` string, nullable, required — Checkbox name
    - `checked` boolean, required — Signer has checked the checkbox
    - `page` integer, required
    - `optional` boolean, required
    - `x` integer, required
    - `y` integer, required
    - `size` integer — The size determines both the width and height of the checkbox.
  - FieldRadioButtonGroup
    - `id` string, uuid, required
    - `document_id` string, uuid, required
    - `signer_id` string, uuid, required
    - `type` 'radio_group', required
    - `page` integer, required
    - `optional` boolean, required — Does the Signer has to select one of the radio buttons from this group?
    - `name` string, nullable, required
    - `radios` FieldRadioButtonGroupRadiosInner[], required
      - `name` string, nullable, required — Radio button's name.
      - `x` integer, required
      - `y` integer, required
      - `size` integer, required — The size determines both the width and height of the radio button.
      - `checked` boolean, required — Signer has checked the radio button.
  - FieldReadOnlyText
    - `id` string, uuid, required
    - `document_id` string, uuid, required
    - `type` 'read_only_text', required
    - `height` integer, required — The height must be calculated using the formula: "height = number_of_lines \* font_size \* line_height", where the line height is always set to 1.5.
    - `width` integer, required — If not set, the width is automatically calculated with the max_length value
    - `page` integer, required
    - `x` integer, required
    - `y` integer, required
    - `text` string, required — This property holds the content displayed in the read-only text field.
    - `font` Font, required
      - `family` 'Inconsolata' | 'Open Sans' | 'Lato' | 'Raleway' | 'Merriweather' | 'EB Garamond' | 'Comic Neue' | 'Monaco' | 'Helvetica' | 'Courier' | 'Times Roman', required
      - `color` string, required
      - `size` integer, required
      - `variants` FontVariants, required
        - `italic` boolean, required
        - `bold` boolean, required
  - FieldSignatureDate
    - `id` string, uuid, required
    - `document_id` string, uuid, required
    - `signer_id` string, uuid, required
    - `type` 'signature_date', required
    - `height` integer, required — The height must be calculated using the formula: "height = number_of_lines \* font_size \* line_height", where the line height is always set to 1.5.
    - `width` integer, required
    - `page` integer, required
    - `x` integer, required
    - `y` integer, required
    - `value` string, nullable, required
    - `font` Font, required
      - `family` 'Inconsolata' | 'Open Sans' | 'Lato' | 'Raleway' | 'Merriweather' | 'EB Garamond' | 'Comic Neue' | 'Monaco' | 'Helvetica' | 'Courier' | 'Times Roman', required
      - `color` string, required
      - `size` integer, required
      - `variants` FontVariants, required
        - `italic` boolean, required
        - `bold` boolean, required
    - `name` string, nullable — Name of the Field.
    - `date_format` 'dd/MM/yyyy' | 'dd-MM-yyyy' | 'dd.MM.yyyy' | 'yyyy-MM-dd' | 'MM/dd/yyyy' | 'dd MMMM yyyy' | 'MMMM dd, yyyy' | 'MMM dd, yyyy' — Format used to display the date (e.g., `dd/MM/yyyy`, `MM/dd/yyyy`)
    - `time_format` 'null' | 'HH:mm' | 'hh:mm a', nullable — Format used to display the time. Can be null to display only the date, or a format like `HH:mm` or `hh:mm a`
    - `show_timezone` boolean, nullable — Boolean indicating whether to display the timezone abbreviation (e.g., `CEST`) next to the time.
    - `show_email` boolean — Boolean indicating whether to display the signer's email address.
    - `offset_unit` 'days' | 'weeks' | 'months' | 'years', nullable — Unit of time used to offset the signature date. When `null`, the field will display the exact signature date.
    - `offset_value` integer, nullable — Number of units to add to the signature date. Ignored if `offset_unit` is `null`. For example, use `offset_unit`: `"month"` and `offset_value: 3` to display "signature date + 3 months"
  - FieldSignerName
    - `id` string, uuid, required
    - `document_id` string, uuid, required
    - `signer_id` string, uuid, required
    - `type` 'signer_name', required
    - `height` integer, required — The height must be calculated using the formula: "height = number_of_lines \* font_size \* line_height", where the line height is always set to 1.5.
    - `width` integer, required
    - `page` integer, required
    - `x` integer, required
    - `y` integer, required
    - `value` string, nullable, required
    - `font` Font, required
      - `family` 'Inconsolata' | 'Open Sans' | 'Lato' | 'Raleway' | 'Merriweather' | 'EB Garamond' | 'Comic Neue' | 'Monaco' | 'Helvetica' | 'Courier' | 'Times Roman', required
      - `color` string, required
      - `size` integer, required
      - `variants` FontVariants, required
        - `italic` boolean, required
        - `bold` boolean, required
    - `name` string, nullable — Name of the Field.
    - `name_format` 'full_name' | 'first_name' | 'last_name' — Format used to display the signer's name.
  - FieldSignerEmail
    - `id` string, uuid, required
    - `document_id` string, uuid, required
    - `signer_id` string, uuid, required
    - `type` 'signer_email', required
    - `height` integer, required — The height must be calculated using the formula: "height = number_of_lines \* font_size \* line_height", where the line height is always set to 1.5.
    - `width` integer, required
    - `page` integer, required
    - `x` integer, required
    - `y` integer, required
    - `value` string, nullable, required
    - `font` Font, required
      - `family` 'Inconsolata' | 'Open Sans' | 'Lato' | 'Raleway' | 'Merriweather' | 'EB Garamond' | 'Comic Neue' | 'Monaco' | 'Helvetica' | 'Courier' | 'Times Roman', required
      - `color` string, required
      - `size` integer, required
      - `variants` FontVariants, required
        - `italic` boolean, required
        - `bold` boolean, required
    - `name` string, nullable — Name of the Field.

## Other responses

- `400` — Bad request
- `401` — Access unauthorized
- `403` — Access forbidden
- `404` — Resource not found
- `405` — This method is not allowed
- `415` — UnsupportedMediaType
- `429` — Too Many Requests, please try again later.
- `500` — Internal Server Error

---

[API](https://skmtc.net/yousign/apis/public-api-v3.md) · [All operations](https://skmtc.net/yousign/apis/public-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yousign/public-api-v3/revisions/8d258c0b45d6/schema)