TL;DR: Regex validation lets a text box accept only values that match a pattern you set. In the BoldSign API, you set
validationTypetoCustomRegex, add the pattern and add a message for signers who type something else. Our eSignature API page shows what else the API can do.
You send a form that asks for an employee ID, and one signer types a name in the box. Someone has to spot the mistake, chase the signer and send the document again.
Validation stops that at the source. This guide shows how to add a regular expression (regex) rule to a text box with the BoldSign API, with samples in five languages.
What is regex validation in an eSignature document?
Regex validation checks what a signer types against a pattern before the field counts as complete. Values that miss the pattern are held back, and the signer sees your message.
Think of a parcel form that only accepts a postcode in the right shape. The clerk does not check that the address exists, only that the code looks right. A regex works the same way: it checks the shape of the value, not whether it is true.
Our developer guide covers regex validation for text tags, and the same idea applies to fields you place by position.
Which validation types does the BoldSign API support?
A text box can use one of five validation types. Four of them check the value, and the fifth turns checking off.
NumbersOnlyaccepts digits only.EmailAddressaccepts a value in email format.Currencyaccepts an amount of money.CustomRegexaccepts values that match your own pattern.Noneaccepts any text and is the default.
Pick CustomRegex when the built-in types are too broad, such as for an order number with a fixed shape.
How do you add regex validation to a text box with the BoldSign API?
You add three properties to a text box in the formFields list of your send request. Our help article on how to add validation to the text box form field lists every option.
- Add a form field with
fieldTypeset toTextBox, a page number and bounds. - Set
validationTypetoCustomRegex. - Put your pattern in
validationCustomRegex. - Put the message signers see in
validationCustomRegexMessage. - Assign the field to a signer and send the document.
What does a regex validation request look like in code?
Each sample below sends a document with one required text box. The pattern ^\d+$ accepts digits only, and the message reads “Enter numbers only”.
curl -X 'POST' \
'https://api.boldsign.com/v1/document/send' \
-H 'accept: application/json' \
-H 'X-API-KEY: {API key}' \
-H 'Content-Type: multipart/form-data' \
-F 'Message={your message}' \
-F 'Signers={
"name": "Alex",
"emailAddress": "alex@example.com",
"privateMessage": "sign",
"authenticationType": "None",
"deliveryMode": "Email",
"signerType": "Signer",
"formFields": [
{
"id": "textbox1",
"name": "textbox1",
"fieldType": "Textbox",
"pageNumber": 1,
"bounds": {
"x": 140,
"y": 140,
"width": 82,
"height": 32
},
"isRequired": true,
"validationType": "CustomRegex",
"validationCustomRegex": "^\\d+$",
"validationCustomRegexMessage": "Enter numbers only"
}
]
}' \
-F 'Files=@{Your file path};type=application/pdf' \
-F 'Title={Document title}'
var apiClient = new ApiClient("https://api.boldsign.com", "{your API key}");
var documentClient = new DocumentClient(apiClient);
var documentFilePath = new DocumentFilePath
{
ContentType = "application/pdf",
FilePath = "{file path}",
};
var filesToUpload = new List<IDocumentFile>
{
documentFilePath,
};
var textBoxField = new FormField(
id: "textbox1",
isRequired: true,
type: FieldType.TextBox,
pageNumber: 1,
bounds: new Rectangle(x: 100, y: 100, width: 100, height: 50),
validationType: ValidationType.CustomRegex,
validationCustomRegex: "^\\d+$",
validationCustomRegexMessage: "Enter numbers only");
var formFieldCollections = new List<FormField>()
{
textBoxField
};
var signer = new DocumentSigner(
signerName: "David",
signerType: SignerType.Signer,
signerEmail: "alex@example.com",
formFields: formFieldCollections,
locale: Locales.EN);
var documentSigners = new List<DocumentSigner>()
{
signer
};
var sendForSign = new SendForSign()
{
Message = "please sign this",
Title = "Agreement",
Signers = documentSigners,
Files = filesToUpload,
};
var documentCreated = documentClient.SendDocument(sendForSign);
import requests
import json
url = "https://api.boldsign.com/v1/document/send"
signer_data = {
"name": "Alex",
"emailAddress": "alex@example.com",
"signerType": "Signer",
"signerRole": "Signer",
"formFields": [
{
"id": "textbox1",
"name": "textbox1",
"fieldType": "TextBox",
"pageNumber": 1,
"bounds": {"x": 100, "y": 100, "width": 200, "height": 200},
"isRequired": True,
"validationType": "CustomRegex",
"validationCustomRegex": "^\\d+$",
"validationCustomRegexMessage": "Enter numbers only",
}
],
"locale": "EN",
}
payload = {
"Signers": json.dumps(signer_data),
"Title": "Agreement",
}
files = [("Files", ("{file name}", open("{file path}", "rb"), "application/pdf"))]
headers = {"accept": "application/json", "X-API-KEY": "{Your API key}"}
response = requests.post(url, headers=headers, data=payload, files=files)
print(response.text)
const axios = require("axios");
const FormData = require("form-data");
const fs = require("fs");
let data = new FormData();
data.append(
"Signers",
'{\r\n "name": "Alex",\r\n "emailAddress": "alex@example.com",\r\n "signerType": "Signer", \r\n "signerRole": "Signer",\r\n "formFields": [\r\n {\r\n "id": "textbox1",\r\n "name": "textbox1",\r\n "fieldType": "TextBox",\r\n "pageNumber": 1,\r\n "bounds": {\r\n "x": 100,\r\n "y": 100,\r\n "width": 125,\r\n "height": 25\r\n },\r\n "isRequired": true,\r\n "validationType":"CustomRegex",\r\n "validationCustomRegex":"^\\\\d+$",\r\n "validationCustomRegexMessage":"Enter numbers only"\r\n }\r\n ],\r\n "locale": "EN"\r\n}',
);
data.append("Files", fs.createReadStream("{you file path}"));
data.append("Title", "Node JS validation");
let config = {
method: "post",
maxBodyLength: Infinity,
url: "https://api.boldsign.com/v1/document/send",
headers: {
"accept": "application/json",
"X-API-KEY": "{your api key}",
...data.getHeaders(),
},
data: data,
};
axios
.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
<?php
require_once "vendor/autoload.php";
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;
use \GuzzleHttp\Psr7\Utils;
$client = new GuzzleHttp\Client();
$headers = [
'accept' => 'application/json',
'X-API-KEY' => '{your Api Key}'
];
$options = [
'multipart' => [
[
'name' => 'Message',
'contents' => 'please sign the document'
],
[
'name' => 'Signers',
'contents' => '{
"name": "Alex",
"emailAddress": "alex@example.com",
"signerType": "Signer",
"formFields": [
{
"id": "textbox1",
"name": "textbox1",
"fieldType": "TextBox",
"pageNumber": 1,
"bounds": {
"x": 50,
"y": 50,
"width": 1,
"height": 1
},
"isRequired": true,
"validationType": "CustomRegex",
"validationCustomRegex": "^\\\\d+$",
"validationCustomRegexMessage": "Enter number only"
}
],
"locale": "EN"
}'
],
[
'name' => 'Files',
'contents' => Utils::tryFopen('{file path}', 'r'),
'filename' => '{file name}',
'headers' => [
'Content-Type' => 'application/pdf'
]
],
[
'name' => 'Title',
'contents' => 'Autoreminder'
],
]
];
$request = new Request('POST', 'https://api.boldsign.com/v1/document/send', $headers);
$res = $client->sendAsync($request, $options)->wait();
echo $res->getBody();
How do you add regex validation with text tags?
Text tags place fields from markers typed in the document, so you skip the coordinates. A text tag definition can carry a validation object with a type, a regex and a regex message.
Our post on how to add document fields with text tags explains the tag syntax. For other ways to place fields, read our guide to adding form fields with the API.
Which regex patterns work for common form fields?
Start with a pattern that matches the whole value, from ^ at the start to $ at the end. Without both anchors, a value with extra text around a match can still pass.
^\d+$accepts one or more digits.^\d{5}(-\d{4})?$accepts a five-digit US postal code with an optional four-digit extension.^\d{3}-\d{3}-\d{4}$accepts a US phone number written as 555-123-4567.^\d{2}/\d{2}/\d{4}$accepts a date written as 12/31/2026.
The date pattern checks the shape only, so 99/99/2026 would also pass. Add a date field when you need a real calendar date.
What should you check before you go live?
Most regex problems come from escaping, not from the pattern itself. Test each rule with values that should pass and values that should fail.
- Write each backslash twice inside a JSON string, so
\dbecomes\\d. - Double it again when that JSON sits inside a string in your code.
- Name the expected format in your message, such as “Enter 5 digits”.
- Mark the field as required when an empty value should also be stopped.
Which BoldSign API plan do you need, and what does it cost?
Live API requests need the Enterprise API plan, from $30 a month with 40 envelopes, as listed on the BoldSign pricing page in November 2026. Each extra envelope costs $0.75, and prices are in USD.
To build and test first, use the free sandbox. It needs no credit card, and its documents carry a test watermark and are deleted after 14 days. To try the web app instead, start a 30-day free trial of BoldSign.
Where do you go next with regex validation?
Try one pattern on a sample document before you add it to your app.
- Create a free API sandbox account and send your first validated text box.
- Book a demo to see how validation fits your documents.
- Visit our support portal with a question about your setup.
Frequently asked questions
What is regex validation in an eSignature document?
It is a pattern check on a text box. The signer can only finish the field when the typed value matches the pattern you set, such as digits only.
Which form fields support regex validation in BoldSign?
Text box fields. Our API reference describes validation as a setting of the text box form field, so place a text box for any value you want to check.
What happens when a signer enters a value that does not match?
The signer sees the message you set in validationCustomRegexMessage. A short message that names the expected format, such as Enter numbers only, helps them fix it quickly.
Do I need custom regex for numbers or email addresses?
Not always. The NumbersOnly, EmailAddress and Currency types cover those cases. Choose CustomRegex for formats they miss, such as an order number or postal code.
Why does my regex pattern fail in the API request?
The backslashes are often the cause. Each backslash in the pattern must be written twice inside a JSON string, and again inside a code string that holds that JSON.
Can I add validation with text tags instead of coordinates?
Yes. A text tag definition can carry a validation object with a type, a regex and a regex message, so the field and its rule come from the document itself.
Can I test regex validation without paying?
Yes. The free API sandbox needs no credit card. Its documents carry a test watermark and are deleted after 14 days.
How much does the BoldSign API cost?
The Enterprise API plan starts at $30 a month with 40 envelopes, and each extra envelope costs $0.75. Prices are in USD.