How to Create Checkbox Groups

Checkbox Groups (cbg) allow you to group multiple individual checkboxes (chk) together. This is useful when you want to enforce validation rules across a set of options, such as "select at least one" or "select no more than three".

Overview

Creating a checkbox group involves two main components:

1. A Parent Checkbox Group field: A field with kind: "cbg". This field holds the validation rules (v_min, v_max) but is not visible on the document.
2. Child Checkbox fields: Multiple fields with kind: "chk" that reference the parent group using the related_to_key property.

Validation Rules

You can use the following properties on the parent cbg field to control selection:

• v_min: The minimum number of checkboxes that must be selected.
• v_max: The maximum number of checkboxes that can be selected.

For example, to create a "Select exactly 2" rule, set both v_min and v_max to 2.

Implementation Example

The following example shows how to create an envelope with a checkbox group containing three options, requiring the signer to select between 1 and 2 of them.

Python

import requests

API_KEY = "your-api-key"
API_URL = "https://api.blueink.com/api/v2/bundles/"

payload = {
    "label": "Checkbox Group Example",
    "packets": [
        {
            "name": "John Doe",
            "email": "[email protected]",
            "key": "signer-1"
        }
    ],
    "documents": [
        {
            "key": "doc-1",
            "file_url": "https://example.com/form.pdf",
            "fields": [
                {
                    "key": "color-group",
                    "kind": "cbg",
                    "label": "Pick 1 or 2 colors",
                    "v_min": 1,
                    "v_max": 2,
                    "editors": ["signer-1"],
                    "page": 1, "x": 0, "y": 0, "w": 0, "h": 0
                },
                {
                    "key": "color-red",
                    "kind": "chk",
                    "label": "Red",
                    "related_to_key": "color-group",
                    "editors": ["signer-1"],
                    "page": 1, "x": 10, "y": 10, "w": 5, "h": 5
                },
                {
                    "key": "color-blue",
                    "kind": "chk",
                    "label": "Blue",
                    "related_to_key": "color-group",
                    "editors": ["signer-1"],
                    "page": 1, "x": 10, "y": 20, "w": 5, "h": 5
                },
                {
                    "key": "color-green",
                    "kind": "chk",
                    "label": "Green",
                    "related_to_key": "color-group",
                    "editors": ["signer-1"],
                    "page": 1, "x": 10, "y": 30, "w": 5, "h": 5
                }
            ]
        }
    ]
}

headers = {
    "Authorization": f"Token {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(API_URL, json=payload, headers=headers)
print(response.json())

JavaScript

const axios = require('axios');

const API_KEY = 'your-api-key';
const API_URL = 'https://api.blueink.com/api/v2/bundles/';

const payload = {
  label: 'Checkbox Group Example',
  packets: [
    {
      name: 'John Doe',
      email: '[email protected]',
      key: 'signer-1'
    }
  ],
  documents: [
    {
      key: 'doc-1',
      file_url: 'https://example.com/form.pdf',
      fields: [
        {
          key: 'color-group',
          kind: 'cbg',
          label: 'Pick 1 or 2 colors',
          v_min: 1,
          v_max: 2,
          editors: ['signer-1'],
          page: 1, x: 0, y: 0, w: 0, h: 0
        },
        {
          key: 'color-red',
          kind: 'chk',
          label: 'Red',
          related_to_key: 'color-group',
          editors: ['signer-1'],
          page: 1, x: 10, y: 10, w: 5, h: 5
        },
        {
          key: 'color-blue',
          kind: 'chk',
          label: 'Blue',
          related_to_key: 'color-group',
          editors: ['signer-1'],
          page: 1, x: 10, y: 20, w: 5, h: 5
        },
        {
          key: 'color-green',
          kind: 'chk',
          label: 'Green',
          related_to_key: 'color-group',
          editors: ['signer-1'],
          page: 1, x: 10, y: 30, w: 5, h: 5
        }
      ]
    }
  ]
};

axios.post(API_URL, payload, {
  headers: {
    'Authorization': `Token ${API_KEY}`,
    'Content-Type': 'application/json'
  }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

PHP

<?php

use Blueink\ClientSDK\Client;

$client = new Client("your-api-key");

$payload = [
    "label" => "Checkbox Group Example",
    "packets" => [
        [
            "name" => "John Doe",
            "email" => "[email protected]",
            "key" => "signer-1"
        ]
    ],
    "documents" => [
        [
            "key" => "doc-1",
            "file_url" => "https://example.com/form.pdf",
            "fields" => [
                [
                    "key" => "color-group",
                    "kind" => "cbg",
                    "label" => "Pick 1 or 2 colors",
                    "v_min" => 1,
                    "v_max" => 2,
                    "editors" => ["signer-1"],
                    "page" => 1, "x" => 0, "y" => 0, "w" => 0, "h" => 0
                ],
                [
                    "key" => "color-red",
                    "kind" => "chk",
                    "label" => "Red",
                    "related_to_key" => "color-group",
                    "editors" => ["signer-1"],
                    "page" => 1, "x" => 10, "y" => 10, "w" => 5, "h" => 5
                ],
                [
                    "key" => "color-blue",
                    "kind" => "chk",
                    "label" => "Blue",
                    "related_to_key" => "color-group",
                    "editors" => ["signer-1"],
                    "page" => 1, "x" => 10, "y" => 20, "w" => 5, "h" => 5
                ],
                [
                    "key" => "color-green",
                    "kind" => "chk",
                    "label" => "Green",
                    "related_to_key" => "color-group",
                    "editors" => ["signer-1"],
                    "page" => 1, "x" => 10, "y" => 30, "w" => 5, "h" => 5
                ]
            ]
        ]
    ]
];

$response = $client->bundles->create($payload);

if ($response->status === 201) {
    print_r($response->data);
} else {
    echo "Error: " . $response->error;
}

Important Notes

• Coordinate Requirements: Although the parent cbg field is not visible on the document, the API still requires coordinates (x, y, w, h) and a page number. You can safely set these to 0.
• Unique Keys: All field keys (including both the parent group and the checkboxes) must be unique within the document.
• Reference Accuracy: Ensure that the related_to_key on each checkbox exactly matches the key of the parent group field.