> For the complete documentation index, see [llms.txt](https://developers.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.docstudio.com/api-documentation/template-api/template-dynamic-fields-api/number-field-api.md).

# Number Field API

Use this page to add a number field to template XML. Assign the field to a role with `roleId`, then reuse the same field `name` in envelope requests.

### Number field example

```xml
<field
    type="number"
    name="invoice_amount"
    placeholder="Enter amount"
    roleId="fd8cb669-db1d-41e1-8f6c-2ad3f8fa981a"
    optional="false"
    search="true"
    formatting="true"
    trailingZeros="true"
    precision="2"
    min="0"
    max="999999"
/>
```

### How it works

1. Add the field inside the document body.
2. Assign the field to a recipient role with `roleId`.
3. Reuse the same field `name` later when sending or filling an envelope.

### Required attributes

* `type` — field type. Use `number`.
* `name` — field name. Use 1 to 128 characters. Do not use `&`, `"`, `<`, or `>`. Keep the value unique within one document.
* `roleId` — role identifier for the recipient who fills the field.

### Optional attributes

* `placeholder` — placeholder text shown in the template and envelope. Use 0 to 1024 characters. If you omit it, the envelope shows the field name.
* `optional` — set to `true` if the recipient can leave the field empty. If you omit it, the default value is `false`.
* `search` — set to `true` if the field value should be available in envelope search. If you omit it, the default value is `false`.
* `formatting` — set to `true` to display the value in the user's local number format.
* `trailingZeros` — set to `true` to keep decimal zeros after the value is filled. Use this attribute with `precision`.
* `precision` — number of decimal places allowed.
* `min` — minimum numeric value allowed in the field.
* `max` — maximum numeric value allowed in the field.

### Validation rules

* `precision` supports values from `0` to `7`.
* `min` and `max` support values from `-999999999999999` to `999999999999999`.
* `trailingZeros` is relevant only when `precision` is set.

### Related topics

* [Template Dynamic Fields API](/api-documentation/template-api/template-dynamic-fields-api.md)
* [Template Structure API](/api-documentation/template-api/template-structure-api.md)
* [Send Envelope](/api-documentation/envelope/send-envelope.md)
* [Fill Envelope](/api-documentation/envelope/fill-envelope.md)