Conditional fields

You can reveal specific tabs (also known as fields) to signers when specified conditions are met by making them conditional fields. For example, you can reveal conditional fields for a user to input data after they select a checkbox, or require a user to provide additional data after entering text in a text field.

Dependent conditional fields (revealed when user input has been provided to the parent) can be of any tab type. Which types you are allowed to use for Parent conditional fields differ between the UI and the API. In the UI, you can use only the following tab types to trigger revealing conditional fields:

Checkbox
Radio button
Dropdown
Text

In the API, you can use any field type as a Parent field if you set its optional property to true. For example, the following initialHereTab definition could be used as a conditional parent, because the optional property is set to true:

"initialHereTabs": [
    {
        "optional" : "true",
        "tabLabel": "exampleParent",
        "xPosition": "300",
        "yPosition": "300",
        "pageNumber": "1",
        "documentId": "1"
    }
]

Configuring parent (trigger) tabs

To set the tab to be used as the trigger for a conditional field, you configure properties on the conditional field itself. When you create a conditional field, you specify a conditionalParentLabel tab property and a conditionalParentValue property.

conditionalParentLabel is the trigger tab whose state can reveal the conditional field
conditionalParentValue is the value of the trigger tab needed to reveal the conditional field

If the conditional field is a Checkbox tab or button from a Radio Group tab, use on as the value to show that the parent tab is active.

Radio Groups as conditional parents

To reference a Radio Group as a conditional parent, the value of the conditionalParentLabel property should match the groupName property of the radio group tab and the conditionalParentValue property value should match the corresponding radio button’s value property.

Text tabs as conditional parents

Text tabs can be set as conditional parents to reveal conditional fields either when a specific string is input, or when any text is input.

For a specific string, enter the specific required value in conditionalParentValue
For any text input, set conditionalParentValue to ##ANY##

Example conditional field definition

The following example uses conditional fields to reveal a Sign Here tab after a Checkbox tab is selected:

{
    "status": "sent",
    "emailSubject": "Conditional Tabs Example",
    "documents": [{
        "documentId": "1",
        "name": "contract.pdf",
        "documentBase64": "base64 encoded string..."
    }],
    "recipients": {
        "signers": [{
            "email": "smason@email.com",
            "name": "Sara Mason",
            "recipientId": "1",
            "tabs": {
                "checkboxTabs": [{
                    "tabLabel": "sampleCheckbox",
                    ...
                }],
                "signHereTabs": [{
                    "conditionalParentLabel": "sampleCheckbox",
                    "conditionalParentValue": "on",
                    "xPosition": "80",
                    "yPosition": "40",
                    "documentId": "1",
                    "pageNumber": "1"
                }]
            }
        }]
    }
}