TL;DR: Conditional fields show or hide a form field based on a signer’s choice in a checkbox, radio button or dropdown. With the BoldSign eSignature API, you add a
conditionalRuleslist to the field the signer picks, and each rule names the field to show. The examples below cover all three field types.
Picture a sales contract with two ways to pay. A customer who picks monthly billing needs to sign one clause. A customer who picks yearly billing needs to initial a different one.
Without conditional fields, both signers see every field and must work out which ones apply. With them, the document shows only the fields that match each choice. This guide shows how to build that with our API, one field type at a time.
What are conditional fields in an eSignature document?
A conditional field is a form field that appears only after a signer makes a certain choice. Other fields stay hidden, so the signer fills in only what applies.
Paper forms do this with a line such as “If you answered yes, complete section B.” The reader has to follow the instruction. A conditional field follows it for them, so nobody fills in the wrong section.
Which e-signature API platforms support conditional logic and calculation fields for dynamic contract pricing?
The BoldSign API supports both. Conditional rules work on checkbox, radio button and dropdown fields, and the send document reference also lists a Formula field type.
Our send document reference marks the Formula field as beta. You set its calculation in FormulaFieldSettings, so a total can update as the signer enters numbers. Our guide to formula fields in the BoldSign API walks through it.
Check both features in any API’s reference before you compare platforms. A pricing contract often needs a choice and a sum in the same document.
How do conditional rules work in the BoldSign API?
You add a conditionalRules list to the field the signer clicks or picks. Each rule names the field to show in fieldId and says which choice shows it.
Checkbox and radio button rules test isChecked, set to true or false. Dropdown rules test value, which must match one of the dropdownOptions.
Our developer guide on how to create conditional fields has each example in several programming languages.
How do you show a field based on a radio button choice?
Give two or more radio buttons the same groupName so the signer can pick one of them. Then add a rule to each button that names the field it shows.
Radio buttons suit choices such as monthly or yearly billing. The request below sends one document to a signer named David.
curl -X POST \
'https://api.boldsign.com/v1/document/send' \
-H 'accept: application/json' \
-H 'X-API-KEY: {Your API key}' \
-H 'Content-Type: multipart/form-data' \
-F 'Signers={
"name": "David",
"emailAddress": "david@cubeflakes.com",
"signerType": "Signer",
"formFields": [
{
"id": "Signature1",
"name": "Signature1",
"fieldType": "Signature",
"pageNumber": 1,
"bounds": {
"x": 140,
"y": 190,
"width": 82,
"height": 32
},
"isRequired": false
},
{
"id": "Initial1",
"name": "Initial",
"fieldType": "Initial",
"pageNumber": 1,
"bounds": {
"x": 340,
"y": 190,
"width": 82,
"height": 32
},
"isRequired": false
},
{
"id": "RadioButton1",
"name": "RadioButton",
"fieldType": "RadioButton",
"groupName": "ConditionalLogic",
"pageNumber": 1,
"bounds": {
"x": 340,
"y": 390,
"width": 20,
"height": 20
},
"value": "off",
"conditionalRules": [
{
"fieldId": "Signature1",
"isChecked": true
}
],
"isRequired": false
},
{
"id": "Radiobutton2",
"name": "RadioButton",
"fieldType": "RadioButton",
"groupName": "ConditionalLogic",
"pageNumber": 1,
"bounds": {
"x": 140,
"y": 590,
"width": 20,
"height": 20
},
"value": "off",
"conditionalRules": [
{
"fieldId": "Initial1",
"isChecked": true
}
],
"isRequired": false
}
],
"language": 1
}' \
-F 'Files=@{Your file path}' \
-F 'Title={Your document title}'
Both radio buttons share the group ConditionalLogic. Picking the first button shows the Signature field. Picking the second shows the Initial field.
How do you show a field based on a checkbox?
Add rules to the checkbox for the checked state, the cleared state, or both. A single checkbox can then switch between two fields.
Checkboxes suit yes or no questions, such as whether the customer wants an add-on service.
curl -X POST \
'https://api.boldsign.com/v1/document/send' \
-H 'accept: application/json' \
-H 'X-API-KEY: {Your API key}' \
-H 'Content-Type: multipart/form-data' \
-F 'Signers={
"name": "David",
"emailAddress": "david@cubeflakes.com",
"signerOrder": 0,
"signerType": "Signer",
"formFields": [
{
"id": "Signature1",
"name": "Signature1",
"fieldType": "Signature",
"pageNumber": 1,
"bounds": {
"x": 140,
"y": 190,
"width": 82,
"height": 32
},
"isRequired": false
},
{
"id": "Initial1",
"name": "Initial",
"fieldType": "Initial",
"pageNumber": 1,
"bounds": {
"x": 340,
"y": 190,
"width": 82,
"height": 32
},
"isRequired": false
},
{
"id": "Checkbox1",
"name": "Checkbox",
"fieldType": "Checkbox",
"pageNumber": 1,
"bounds": {
"x": 340,
"y": 390,
"width": 20,
"height": 20
},
"value": "off",
"conditionalRules": [
{
"fieldId": "Signature1",
"isChecked": true
},
{
"fieldId": "Initial1",
"isChecked": false
}
],
"isRequired": false
}
],
"language": 1
}' \
-F 'Files=@{Your file path}' \
-F 'Title={Your document title}'
This checkbox has two rules. A checked box shows the Signature field. A cleared box shows the Initial field instead.
How do you show a field based on a dropdown option?
List the options in dropdownOptions, then add one rule for each option that should show a field. Each rule’s value must match an option exactly.
A dropdown keeps a long list of choices in a small space, such as a list of service tiers.
curl -X POST \
'https://api.boldsign.com/v1/document/send' \
-H 'accept: application/json' \
-H 'X-API-KEY: {Your API key}' \
-H 'Content-Type: multipart/form-data' \
-F 'Signers={
"name": "David",
"emailAddress": "david@cubeflakes.com",
"signerOrder": 0,
"signerType": "Signer",
"formFields": [
{
"id": "Signature1",
"name": "Signature1",
"fieldType": "Signature",
"pageNumber": 1,
"bounds": {
"x": 140,
"y": 190,
"width": 82,
"height": 32
},
"isRequired": false
},
{
"id": "Initial1",
"name": "Initial",
"fieldType": "Initial",
"pageNumber": 1,
"bounds": {
"x": 340,
"y": 190,
"width": 82,
"height": 32
},
"isRequired": false
},
{
"id": "Dropdown1",
"name": "Dropdown",
"fieldType": "Dropdown",
"pageNumber": 1,
"bounds": {
"x": 340,
"y": 390,
"width": 20,
"height": 20
},
"dropdownOptions": [
"1",
"2"
],
"value": "1",
"conditionalRules": [
{
"fieldId": "Signature1",
"value": "1"
},
{
"fieldId": "Initial1",
"value": "2"
}
],
"isRequired": false
}
],
"language": 1
}' \
-F 'Files=@{Your file path}' \
-F 'Title={Your document title}'
The dropdown offers two options, “1” and “2”. Option “1” shows the Signature field, and option “2” shows the Initial field.
What should you check before you send a document with conditional fields?
Small mismatches in the request are the usual cause of a field that never appears. Run through these points before you send:
- Give every field a unique
id, and use that exactidin each rule’sfieldId. - Use the same
groupNamefor radio buttons that belong together. - Match each dropdown rule’s
valueto an entry indropdownOptions. - Decide whether each shown field should be required, then set
isRequired.
Send a test document from the sandbox and sign it yourself to see each choice work. Our support team can look at a request that does not behave as you expect.
Which plan do you need for conditional fields, and what does the API cost?
Our pricing page lists conditional fields on every plan, including the free Essential plan. You can start a 30-day free trial to try them in the web app.
Sending live documents through the BoldSign API needs the Enterprise API plan. It starts at $30 a month and includes 40 envelopes, with extra envelopes at $0.75 each. Prices are in USD.
You can build and test first in a free API sandbox, with no credit card. Sandbox documents carry a “This is a test document” watermark, and we delete them after 14 days.
Where do you go next with conditional fields?
Pick the step that fits where your project is today.
- Create a free API sandbox account and send the radio button example to yourself.
- Book a demo to see conditional fields set up for your own contracts.
- Read how to use checkboxes and radio buttons in BoldSign forms.
Frequently asked questions
What is a conditional field in an eSignature document?
A conditional field appears only when a signer makes a certain choice in another field. Signers see the fields that apply to them and skip the rest.
Which form fields can control a conditional rule in BoldSign?
Checkbox, radio button and dropdown fields can control conditional rules. The field they show can be another type, such as a signature or initial field.
Where do I put the conditionalRules property in an API request?
Put it on the field the signer clicks or picks, such as the checkbox. Each rule names the field to show in fieldId.
Can one checkbox show different fields when checked and cleared?
Yes. Add two rules to the checkbox: one with isChecked set to true and one set to false. Each rule points at a different field.
Can the BoldSign API calculate a price inside a contract?
Yes. The send document reference lists a Formula field type, marked as beta, set up with FormulaFieldSettings. It can add, subtract, multiply and divide values from number fields.
Are conditional fields included on the free BoldSign plan?
Yes. Our pricing page lists conditional fields on every plan, including the free Essential plan. Sending live documents through the API needs the Enterprise API plan.
Can I test conditional fields without paying?
Yes. A free API sandbox account needs no credit card. Sandbox documents carry a test watermark, and we delete them after 14 days.
Which programming languages have conditional field examples?
Our developer guide shows the same three examples in several languages, including C#, Python, Java and JavaScript. Each one sends a document with signature and initial fields.