This walkthrough will help you use Logic Jumps when you're creating or updating a form with the Create API.
If you're not familiar with Typeform's Logic Jump concept, this Help Center article is a great introduction to the basics. Some Logic Jump capabilities rely on Hidden Fields, so it's a good idea to get to know Hidden Fields too.
Here's an example Logic Jump:
{
"logic": [
{
"type": "field",
"ref": "ref_trigger_field",
"actions": [
{
"action": "jump",
"details": {
"to": {
"type": "field",
"value": "ref_field_leads_to"
}
},
"condition": {
"op": "equal",
"vars": [
{
"type": "field",
"value": "ref_another_field"
},
{
"type": "constant",
"value": 10
}
]
}
}
]
}
]
}The three main parts of this Logic Jump are the type and ref definitions, the to object, and the condition object. Here's how they work together in a Logic Jump:
type and ref definitions identify which field triggers the Logic Jump.to object identifies which field or screen the Logic Jump leads to.condition object sets the conditions for executing the Logic Jump.Let's look at each of the three parts in detail.
type and ref definitionsThe type and ref definitions identify the field that triggers the Logic Jump. This part answers the question, "Where from?"
Logic Jumps can be triggered by the answer to a question or by a hidden field value. You can jump from a field based on an answer or jump to a field or skip fields based on a Hidden Field value. Both types of Logic Jumps must include the actions array, which will contain the other two parts of the Logic Jump (the to and condition objects).
A Logic Jump triggered by the answer to a question includes type and ref definitions, in addition to the actions array:
{
"type": "field",
"ref": "ref_trigger_field",
"actions": [...]
}A Logic Jump triggered by a Hidden Field value only includes a type definition and the actions array:
{
"type": "hidden",
"actions": [...]
}Here's a description of each element in the type and ref definitions:
| Element | Type | Description | Required? |
|---|---|---|---|
| type | string | Identifies which Logic Jump "from" option you are using. Valid values are field and hidden. | Required |
| ref | string | Unique ID you will use to refer to this Logic Jump. Must be less than 255 characters and in valid regular expression format ^[a-zA-Z0-9_-]+$. | Required for field Logic Jumps. Not used for hidden Logic Jumps. |
| actions | array of objects | Array of objects that define the Logic Jump's behavior. | Required |
NOTE: Logic Jump definitions are unique per triggering field.
Per form, there should be at most one Logic Jump definition with "type": "hidden" and at most one Logic Jump definition for each field ("type": "field"). Multiple jump conditions can be defined inside the actions array
For example, this is not valid, because it has two Logic Jump definitions for the field ref_trigger_field:
{
"logic":[
{
"type":"field",
"ref":"ref_trigger_field",
"actions":[{...}]
},
{
"type":"field",
"ref":"ref_trigger_field",
"actions":[{...}]
},
{
"type":"field",
"ref":"ref_another_trigger_field",
"actions":[{...}]
}
]
}In this case, the correct format should be to merge actions from the two definitions of field ref_trigger_field into a single one:
{
"logic":[
{
"type":"field",
"ref":"ref_trigger_field",
"actions":[{...}, {...}]
},
{
"type":"field",
"ref":"ref_another_trigger_field",
"actions":[{...}]
}
]
}to objectThe to object defines where the Logic Jump leads to — it answers the question, "Where to?" You have three options: a field in the form, the default thank-you screen, or a custom thank-you screen.
Here's an example object for a Logic Jump to a field in the form:
{
"action":"jump",
"details":{
"to":{
"type":"field",
"value":"ref_field_leads_to"
}
},And for a jump to the default thank-you screen:
{
"action":"jump",
"details":{
"to":{
"type":"thankyou",
"value":"default"
}
},And for a jump to a custom thank-you screen:
{
"action":"jump",
"details":{
"to":{
"type":"thankyou",
"value":"thankyou_screen_reference"
}
},Here's a description of each element in this to object:
| Element | Type | Description | Required? | ||
|---|---|---|---|---|---|
| action | string | Behavior the Logic Jump will take. Valid values include jump, add, subtract, multiply, and divide. | Required | ||
| details | object | Properties that specify how the Logic Jump will behave. | Required | ||
| to | object | Elements that define where the Logic Jump leads to. | Required | ||
| type | string | Identifies which Logic Jump "to" option you are using. Valid values are field and thankyou. | Required | ||
| value | string | ref value for the field or thank-you screen where the Logic Jump leads to. Valid values include the ref for any field in the form, the ref for any custom thank-you screen, and default for the default thank-you screen. | Required |
NOTE: You can use Logic Jumps for more than jumping to a question! If your form adds up the prices of different items or keeps a score and provides a total at the end, use target and value instead of to.
The POST https://api.typeform.com/forms endpoint includes a schema explanation.
condition objectIn the condition object, you specify the conditions for executing your Logic Jump. The conditions answer the question, "Under what circumstances?" The condition object is the IF statement in your Logic Jump.
In plain language, a condition would be something like "Execute the jump if the numeric answer for Question X is less than 5" or "Execute the jump if the person answers "No" to the legal agreement." In code, it looks quite different!
In our example, the Logic Jump should execute when a respondent answers "10" in the field with the ref "readable field reference".
"condition":{
"op":"equal",
"vars":[
{
"type":"field",
"value":"ref_another_field"
},
{
"type":"constant",
"value":10
}
]
}Here's a description of each element in the condition object.
| Element | Type | Description | Required? | |||
|---|---|---|---|---|---|---|
| condition | object | Conditions for executing the Logic Jump. | Required | |||
| op | string | Operator for the condition. Valid values depend on the field type: text, numeric, choice, date, file upload, or hidden — see subsections below for details. | Required | |||
| vars | array of objects | Elements that define the field type and value to evaluate with the operator. | Required | |||
| type | string | Type of value the condition object refers to. Valid values are field, hidden, variable, constant, and end. | Required | |||
| value | string | Value to check for in the type field to evaluate with the operator. | Required |
Read on for details about the operators (op) you can use for each field type.
| Operator | Meaning |
|---|---|
| always | Always execute the jump |
{
"op": "always",
"vars": []
}For the always operator, you don't need to specify any vars. Your typeform will always execute this Logic Jump.
| Operator | Meaning |
|---|---|
| equal | Execute jump if field answer equals specified value |
| not_equal | Execute jump if field answer does not equal specified value |
| begins_with | Execute jump if field answer starts with specified value |
| ends_with | Execute jump if field answer ends with specified value |
| contains | Execute jump if field answer contains specified value |
| not_contains | Execute jump if field answer does not contain specified value |
{
"op": "equal",
"vars": [
{
"type": "field",
"value": "text_field_ref"
},
{
"type": "constant",
"value": "Mamon"
}
]
}For conditions based on numeric fields, the specified value must be an integer.
| Operator | Meaning |
|---|---|
| equal | Execute jump if field answer equals specified value |
| not_equal | Execute jump if field answer does not equal specified value |
| lower_than | Execute jump if field answer is less than specified value |
| lower_equal_than | Execute jump if field answer is less than or equal to specified value |
| greater_than | Execute jump if field answer is greater than specified value |
| greater_equal_than | Execute jump if field answer is greater than or equal to specified value |
{
"op": "lower_than",
"vars": [
{
"type": "field",
"value": "numeric_field_ref"
},
{
"type": "constant",
"value": "3"
}
]
}| Operator | Meaning |
|---|---|
| is | Execute jump if field answer matches the ref of the choice (for text choice and picture choice fields) or specified Boolean value (for yes/no and legal fields). |
| is_not | Execute jump if field answer does not match the ref of the choice (for text choice and picture choice fields) or specified Boolean value (for yes/no and legal fields). |
ref of the choice{
"op": "is",
"vars": [
{
"type": "field",
"value": "picture_or_text_choice_field_ref"
},
{
"type": "choice",
"value": "multiple_choice_ref"
}
]
}yes/no or legal answer matches specified Boolean value{
"op": "is",
"vars": [
{
"type": "field",
"value": "yes_no_or_legal_field_ref"
},
{
"type": "constant",
"value": true
}
]
}| Operator | Meaning |
|---|---|
| on | Execute jump if field answer matches specified date |
| not_on | Execute jump if field answer is not on specified date |
| earlier_than | Execute jump if field answer is earlier than specified date |
| earlier_than_or_on | Execute jump if field answer is earlier than or on specified date |
| later_than | Execute jump if field answer is later than specified date |
| later_than_or_on | Execute jump if field answer is later than or on specified date |
value{
"op": "on",
"vars": [
{
"type": "field",
"value": "date_field_ref"
},
{
"type": "constant",
"value": "2016-09-30"
}
]
}The date format is YYYY-MM-DD.
| Operator | Meaning |
|---|---|
| answered | Execute jump if respondent uploaded a file |
{
"op": "answered",
"vars": [
{
"type": "field",
"value": "file_upload_field_ref"
},
{
"type": "constant",
"value": true
}
]
}| Operator | Meaning |
|---|---|
| equal | Execute jump if Hidden Field equals specified value |
| not_equal | Execute jump if Hidden Field does not equal specified value |
| begins_with | Execute jump if Hidden Field starts with specified value |
| ends_with | Execute jump if Hidden Field ends with specified value |
| contains | Execute jump if Hidden Field contains specified value |
| not_contains | Execute jump if Hidden Field does not contain specified value |
{
"op": "equal",
"vars": [
{
"type": "hidden",
"value": "referrer"
},
{
"type": "constant",
"value": "facebook"
}
]
}Follow these best practices to create Logic Jumps that work beautifully.
ref values that actually existThis is the most important part of ensuring that your Logic Jumps work properly. Make sure that you don't include a ref to a field that doesn't exist in the typeform. And as always, watch for typos!
If you include more than one condition in a Logic Jump, it's important to put the conditions in the correct order so that the Logic Jump executes the way you want. The first condition that's met will trigger the Logic Jump, and any subsequent conditions will be ignored.
For example, suppose you have multiple choice question, and respondents can pick more than one answer. If the answer is Mango, the form should skip to Question 3. If the answer is Mango and Apple, the form should skip to question 4.
For this Logic Jump to work properly, put the condition "If [Mango AND Apple], jump to Question 4" first--before the condition "If [Mango], jump to Question 3."
Here's what this looks like in code:
{
"logic": [
{
"type": "field",
"ref": "ref_text_choice_field",
"actions": [
{
"type": "jump",
"jump": {
"to": {
"type": "field",
"value": "ref_question4"
}
},
"condition": {
"op": "and",
"vars": [
{
"op": "is",
"vars": [
{
"type": "field",
"value": "ref_text_choice_field"
},
{
"type": "constant",
"value": "ref_for_mango"
}
]
},
{
"op": "is",
"vars": [
{
"type": "field",
"value": "ref_other_text_choice_field"
},
{
"type": "constant",
"value": "ref_for_apple"
}
]
}
]
}
},
{
"type": "jump",
"jump": {
"to": {
"type": "field",
"value": "ref_question3"
}
},
"condition": {
"op": "is",
"vars": [
{
"type": "field",
"value": "ref_text_choice_field"
},
{
"type": "constant",
"value": "ref_for_mango"
}
]
}
}
]
}
]
}If you put "If [Mango], skip to Question 3" first, and a respondent answered [MangoAND Apple], the Logic Jump to Question 3 would execute because the answer contains "Mango."
When you're organizing the order of your Logic Jumps, place your most restrictive conditions first, followed by your more general conditions.
For example, if you have the conditions "answer begins with b" and "answer is boat", place the condition "answer is boat" first because it's more restrictive.
AND and OR operators correctlyYou can use AND and OR operators to add several conditions to a single Logic Jump, but it's important to use the correct operators in the correct order to achieve the result you want.
Imagine that this is Question 1: "Select your favorite fruits." The answer choices are Apple, Orange, and Mango. Respondents can select one, two, or all three choices.
Here's what the Logic Jump code should look like for the scenario IF answer is [Apple AND Orange] OR [Mango], jump to Question 3:
{
"logic":[
{
"type":"field",
"ref":"ref_text_choice_field",
"actions":[
{
"type":"jump",
"jump":{
"to":{
"type":"field",
"value":"ref_question3"
}
},
"condition":{
"op":"or",
"vars":[
{
"op":"and",
"vars":[
{
"op":"is",
"vars":[
{
"type":"field",
"value":"ref_text_choice_field"
},
{
"type":"constant",
"value":"apple"
}
]
},
{
"op":"is",
"vars":[
{
"type":"field",
"value":"ref_text_choice_field"
},
{
"type":"constant",
"value":"orange"
}
]
}
]
},
{
"op":"is",
"vars":[
{
"type":"field",
"value":"ref_text_choice_field"
},
{
"type":"constant",
"value":"ref_for_mango"
}
]
}
]
}
]
}
]
}And here's what the Logic Jump code should look like for the scenario IF answer is [Apple AND Orange] OR [Apple AND Mango], jump to Question 3:
{
"logic":[
{
"type":"field",
"ref":"ref_text_choice_field",
"actions":[
{
"type":"jump",
"jump":{
"to":{
"type":"field",
"value":"ref_question3"
}
},
"condition":{
"op":"or",
"vars":[
{
"op":"and",
"vars":[
{
"op":"is",
"vars":[
{
"type":"field",
"value":"ref_text_choice_field"
},
{
"type":"constant",
"value":"apple"
}
]
},
{
"op":"is",
"vars":[
{
"type":"field",
"value":"ref_text_choice_field"
},
{
"type":"constant",
"value":"orange"
}
]
}
]
},
{
"op":"and",
"vars":[
{
"op":"is",
"vars":[
{
"type":"field",
"value":"ref_text_choice_field"
},
{
"type":"constant",
"value":"apple"
}
]
},
{
"op":"is",
"vars":[
{
"type":"field",
"value":"ref_text_choice_field"
},
{
"type":"constant",
"value":"mango"
}
]
}
]
},
]
}
]
}
]
}Logic Jumps can only jump to a previous question if the respondent has already visited that question. So for example, if a respondent bypassed Question A in Logic Jump X, you can't send the respondent back to Question A in Logic Jump Y. Place the question or statement that a Logic Jump leads to after the question that triggers the Logic Jump.
Multi-branching allows you to ask follow-up questions based on answers to a previous question. For example, if a respondent answers the multiple-choice question, "Which book do you prefer? A. Charlotte's Web B. James and the Giant Peach" by selecting Charlotte's Web, you can create multi-branch Logic Jumps to ask follow-up questions specific to Charlotte's Web and skip questions related to James and the Giant Peach. Here are some best practices for multi-branching.
The question that comes immediately before a branch must be a Logic Jump. If you forget to include a Logic Jump before a branch, respondents could end up in a branch of questions that don't make sense based on their previous answers.
For example, if you forget to include a Logic Jump on the multiple-choice question, "Which book do you prefer? A. Charlotte's Web B. James and the Giant Peach", respondents who answer "A. Charlotte's Web will still see questions about James and the Giant Peach.
Make sure that your Logic Jumps include follow-up questions for all the possible answers (or combinations of answers). To continue our "Which book do you prefer?" example, you'd need two branches: one for the answer A. Charlotte's Web and one for the answer B. James and the Giant Peach. If you offer a third answer choice, C. Watership Down, you'd need a third branch in case respondents choose answer C.
Now, consider how many branches you'd need for the question, "Which of these books do you enjoy? A. Charlotte's Web B. James and the Giant Peach". For this question, respondents could choose only A., only B., both A. and B., or neither A. or B. So you'd need four branches.
There's no limit to the number of Logic Jumps you can include---here's an example typeform that uses more than 100! As long as your Logic Jumps are set up properly, you can use as many as you need to give your repondents a great experience.
Learn more about how Hidden Fields work in the Create API. Or, check out the Create reference for endpoints.