# 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

```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": "john.doe@example.com",
            "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

```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: 'john.doe@example.com',
      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
<?php

use Blueink\ClientSDK\Client;

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

$payload = [
    "label" => "Checkbox Group Example",
    "packets" => [
        [
            "name" => "John Doe",
            "email" => "john.doe@example.com",
            "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.