Custom regex validation lets you define the format recipients must follow when entering information into text fields created using Text Tags.
Text field tags accept custom as the validation type (option 9). Custom validation requires two additional options: a regular expression that the recipient's input must match (option 11) and an error message displayed when the input doesn't match (option 12).
Text Field Tag Options
| # | Option | Notes |
|---|---|---|
| 1 | Field type | text or t |
| 2 | Signer number | The recipient number |
| 3 | Required | y / n |
| 4 | Label | Field label |
| 5 | Value | Prefilled value. With custom, it must match the regex pattern. |
| 6 | API ID | Field identifier |
| 7 | Width | Optional, but recommended for custom tags (see Long Tags). |
| 8 | Height | Optional |
| 9 | Validation type | numbers, letters, email_address, us_phone_number, us_zip_code, us_age, alphanumeric, or custom |
| 10 | Fixed width | y / n |
| 11 | Regex pattern | Required with custom. Maximum 500 characters. |
| 12 | Error message | Required with custom. Maximum 300 characters. |
Options 9–12 above apply specifically to text fields. Other field types have their own options.
Example: Exactly three digits
The following Text Tag creates a field that accepts exactly three digits:
{{text:1:y:Code::code_field:160:30:custom:n:^\d{3}$:Enter 3 digits exactly}}
If the recipient enters a value that doesn't match the pattern, they see the error message "Enter 3 digits exactly" for that field and cannot complete the document until the value matches.
Custom validation is only supported for text fields. Using custom on a signature, initials, date, checkbox, or autofill tag results in an error.
Special Characters
Colons
Text Tag options are separated by colons (:). To include a colon in a regex pattern or error message, escape it as \:.
For example, a field requiring a time in HH:MM format:
{{text:1:y:Time::time_1:160:30:custom:n:^\d{2}\:\d{2}$:Use the format HH\:MM}}
A custom tag containing more options than expected because of an unescaped colon is rejected.
Curly braces
Curly braces used in regex patterns, such as \d{3} or [A-Z]{2}, are preserved.
However, regex patterns and error messages cannot contain {{ or }}, because these mark the beginning and end of a Text Tag.
Word processors
Turn off smart quotes and autocorrect when entering Text Tags. Some word processors automatically replace standard quotation marks with curly quotation marks, which can change the intended regex pattern.
Writing the Regex
Regex patterns are evaluated in the recipient's browser (JavaScript) and on SignWell's servers (Ruby). Use syntax supported by both environments.
- Use
^and$to anchor patterns rather than Ruby-specific\Aand\z. - Avoid Ruby-only features such as possessive quantifiers (
a++) and atomic groups ((?>...)). - Avoid patterns that can take excessive time to evaluate, such as nested repetitions like
(a+)+.
Long Tags
Custom validation tags can be longer than standard Text Tags because they include both a regex pattern and an error message.
To avoid layout issues:
- Specify the width (option 7). Without an explicit width, the field width is based on the Text Tag's size in the document. Longer tags may produce unnecessarily wide fields.
- Minimize line wrapping. Keep the tag on as few lines as practical and within the supported limits described below.
- Hide tags in the document. You can use a small font and set the text color to match the document background, as recommended for standard Text Tags.
Validation Errors
Text Tags are processed after the initial API response.
If a custom validation tag contains an error, the document moves to the Error status. The document's error message identifies the invalid tag and explains the reason.
Multiple errors for the same tag are separated by semicolons (;).
For example:
The following tags are not valid: {{text:1:y:Code::code_field:160:30:custom:n}} (custom validation needs a regex pattern; custom validation needs an error message)
Possible Error Messages
| Error message | Cause |
|---|---|
custom validation needs a regex pattern | Option 11 is missing or empty. |
custom validation needs an error message | Option 12 is missing or empty. |
the regex pattern isn't valid | Option 11 contains an invalid regular expression. |
the regex pattern is longer than 500 characters | Option 11 exceeds the maximum length. |
the error message is longer than 300 characters | Option 12 exceeds the maximum length. |
custom validation only works on text fields | Custom validation was used on a signature, initials, date, checkbox, or autofill tag. |
too many options, write a colon inside the regex or error message as \: | The regex pattern or error message contains an unescaped colon. |
the prefilled value doesn't match the regex pattern | The prefilled value in option 5 does not match the regex. |
Text Tag Length and Parser Limits
Custom validation Text Tags support:
- A maximum of 1,000 characters per tag.
- A maximum of 13 lines per tag.
- Regex patterns up to 500 characters.
- Custom error messages up to 300 characters.
Other Text Tags retain the existing limits of 100 characters and 3 lines.
Tags exceeding their applicable character or line limits are not processed. No field is created, and no validation error is displayed for the ignored tag.
Reading the Field Back
Text fields created using custom regex validation in Text Tags return the same validation data as fields created through the API's fields parameter.
The validation value differs depending on whether the field is retrieved through an API response or a template webhook.
Document and Template API Responses
Create and GET responses for documents and templates return:
validation: "custom"validation_regexvalidation_regex_error_message
Template Webhooks
Template webhook events, such as template_created and template_available, return:
validation: "custom_regex"validation_regexvalidation_regex_error_messagecustom_validation_patterncustom_validation_message
Both sets of regex properties are included in template webhook data for backward compatibility with existing integrations.
