For more complex forms or agreements, it is often necessary to cluster separate checkbox fields and apply validation rules for the number of checkboxes that must be selected. The BoldSign group checkbox functionality allows you to validate multiple checkbox fields that are contained in one group. This is really useful when you want to constrain or mandate the number of options that a signer can select.
In this blog, I’ll show you how you can apply grouped checkboxes to your BoldSign documents and make sure your users check the boxes before signing. In addition, we’ll also provide code samples that will allow you to integrate this functionality easily into your workflows.
How group checkbox validation can be applied in document signing
Surveys and Questionnaires
Group checkbox validation can be applied in surveys where users are required to select a specific number of answers. For example, in a customer satisfaction survey, you might want to enforce that users select at least three out of 10 available options. Using grouped checkboxes with validation helps you ensure that the respondents supply enough data, refining the quality and consistency of the data that’s collected.
Legal and Compliance Documents
Legal documents like NDAs or consent forms can use group checkbox validation to make sure the signer checks off important pieces. For instance, when a signer needs to verify all of the clauses related to confidentiality, legal obligations, or terms of use.
Form Selections
Grouped checkbox validation can be used when designing forms to require users to check a certain number of boxes. It is useful when the signer must confirm validated conditions or certifications.
Preference and Option Selection
Grouped checkbox validation can enforce constraints in cases where users have to choose from a fixed set of options. An example is when a user must choose exactly three options from a list of 10. This validation will make sure that the user follows the selection rule.
How to add group checkbox validation to a document using the BoldSign API
In order for group checkboxes to work, we need to apply validation to them. These validations dictate how many of the checkboxes will be selected by a signer to ensure the accuracy and consistency of the data that is collected.
The validation types for grouped checkboxes:
- Maximum: Defines the maximum number of checkboxes that can be selected.
- Minimum: Defines the minimum number of checkboxes that must be selected.
- Absolute: Indicates the number of checkboxes to be selected exactly. Both minimumCount and maximumCount should be equal.
- Range: Allows a minimum and maximum value, between which a range of checkboxes can be selected.
The following sample code snippets show how to add group checkbox field validation to a document via the BoldSign API.
curl -X 'POST' \
'https://api.boldsign.com/v1/document/send' \
-H 'accept: application/json' \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"title": "Send Document",
"files": [
"data:application/pdf;base64,JVBERi0xLjcKJcfs..."
],
"signers": [
{
"name": "David",
"signerOrder": 1,
"emailAddress": "[email protected]",
"signerType": "Signer",
"FormFields": [
{
"fieldType": "CheckBox",
"id": "check1",
"pageNumber": 1,
"bounds": {
"X": 100,
"Y": 100,
"Width": 30,
"Height": 30
},
"isRequired": true,
"groupName": "checkgroup1"
},
{
"id": "check2",
"fieldType": "CheckBox",
"pageNumber": 1,
"bounds": {
"X": 130,
"Y": 100,
"Width": 30,
"Height": 30
},
"isRequired": true,
"groupName": "checkgroup1"
},
{
"fieldType": "CheckBox",
"id": "check11",
"pageNumber": 1,
"bounds": {
"X": 300,
"Y": 300,
"Width": 30,
"Height": 30
},
"isRequired": true,
"groupName": "checkgroup2"
},
{
"id": "check21",
"fieldType": "CheckBox",
"pageNumber": 1,
"bounds": {
"X": 350,
"Y": 300,
"Width": 30,
"Height": 30
},
"isRequired": true,
"groupName": "checkgroup2"
}
]
}
],
"formGroups": [
{
"maximumCount": 2,
"groupNames": [
"checkgroup1"
],
"groupValidation": "Maximum"
},
{
"minimumCount": 1,
"groupNames": [
"checkgroup2"
],
"groupValidation": "Minimum"
}
]
}'
var apiClient = new ApiClient("https://api.boldsign.com", "{Your API key}");
var documentClient = new DocumentClient(apiClient);
var documentFilePath = new DocumentFilePath
{
ContentType = "application/pdf",
FilePath = "{Your File path}"
};
var filesToUpload = new List<IDocumentFile>
{
documentFilePath,
};
var formFields = new List<FormField>();
formFields.Add(new FormField(
name: "check1",
type: FieldType.CheckBox,
pageNumber: 1,
bounds: new Rectangle(x: 200, y: 250, width: 30, height: 30)));
formFields.Add(new FormField(
name: "check2",
type: FieldType.CheckBox,
pageNumber: 1,
bounds: new Rectangle(x: 230, y: 250, width: 30, height: 30)));
formFields.Add(new FormField(
name: "check3",
type: FieldType.CheckBox,
pageNumber: 1,
bounds: new Rectangle(x: 200, y: 450, width: 30, height: 30)));
formFields.Add(new FormField(
name: "check4",
type: FieldType.CheckBox,
pageNumber: 1,
bounds: new Rectangle(x: 230, y: 450, width: 30, height: 30)));
formFields[0].GroupName = "checkGroup1";
formFields[1].GroupName = "checkGroup1";
formFields[2].GroupName = "checkGroup2";
formFields[3].GroupName = "checkGroup2";
var signer = new DocumentSigner(
signerName: "David",
signerType: SignerType.Signer,
signerEmail: "[email protected]",
formFields: formFields);
var documentSigners = new List<DocumentSigner>()
{
signer
};
var groupNames = new List<string>() { "checkGroup1" };
var groupNames2 = new List<string>() { "checkGroup2" };
var formGroups = new List<FormGroup>()
{
new FormGroup(groupNames: groupNames, groupValidation: GroupValidation.Minimum)
{
MinimumCount = 1
},
new FormGroup(groupNames: groupNames2, groupValidation: GroupValidation.Maximum)
{
MaximumCount = 2
}
};
var sendForSign = new SendForSign()
{
Message = "please sign this",
Title = "Agreement",
Signers = documentSigners,
Files = filesToUpload,
FormGroups = formGroups
};
var documentCreated = documentClient.SendDocument(sendForSign);
import requests
url = "https://api.boldsign.com/v1/document/send"
payload = {
"title": "Send Document",
"files": ["data:application/pdf;base64,JVBERi0xLjcKJcfs..."],
"signers": [
{
"name": "David",
"signerOrder": 1,
"emailAddress": "[email protected]",
"signerType": "Signer",
"FormFields": [
{
"fieldType": "CheckBox",
"id": "check1",
"pageNumber": 1,
"bounds": {"X": 100, "Y": 100, "Width": 30, "Height": 30},
"isRequired": True,
"groupName": "checkgroup1"
},
{
"id": "check2",
"fieldType": "CheckBox",
"pageNumber": 1,
"bounds": {"X": 130, "Y": 100, "Width": 30, "Height": 30},
"isRequired": True,
"groupName": "checkgroup1"
},
{
"fieldType": "CheckBox",
"id": "check11",
"pageNumber": 1,
"bounds": {"X": 300, "Y": 300, "Width": 30, "Height": 30},
"isRequired": True,
"groupName": "checkgroup2"
},
{
"id": "check21",
"fieldType": "CheckBox",
"pageNumber": 1,
"bounds": {"X": 350, "Y": 300, "Width": 30, "Height": 30},
"isRequired": True,
"groupName": "checkgroup2"
}
]
}
],
"formGroups": [
{
"maximumCount": 2,
"groupNames": ["checkgroup1"],
"groupValidation": "Maximum"
},
{
"minimumCount": 1,
"groupNames": ["checkgroup2"],
"groupValidation": "Minimum"
}
]
}
headers = {
"accept": "application/json",
"X-API-KEY": "YOUR_API_KEY",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
const axios = require("axios");
const fs = require("fs");
const payload = {
title: "Send Document",
files: ["data:application/pdf;base64,JVBERi0xLjcKJcfs..."],
signers: [
{
name: "David",
signerOrder: 1,
emailAddress: "[email protected]",
signerType: "Signer",
FormFields: [
{
fieldType: "CheckBox",
id: "check1",
pageNumber: 1,
bounds: { X: 100, Y: 100, Width: 30, Height: 30 },
isRequired: true,
groupName: "checkgroup1",
},
{
id: "check2",
fieldType: "CheckBox",
pageNumber: 1,
bounds: { X: 130, Y: 100, Width: 30, Height: 30 },
isRequired: true,
groupName: "checkgroup1",
},
{
fieldType: "CheckBox",
id: "check11",
pageNumber: 1,
bounds: { X: 300, Y: 300, Width: 30, Height: 30 },
isRequired: true,
groupName: "checkgroup2",
},
{
id: "check21",
fieldType: "CheckBox",
pageNumber: 1,
bounds: { X: 350, Y: 300, Width: 30, Height: 30 },
isRequired: true,
groupName: "checkgroup2",
},
],
},
],
formGroups: [
{
maximumCount: 2,
groupNames: ["checkgroup1"],
groupValidation: "Maximum",
},
{
minimumCount: 1,
groupNames: ["checkgroup2"],
groupValidation: "Minimum",
},
],
};
const response = await axios.post(
"https://api.boldsign.com/v1/document/send",
payload,
{
headers: {
"Content-Type": "application/json",
accept: "application/json",
"X-API-KEY": "{your API key}",
},
}
);
console.log(response.data);
<?php
$url = 'https://api.boldsign.com/v1/document/send';
$data = array(
"title" => "Send Document",
"files" => array("data:application/pdf;base64,JVBERi0xLjcKJcfs..."),
"signers" => array(
array(
"name" => "{Signer name}",
"signerOrder" => 1,
"emailAddress" => "{Signer email}",
"signerType" => "Signer",
"FormFields" => array(
array(
"fieldType" => "CheckBox",
"id" => "check1",
"pageNumber" => 1,
"bounds" => array("X" => 100, "Y" => 100, "Width" => 30, "Height" => 30),
"isRequired" => true,
"groupName" => "checkgroup1"
),
array(
"id" => "check2",
"fieldType" => "CheckBox",
"pageNumber" => 1,
"bounds" => array("X" => 130, "Y" => 100, "Width" => 30, "Height" => 30),
"isRequired" => true,
"groupName" => "checkgroup1"
),
array(
"fieldType" => "CheckBox",
"id" => "check11",
"pageNumber" => 1,
"bounds" => array("X" => 300, "Y" => 300, "Width" => 30, "Height" => 30),
"isRequired" => true,
"groupName" => "checkgroup2"
),
array(
"id" => "check21",
"fieldType" => "CheckBox",
"pageNumber" => 1,
"bounds" => array("X" => 350, "Y" => 300, "Width" => 30, "Height" => 30),
"isRequired" => true,
"groupName" => "checkgroup2"
)
)
)
),
"formGroups" => array(
array(
"maximumCount" => 2,
"groupNames" => array("checkgroup1"),
"groupValidation" => "Maximum"
),
array(
"minimumCount" => 1,
"groupNames" => array("checkgroup2"),
"groupValidation" => "Minimum"
)
)
);
$options = array(
'http' => array(
'header' => "Content-type: application/json\r\n" .
"accept: application/json\r\n" .
"X-API-KEY: YOUR_API_KEY\r\n",
'method' => 'POST',
'content' => json_encode($data),
),
);
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === FALSE) {
// Handle error
}
print_r($result);
?>
Conclusion
Group checkbox validation in BoldSign facilitates document workflow processing by ensuring that signers fulfill certain selection requirements. Whatever you’re collecting data on (forms, surveys, or legal agreements), this feature helps the collection be more accurate and consistent. Using the BoldSign API, you can automate the validation process, so you know your document signing workflows are both efficient and compliant.
If you are not yet a BoldSign customer, try a 30-day free trial to explore how features like grouped checkboxes can simplify your document signing workflows. We value your feedback, so please share your thoughts in the comments section. If you have any questions or need more information about our services, don’t hesitate to schedule a demo or reach out to our support team through our support portal.
