Skip to main content

Field Groups (Radio & Checkbox Grouping)

Field groups let you link multiple checkbox or radio button tags together so they behave as a single logical control during signing. A checkbox group can enforce minimum/maximum selections; a radio group enforces mutual exclusion (exactly one selection). Groups are defined at the document level and reference their member tags by tagId.

Note: Field grouping requires the enableFieldGrouping feature to be enabled for your organization. Contact eSign360 support if you receive a 400 Bad Request stating the feature is not enabled.

When to Use​

Use field groups when you need:

  • Checkbox groups — "select at least 1", "select up to 2", or "select exactly N" of several checkboxes.
  • Radio groups — a set of options where the signer may pick only one (selecting one clears the others).

Group validation is enforced automatically in the signing experience — the signer cannot exceed a group's maximum, and submission is blocked until each group's minimum is satisfied.

Where Field Groups Are Accepted​

The fieldGroups array is accepted on each document in the request body of:

  • POST /transactions — when creating a transaction with document tags.
  • PUT /transactions/{id} — when updating a transaction's documents/tags.

The fieldGroups Schema​

Each document may include a fieldGroups array (max 50 groups per document). Each group object:

FieldTypeRequiredDefaultDescription
groupIdstringNoauto-generatedYour identifier for the group. Must be unique within the document.
namestringYes—Human-readable group name shown in signer hover hints.
typestringYes—checkBox or radioButton. All member tags must be of the matching tag type.
memberTagIdsstring[]Yes—The tagId values of the member tags. Min 2, max 30. All members must share the same type and the same signerId.
minSelectionsnumberNo0Minimum selections required (0 = no minimum). Ignored for radioButton (forced to 1).
maxSelectionsnumberNo0Maximum selections allowed (0 = unlimited). Ignored for radioButton (forced to 1).
validationModestringNoflexiblestrict or flexible — controls how conditionally-hidden members affect validation.

Tag type mapping — member tags must use these types:

Group typeMember tag type
checkBoxCHECKHERETAGTEMPLATEANNOTATION
radioButtonRADIOBUTTONTAGTEMPLATEANNOTATION

Requirements​

  1. Add a unique tagId (UUID) to each tag you want to group.
  2. All members of a group must share the same signerId.
  3. A tag may belong to only one group.

Example — Checkbox Group​

A document with two checkbox tags grouped so the signer must check 1 or 2 of them:

{
  "documents": [
    {
      "StoragePath": "your-storage-path/Document.pdf",
      "title": "Consent Form",
      "order": 0,
      "visible": true,
      "readOnly": false,
      "tags": [
        {
          "tagId": "c1a2b3c4-0000-4000-a000-000000000001",
          "x": 50, "y": 200, "width": 20, "height": 20,
          "type": "CHECKHERETAGTEMPLATEANNOTATION",
          "signerId": "8500caa1-eb70-4614-a9a1-020be63e67ad",
          "page": 0, "required": false
        },
        {
          "tagId": "c1a2b3c4-0000-4000-a000-000000000002",
          "x": 50, "y": 240, "width": 20, "height": 20,
          "type": "CHECKHERETAGTEMPLATEANNOTATION",
          "signerId": "8500caa1-eb70-4614-a9a1-020be63e67ad",
          "page": 0, "required": false
        }
      ],
      "fieldGroups": [
        {
          "name": "Payment Options",
          "type": "checkBox",
          "memberTagIds": [
            "c1a2b3c4-0000-4000-a000-000000000001",
            "c1a2b3c4-0000-4000-a000-000000000002"
          ],
          "minSelections": 1,
          "maxSelections": 2
        }
      ]
    }
  ]
}

Example — Radio Group​

A document with two radio button tags grouped so the signer picks exactly one:

{
  "fieldGroups": [
    {
      "name": "Choose One",
      "type": "radioButton",
      "memberTagIds": [
        "d2b3c4d5-0000-4000-a000-000000000001",
        "d2b3c4d5-0000-4000-a000-000000000002"
      ]
    }
  ]
}

For radio groups, omit minSelections/maxSelections — the API enforces exactly one selection automatically.

Validation Rules​

  • Max 50 groups per document.
  • Each group must have 2 to 30 members.
  • Every memberTagId must match an existing tag's tagId in the same document.
  • All members must be of the group's tag type (checkBox → CHECKHERETAGTEMPLATEANNOTATION, radioButton → RADIOBUTTONTAGTEMPLATEANNOTATION).
  • All members must belong to the same signer (signerId).
  • A tag may belong to only one group.
  • radioButton groups must not set minSelections/maxSelections to anything other than 1.
  • For checkBox groups, minSelections must not exceed maxSelections, and neither may exceed the member count.

Error Responses​

StatusReason
400 Bad RequestThe enableFieldGrouping feature is not enabled for your organization, or a validation rule above was violated (see the detail field for the specific message).
401 UnauthorizedInvalid or expired Bearer token.

Example validation error:

{
  "detail": "Group 1 (\"Payment Options\"): all members must belong to the same signer.",
  "error": "enl-api-400",
  "message": "Bad request. Validation error.",
  "help": "https://integration.esign360.io/docs/troubleshooting/enl-api-400"
}

Testing Field Groups Quickly​

Use the test transaction endpoint with the fieldGroups query parameter to auto-generate a payload (and transaction) with field groups already configured:

  • GET /transactions/test?fieldGroups=checkbox — one checkbox group.
  • GET /transactions/test?fieldGroups=radio — one radio group.
  • GET /transactions/test?fieldGroups=both — one checkbox group and one radio group in the same document.

Add &return_payload=true to inspect the generated request body without creating a transaction.

Additional Resources​

If you need further assistance or have questions, feel free to reach out to our support team.