Number fields

Number fields enable recipients to enter numeric values in 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. For currency amounts, you can configure the field to display the currency symbol and three-letter currency code. Separator and currency formatting is applied automatically when a user enters a value in a number field. In addition, you can require recipients to enter values that fall within a range.

Tab types for number fields

To add a number field to a document, you can use either of two types of tabs:

• numericalTabs: These tabs provide robust display and validation features, including formatting for different regions and currencies, and minimum and maximum value validation.
• numberTabs: These tabs validate that the entered value is a number. They do not support advanced validation or display options.

This table compares the two tab types.

For more information about the two tab types, see:

• Features of numericalTabs
• 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.

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

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 for details.
• A series of hash symbols representing digits with the thousand and decimal separators in use. See 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 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.

Sample numericalTab definition

See the JSON code below for a sample definition of a numericalTab.

"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.

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, 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. See the API reference for information about supported currencies.
• The position of the currency symbol (for example, $, €, ¥, etc.). You define this by setting the 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
• 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:

"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

See 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:

"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.

See 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 or template.
• 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 request or equivalent SDK method:

"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 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 defined in 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.
• 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.

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.

"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.

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.

Next steps

• See How to set envelope tab values for code examples that include a numericalTab.
• See EnvelopeRecipientTabs Resource in the API reference for more information about numericalTabs, numberTabs, and other tab types.
• See Calculated fields for information about using number field values in formulas.
• See Requesting payment with tabs for information about using number field values in payment requests.
• See Custom tabs for information about creating custom numericalTabs and numberTabs that you can reuse across envelopes and templates.