> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL. > > Documentation indexes by section: > - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt > - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt > - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt > - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt > > Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth > Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks > > OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json > MCP server: https://docusign.docs.buildwithfern.com/_mcp/server # Number fields > Learn about fields that enable recipients to enter numeric values in documents. *Number fields* enable [recipients](/docs/esign-rest-api/esign101/concepts/recipients) to enter numeric values in [documents](/docs/esign-rest-api/esign101/concepts/documents). They offer several formatting and validation options. For example, when you define a number field, you can select the characters to use as [thousand and decimal separators](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#set-the-numericaltab-number-display-format). For currency amounts, you can configure the field to display the [currency symbol and three-letter currency code](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#treat-a-numericaltab-value-as-number-or-currency). Separator and currency formatting is [applied automatically](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#ui-behavior-and-validation-of-numericaltabs) when a user enters a value in a number field. In addition, you can require recipients to enter [values that fall within a range](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#set-numericaltab-minimum-and-maximum-values). ## Tab types for number fields To add a number field to a document, you can use either of two types of [tabs](/docs/esign-rest-api/esign101/concepts/tabs): * [numericalTabs](/docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/create#schema__enveloperecipienttabs_numericaltabs): These tabs provide robust display and validation features, including formatting for different regions and currencies, and minimum and maximum value validation. * [numberTabs](/docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/create#schema__enveloperecipienttabs_numbertabs): These tabs validate that the entered value is a number. They do not support advanced validation or display options. > **Warning** > > The `numericalTabs` type is available in all developer accounts, but only in certain production account plans. Contact [Docusign Support](https://support.docusign.com/s/contactSupport) or your account manager to find out whether this feature is available for your production account plan. In addition, the `numericalTabs` type is available only in eSignature REST API v2.1. The `numberTabs` type is available in all production account plans, and in both eSignature REST API v2 and v2.1. This table compares the two tab types. | Feature | Supported in numericalTabs | Supported in numberTabs | | ------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ----------------------- | | Validate that the user-entered value is a number | Yes | Yes | | Display the value with currency symbol and/or name | Yes | No | | Specify which thousand and decimal separator characters to use | Yes | No | | Format negative numbers with parentheses | Yes | No | | Set the minimum and/or maximum value that a user can enter | Yes | No | | Accept more than two digits of decimal precision | No | Yes | | Use the tab value in [calculated fields](/docs/esign-rest-api/esign101/concepts/tabs/calculated-fields) (formula tabs) | Yes | Yes | | Use the tab value with [payment requests](/docs/esign-rest-api/esign101/concepts/tabs/payment) | No | Yes | | Set the tab position using [auto-place](/docs/esign-rest-api/esign101/concepts/tabs/auto-place) (anchor tagging) | Yes | Yes | | Set the tab position using [fixed positioning](/docs/esign-rest-api/esign101/concepts/tabs/fixed) | Yes | Yes | | Show the tab only when certain [conditions](/docs/esign-rest-api/esign101/concepts/tabs/conditional-fields) have been met | Yes | Yes | | Create [custom tabs](/docs/esign-rest-api/esign101/concepts/tabs/custom-tabs) for the tab type | Yes | Yes | | Use [data replication](/docs/esign-rest-api/esign101/concepts/tabs/data-replication) to share values between tabs | Yes | Yes | | [Transform PDF form fields](/docs/esign-rest-api/esign101/concepts/tabs/pdf-transform) into Docusign tabs | No | Yes | > **Note** > > For some features listed above as not supported in `numberTabs`, you can use a regular expression to implement the feature. See [UI behavior and validation of numberTabs](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#ui-behavior-and-validation-of-numbertabs) for details. For more information about the two tab types, see: * [Features of numericalTabs](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#features-of-numericaltabs) * [Features of numberTabs](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#features-of-numbertabs) ## Features of numericalTabs ### UI behavior and validation of numericalTabs When you define a `numericalTab`, you can specify number and currency formatting to be applied to values that users enter. For example, if a user enters **50000**, and the tab definition specifies the default U.S. number and currency formats, the value is automatically reformatted as shown below. ![A red-outlined rectangular field with a value of fifty thousand and zero cents in US dollars, formatted to have the currency symbol at the beginning of the value, a comma between 50 and the next 3 zeroes, and point-zero-zero at the end.](/_fern-files/_img/611ee1d71ecb698c5bf17970a455a34d64097207ed9324f41cd9d309662783c2.webp) The `numericalTab` type also validates that a user has entered a number. It supports various options for thousand and decimal separators, and the validation checks that the entered value is compatible with the format specified in the tab definition. See [Set the numericalTab number display format](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#set-the-numericaltab-number-display-format) for more information. To help users understand the format and types of values permitted for a `numericalTab`, the signing UI displays a tooltip like this: ![A red-outlined rectangular, blank field. A yellow-shaded box above it states: 'Required - Number - Value must be between zero and one hundred thousand,' in black text.](/_fern-files/docusign.docs.buildwithfern.com/cb248c6fa8fbaf6566aa1bd64839a63b332299ae82a641ff666bfbaeb2fd1214/assets/img/esign-rest-api/numericalTabTooltip.png) The tooltip includes the following information: * **Required** or **optional**. **Required** means the user must supply a value in order to complete the signing process. * **Number** or **currency**. For **currency**, the value a user enters is automatically formatted to indicate the currency. See [Treat a numericalTab value as number or currency](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#treat-a-numericaltab-value-as-number-or-currency) for details. * A series of hash symbols representing digits with the thousand and decimal separators in use. See [Set the numericalTab number display format](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#set-the-numericaltab-number-display-format) for details about the options. * The minimum and/or maximum permitted value, if specified in the `numericalTab` definition. See [Set numericalTab minimum and maximum values](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#set-numericaltab-minimum-and-maximum-values) for details. If a user-entered value in a `numericalTab` is not a number, has separators different from those specified in the tab definition, or violates a minimum or maximum restriction, the signing UI displays a tooltip with a message in red text indicating why the validation did not pass. The user will not be able to complete the signing process until the validation error is resolved. Below is an example of a message displayed when a value is outside the allowed range. ![A red-outlined rectangular field with 51000 euros inputted. A yellow-shaded box above it states: 'Required - Currency' in black text and 'Value must be between (50000 euros) and 50000 euros' in red text.](/_fern-files/_img/10ccd058f03b7d6cbb355dc7e05922e75907b81dfb0e631fabaf35a0dbd7be9f.webp) ### Sample numericalTab definition See the JSON code below for a sample definition of a `numericalTab`. ```text "numericalTabs": [ { "recipientId": "1", "documentId": "1", "pageNumber": "1", "xPosition": "400", "yPosition": "400", "width": "50", "height": "20", "validationType": "currency", "minNumericalValue": "-50000", "maxNumericalValue": "50000", "numericalValue": "20000", "localePolicy": { "cultureName": "de", "currencyCode": "eur", "currencyPositiveFormat": "csym_1_period_234_period_567_comma_89", "currencyNegativeFormat": "opar_csym_1_period_234_period_567_comma_89_cpar", "useLongCurrencyFormat": "true" } } ] ``` The sections below describe `numericalTab` options and behaviors. See the API reference for detailed descriptions of all [numericalTab properties](/docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/create#schema__enveloperecipienttabs_numericaltabs). ### Treat a numericalTab value as number or currency When defining a `numericalTab`, you can specify whether the value in the field is treated as a number or currency amount by setting the tab’s `validationType` property to `number` or `currency`. If you select `number`, you can set the [number display format](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#set-the-numericaltab-number-display-format), including thousand and decimal separators and negative number formatting. If you select `currency`, in addition to the number display format, you can specify the following: * The currency in which the value is denominated. You can define the currency in the `localePolicy.currencyCode` property, or omit the property and use the [default](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#use-the-culture-defaults). See the API reference for information about [supported currencies](/docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/create#schema__enveloperecipienttabs_numericaltabs_localepolicy_currencycode). * The position of the currency symbol (for example, \$, €, ¥, etc.). You define this by setting the [number display format](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#set-the-numericaltab-number-display-format). * Whether to include the three-letter currency code (for example, USD, EUR, JPY, etc.) at the end of the displayed value. A value of `true` for the `localePolicy.useLongCurrencyFormat` property causes the currency code to be displayed. ### Set the numericalTab number display format Regardless of whether you set the `numericalTab` `validationType` property to `number` or `currency`, you can set properties that determine: * The thousand separator: comma, period, space, or single quote * The decimal separator: comma, period, or none if the value only supports whole numbers * The format for negative numbers: leading minus sign, trailing minus sign, or parentheses * Whether the currency symbol appears before or after the amount. Although all formats specify a location for a currency symbol, it is displayed only if `validationType` is `currency`. There are two ways to set a display format: * [Use the culture defaults](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#use-the-culture-defaults) * [Explicitly define formatting](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#explicitly-define-formatting) #### Use the culture defaults If you use the `localePolicy.cultureName` property, the currency (for `numericalTabs` where `validationType` is `currency`) and positive and negative number formats will conform to the defaults for the culture. For example, if the `localePolicy` looks like this: ```text "localePolicy": { "cultureName": "fr", "useLongCurrencyFormat": "false" } ``` The formatting in the signing UI will be as follows: **Currency validation** Positive: 50 000.00 € Negative: -50 000.00 € **Number validation** Positive: 50 000.00 Negative: -50 000.00 > **Note** > > The API reference has information about valid values for [localePolicy.cultureName](/docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/create#schema__enveloperecipienttabs_numericaltabs_localepolicy_culturename) and the default currency and positive and negative number formats for each culture. See [Default values for numericalTab currency and number formats](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#default-values-for-numericaltab-currency-and-number-formats) for information about how the format is determined if you do not supply a `localePolicy` for a `numericalTab`. #### Explicitly define formatting If you use these properties, you can set the currency, separator characters, location of the currency symbol, and negative number formatting: * `localePolicy.currencyCode` * `localePolicy.currencyPositiveFormat` * `localePolicy.currencyNegativeFormat` For example, if the `localePolicy` looks like this: ```text "localePolicy": { "currencyCode": "eur", "currencyPositiveFormat": "csym_1_period_234_period_567_comma_89", "currencyNegativeFormat": "opar_csym_1_period_234_period_567_comma_89_cpar", "useLongCurrencyFormat": "false" } ``` The formatting in the signing UI will be as follows: **Currency validation** Positive: €50.000,00 Negative: (€50.000,00) **Number validation** Positive: 50.000,00 Negative: (50.000,00) > **Note:** Currently, none of the supported formats for `numericalTabs` allow more than two digits after the decimal separator. > **Note** > > The API reference has information about valid values for [localePolicy.currencyCode](/docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/create#schema__enveloperecipienttabs_numericaltabs_localepolicy_currencycode), [localePolicy.currencyPositiveFormat](/docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/create#schema__enveloperecipienttabs_numericaltabs_localepolicy_currencypositiveformat), and [localePolicy.currencyNegativeFormat](/docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/create#schema__enveloperecipienttabs_numericaltabs_localepolicy_currencynegativeformat). See [Default values for numericalTab currency and number formats](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#default-values-for-numericaltab-currency-and-number-formats) for information about how the format is determined if you do not supply a `localePolicy` for a `numericalTab`. ### Storage of formatted and unformatted values for numericalTabs `numericalTabs` store values in these properties: * `numericalValue`: Stores the field value with thousand and decimal separators, and a minus sign if the value is negative. If you want to set a default value for the `numericalTab` that will appear in the field when the signing document loads, include a value for this property in the API request that creates an [envelope](/docs/esign-rest-api/esign101/concepts/envelopes) or [template](/docs/esign-rest-api/esign101/concepts/templates). * `value`: Stores the formatted value of `numericalValue`. Do not set this value in the API request that creates an envelope or template. It will be overwritten with the formatted value of `numericalValue`. For example, if the default U.S. number and currency formats are in use, including the three-letter currency code, and a user enters a value of **-50000** in the signing UI, it will be stored as follows in these two `numericalTab` properties, as returned by an [EnvelopeRecipientTabs:list](/docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/list) request or equivalent SDK method: ```text "numericalValue": "-50,000.00", "value": "($50,000.00) USD", ``` ### Default values for numericalTab currency and number formats Default values are used if a currency code, positive number format, and negative number format are not defined for a `numericalTab`. A summary of the behavior is below. * If `localePolicy.currencyCode`, `localePolicy.currencyPositiveFormat`, and `localePolicy.currencyNegativeFormat` are specified, those properties will be used and will override the defaults associated with `localePolicy.cultureName`. * If `localePolicy.currencyCode`, `localePolicy.currencyPositiveFormat`, and/or `localePolicy.currencyNegativeFormat` are omitted, the default currency and/or formats associated with `localePolicy.cultureName` (if supplied) are used. * If `localePolicy.currencyCode`, `localePolicy.currencyPositiveFormat`, and/or `localePolicy.currencyNegativeFormat` are omitted, and no `localePolicy.cultureName` was supplied for the `numericalTab`, the default currency and format associated with envelope sender’s user-level locale policy are used. To retrieve the user-level locale policy, make a request to the [Users:getSettings](/docs/esign-rest-api/reference/users/users/getsettings) endpoint or an equivalent SDK method, and check the value of `localePolicy.cultureName` in the response. * Any API request that creates or updates a `numericalTab` will receive an API error response if the positive and negative formats are incompatible, regardless of whether they are specified in `localePolicy.currencyPositiveFormat` and `localePolicy.currencyNegativeFormat`, or derived from the `numericalTab` culture name or user-level culture name. For example, a positive format that uses a comma as the decimal separator is not compatible with a negative format that uses a period as the decimal separator. ### Set numericalTab minimum and maximum values You can use the `numericalTab` properties `minNumericalValue` and `maxNumericalValue` to validate user-entered values against a minimum and/or maximum. If a user enters a value that violates a minimum or maximum restriction, the field’s tooltip displays the value restriction in red text: for example, **Value must be between 0.00 and 100,000.00**. The user will not be able to complete the signing process until the validation error is resolved. The API supports a `minNumericalValue` as low as -999,999,999.99 and a `maxNumericalValue` of up to 999,999,999.99. In the absence of explicit `minNumericalValue` and `maxNumericalValue` properties in an API request, the system uses a default minimum of -999,999,999.99 and a default maximum of 999,999,999.99. ### Use numericalTab values in calculations Values from `numericalTabs` can be used in [calculated fields](/docs/esign-rest-api/esign101/concepts/tabs/calculated-fields) defined in [formulaTabs](/docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/create#schema__enveloperecipienttabs_formulatabs). When using values from multiple `numericalTabs` in a `formulaTab`: * The `localePolicy` property of all the `numericalTabs` must be identical. If not, an API error response will be returned. * You can also omit the `localePolicy` property from all the `numericalTabs`, and they will use the [default settings](/docs/esign-rest-api/esign101/concepts/tabs/number-fields#default-values-for-numericaltab-currency-and-number-formats). * The `formulaTab` will follow the same `localePolicy` settings as the referenced `numericalTabs` automatically, or the default settings if the `numericalTabs` do not include a `localePolicy`. * Do not specify a `localePolicy` in the `formulaTab`. It will be ignored, and under some circumstances may cause an API error response. * If a `formulaTab` includes values from some `numericalTabs` that use currency validation and others that use number validation, the `formulaTab` uses the `localePolicy` of the `numericalTabs` with currency validation. In this scenario, mismatching `localePolicy` values are permitted for the `numericalTabs` with number validation, but the `localePolicy` of all `numericalTabs` with currency validation must match. * If a `formulaTab` includes values from both `numericalTabs` and `numberTabs`, do not specify a `localePolicy` in the `numberTabs`. It will be ignored, and under some circumstances may cause an API error response. * If an envelope or template includes more than one `formulaTab`, each referencing a different set of `numericalTabs`, the `localePolicy` can differ between the sets of `numericalTabs`; however, each `formulaTab`'s referenced `numericalTabs` must have consistent `localePolicy` settings, or no `localePolicy`. ### numericalTab equivalent in the eSignature web app In the eSignature web app, the component that’s equivalent to the API `numericalTab` element is the **Number** field. For more information, see [Field Types](https://support.docusign.com/s/document-item?bundleId=ulp1643236876813\&topicId=vfk1578456408630.html). ## Features of numberTabs ### UI behavior and validation of numberTabs The `numberTab` type validates that the value a user has entered is a number. The validation allows an unlimited number of digits after the decimal separator, which is a period by default. The value can also include a leading minus sign to indicate a negative number. To change the validation for a `numberTab`, include a `validationPattern` property, with its value set to a regular expression. For example, this regular expression allows a comma as the decimal separator instead of a period: `"validationPattern": "^-?\\d{0,}(\\,\\d{1,})?$",` If a user enters a value that fails the validation, the field’s tooltip displays an **Invalid number** message in red text, and the user will not be able to complete the signing process until the validation error is resolved. ### Sample numberTab definition See the JSON code below for a sample definition of a `numberTab`. ```text "numberTabs": [ { "recipientId": "1", "documentId": "1", "pageNumber": "1", "xPosition": "400", "yPosition": "300", "width": "50", "height": "20", "locked": "false", "value": "50000", } ] ``` See the API reference for detailed descriptions of all [numberTab properties](/docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/create#schema__enveloperecipienttabs_numbertabs). ### numberTab equivalent in the eSignature web app In the eSignature web app, the component that’s equivalent to the API `numberTab` element is the **Text** field with number validation. For more information, see [Data Validation for Text Fields](https://support.docusign.com/s/document-item?bundleId=gbo1643332197980\&topicId=jgd1578456357365.html). ## Next steps * See [How to set envelope tab values](/docs/esign-rest-api/how-to/set-envelope-tab-values) for code examples that include a `numericalTab`. * See [EnvelopeRecipientTabs Resource](/docs/esign-rest-api/reference/envelopes/enveloperecipienttabs) in the API reference for more information about `numericalTabs`, `numberTabs`, and other tab types. * See [Calculated fields](/docs/esign-rest-api/esign101/concepts/tabs/calculated-fields) for information about using number field values in formulas. * See [Requesting payment with tabs](/docs/esign-rest-api/esign101/concepts/tabs/payment) for information about using number field values in payment requests. * See [Custom tabs](/docs/esign-rest-api/esign101/concepts/tabs/custom-tabs) for information about creating custom `numericalTabs` and `numberTabs` that you can reuse across envelopes and templates.