Custom Regex Validation for Text Tags

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

#OptionNotes
1Field typetext or t
2Signer numberThe recipient number
3Requiredy / n
4LabelField label
5ValuePrefilled value. With custom, it must match the regex pattern.
6API IDField identifier
7WidthOptional, but recommended for custom tags (see Long Tags).
8HeightOptional
9Validation typenumbers, letters, email_address, us_phone_number, us_zip_code, us_age, alphanumeric, or custom
10Fixed widthy / n
11Regex patternRequired with custom. Maximum 500 characters.
12Error messageRequired 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 \A and \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 messageCause
custom validation needs a regex patternOption 11 is missing or empty.
custom validation needs an error messageOption 12 is missing or empty.
the regex pattern isn't validOption 11 contains an invalid regular expression.
the regex pattern is longer than 500 charactersOption 11 exceeds the maximum length.
the error message is longer than 300 charactersOption 12 exceeds the maximum length.
custom validation only works on text fieldsCustom 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 patternThe 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_regex
  • validation_regex_error_message

Template Webhooks

Template webhook events, such as template_created and template_available, return:

  • validation: "custom_regex"
  • validation_regex
  • validation_regex_error_message
  • custom_validation_pattern
  • custom_validation_message

Both sets of regex properties are included in template webhook data for backward compatibility with existing integrations.