Skip to content
  1. Blog
  2. API

How to Use Group Checkbox Fields in the BoldSign API

TL;DR: A group checkbox puts several checkbox fields under one group name, so you can set how many of them a signer must tick. The BoldSign API offers four rules: Maximum, Minimum, Absolute and Range. Our eSignature API page shows what else you can build.

Your form asks a customer to pick their top three interests from a list of 10. Or a consent form needs the signer to tick at least one box before they can finish. Without a rule, a signer can skip the boxes or tick all of them.

Group checkbox validation stops that at the signing step. This guide explains the four rules and shows a sample request in five languages.

What are group checkbox fields?

Group checkbox fields are checkboxes that share one group name. You set one rule for the group, and we check the signer’s ticks against it before they finish.

Think of a lunch menu that says “choose any two sides”. Each side has its own box, but the limit applies to the whole list. A checkbox group works the same way.

Read our guide on using checkboxes and radio buttons in BoldSign forms for a wider look.

Where does group checkbox validation help?

Any form with a choice of options can use it. Here are four common cases:

  • Surveys that ask for at least three answers out of 10.
  • Consent forms where the signer confirms each clause, such as confidentiality and terms of use.
  • Forms where the signer confirms a set number of conditions or certificates.
  • Preference lists where the signer picks exactly three options from 10.

A clear rule means you get answers you can use. You avoid chasing signers for missing choices after the document is signed.

Which validation rules can a checkbox group use?

There are four rules, and each one sets a count for the group. You pick the rule with the groupValidation property.

  • Maximum sets the most boxes a signer can tick, with maximumCount.
  • Minimum sets the fewest boxes a signer must tick, with minimumCount.
  • Absolute asks for an exact number, so minimumCount and maximumCount hold the same value.
  • Range accepts any count between minimumCount and maximumCount.

These definitions come from our developer guide on how to add group checkboxes to a document.

How do you add group checkboxes with the BoldSign API?

You add the checkboxes to the signer’s form fields and give each one a groupName. Then you add a formGroups entry that holds the rule for each group.

  1. Add each checkbox with fieldType set to CheckBox, a page number and its bounds.
  2. Give every checkbox in the same set the same groupName.
  3. Add one formGroups entry per group, with its groupNames list and groupValidation rule.
  4. Set minimumCount, maximumCount or both to match the rule.
  5. Send the request to the send document endpoint.

The sample below sends one document with two groups. The first group allows two ticks at most, and the second needs one tick or more.

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": "Alex",
      "signerOrder": 1,
      "emailAddress": "alex@example.com",
      "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: "Alex",
    signerType: SignerType.Signer,
    signerEmail: "alex@example.com",
    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": "Alex",
            "signerOrder": 1,
            "emailAddress": "alex@example.com",
            "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: "Alex",
      signerOrder: 1,
      emailAddress: "alex@example.com",
      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);
?>

The C# sample sets the rules the other way round: Minimum on the first group and Maximum on the second. Both forms are valid, so pick the one that fits your document.

What should you watch out for?

A few details decide whether the rule works as you expect:

  • Spell each group name the same way in the form fields and in formGroups.
  • For Absolute, set minimumCount and maximumCount to the same number.
  • Give the signer enough boxes to meet the rule, such as three boxes for a minimum of three.
  • Test each group in the sandbox before you send real documents.

Which BoldSign plan do you need for the API?

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 API sandbox. It needs no credit card, and its documents carry a test watermark and are deleted after 14 days. You can also try the web app with a 30-day free trial.

How do you start building with group checkboxes?

Pick the step that fits where you are:

Frequently asked questions

What is a group checkbox in BoldSign?

A group checkbox is a set of checkbox fields that share one group name. You then set one rule for the whole set, such as how many boxes the signer must tick.

What is a top API for splitting documents with checkboxes?

The BoldSign API is one option. You split the checkboxes in a document into named groups and give each group its own rule, so one form can hold several separate questions.

How do I make a signer tick at least one checkbox?

Put the checkboxes in one group and add a form group with groupValidation set to Minimum and minimumCount set to 1. The signer then has to tick one box or more.

How do I require an exact number of checkboxes?

Use the Absolute rule and set minimumCount and maximumCount to the same number. The signer has to tick exactly that many boxes in the group.

Can one document have more than one checkbox group?

Yes. Give each set of checkboxes its own group name, then add one entry per group to formGroups. Our sample request sends two groups with different rules.

What is the difference between Range and Absolute validation?

Range accepts any count between a lowest and a highest number. Absolute accepts one exact count, so its minimum and maximum are the same.

Are checkbox answers in a signed document legally binding?

Yes, when the signed document as a whole meets the electronic signature rules that apply to it. A ticked box records a choice, and we keep it in the completed document.

Can I test group checkboxes before I pay?

Yes. The free API sandbox needs no credit card. Its documents carry a test watermark and are deleted after 14 days.

Starvritsa Buhungi

Starvritsa is a Technical Assistant at BoldSign, channelling her passion into crafting top-tier content for users through meticulous documentation. She creates content across various formats, including API tutorials, help articles, and comprehensive guides.

More posts by Starvritsa Buhungi
Get started

Sign up for your free trial today!

Start free trial
  • 30-day free trial
  • No credit card required