flowQuestionSet/{flowId}/{questionSetId} (GET)
The flowQuestionSet endpoint returns a question set for a given flow. Flow question sets are used to filter the list of potentially applicable forms down to a list of required forms. Each question set may contain one or more questions, validation regular expressions, and navigation aids.
Below is a sample response of the flowQuestionSet for the Federal flow, question set 1:
{
"id": "QS1",
"questions": [
{
"id": "federalGuidedQ1",
"questionText": "Select one",
"validationRegex": "",
"htmlType": "INPUT",
"displayType": "RADIO",
"required": {
"whenRequired": "ALWAYS"
},
"questionOptions": [
{
"label": "Foreign Earned Income Exclusion - I expect to qualify for the foreign earned income exclusion under either the bona fide residence or physical presence test for calendar year or other tax year",
"formsToComplete": [
{
"id": "W6101",
"name": "673",
"title": "Statement For Claiming Exemption From Withholding on Foreign Earned Income Eligible for the Exclusion(s) Provided by Section 911",
"formVersion": "2019.1.0",
"formLocality": "FEDERAL",
"formType": "EXEMPT",
"initialQuestionSet": "QS1"
}
]
},
{
"label": "Nonresident Alien - I am exempt from withholding on compensation for independent (or eligible dependent) personal services of a Nonresident Alien Individual, see instructions for Form 8233",
"formsToComplete": [
{
"id": "W8101",
"name": "8233",
"title": "Exemption From Withholding on Compensation for Independent (and Certain Dependent) Personal Services of a Nonresident Alien Individual",
"formVersion": "2018.9.0",
"formLocality": "FEDERAL",
"formType": "EXEMPT",
"initialQuestionSet": "QS1"
}
]
},
{
"label": "Quiero continuar en Español",
"formsToComplete": [
{
"id": "W4101SP",
"name": "W-4(SP)",
"title": "Certificado de Retenciones del Empleado",
"formVersion": "2020.12.0",
"formLocality": "FEDERAL",
"formType": "RESIDENT",
"initialQuestionSet": "QS1"
}
]
},
{
"label": "I want to continue in English",
"formsToComplete": [
{
"id": "W4101",
"name": "W-4",
"title": "Employee's Withholding Certificate",
"formVersion": "2021.1.0",
"formLocality": "FEDERAL",
"formType": "RESIDENT",
"initialQuestionSet": "QS1"
}
]
}
],
"isCalculated": false
}
],
"breadcrumbTitle": "Survey",
"navigation": {
"navigationType": "CONSTANT",
"navigationMapping": {
"hasMoreQuestions": false
}
}
}
The information below will detail the various aspects of the response object above.
Outer Objects
- id represents which question set you are on.
- notes represents an object of one of the following html types PARAGRAPH, UNORDERED_LIST, IMAGE, or TABLE that is recommend for displaying the question or instructions.
- questions represents an array of question objects to help filter down to a formsToComplete array.
- breadcrumbTitle represents our recommended title for breadcrumbs relating to the question.
- navigation represents an object to help navigate through the guided-flows
Notes Object
- notes take three html types (PARAGRAPH, UNORDERED_LIST, IMAGE, or TABLE).
- Paragraph returns a string argument and a suggest placement.
{
"htmlType": "PARAGRAPH",
"suggestedPlacement": "BELOW_QUESTION",
"text": "Selecting Yes will result in selecting a marital status of Single or Married filing separately regardless of actual marital status. See Notice 1392 for more details."
}
- Unordered lists return an array of strings, each representing an item in the list and a suggested placement. Unordered lists may also return an optional label for the list.
{
"htmlType": "UNORDERED_LIST",
"suggestedPlacement": "ABOVE_ALL_QUESTIONS",
"optionalLabel": "Form A4-MS is to be used only for employees claiming exemption from Alabama's income tax withholding requirements based on the conditions set forth under the Military Spouses Residency Relief Act (P.L. 111-97). In order to qualify for this exemption, the employee must be able to answer true to all of the following conditions:",
"listItems": [
"My Spouse is an active duty military servicemember",
"I am not a military servicemember",
"My Spouse's current military orders assign him/her to a location in/near Alabama",
"I am present in/near Alabama solely to be with my servicemember Spouse",
"I and my military service member Spouse live at the same address",
"My domicile is a state other than Alabama",
"My military servicemember Spouse's domicile is the same as mine, or I will be selecting my Spouse's domicile for tax purposes"
]
}
- Image returns the href of the image itself, a suggested placement, and may an optional label.
{
"htmlType": "IMAGE",
"suggestedPlacement": "ABOVE_ALL_QUESTIONS",
"href": "https://spfcdn.symmetry.com/images/NC102/1.20.0/nc102_allowances-table.png"
}
- Tables return an object containing an array of headers and an array of rows, representing the respective cells in each row. Table note types will also include a suggested placement and may include an optional label. An example can be found below.
{
"htmlType": "TABLE",
"suggestedPlacement": "ABOVE_ALL_QUESTIONS",
"headers": [
"Filing Status & Dependents",
"Income range from all sources"
],
"rows": [
{
"cells": [
"Single",
"$12,493 to $14,900"
]
},
{
"cells": [
"Married Filing Jointly (1 or less dependents)",
"$21,068 to $24,800"
]
},
{
"cells": [
"Married Filing Jointly (2 or more dependents)",
"$25,356 to $30,800"
]
},
{
"cells": [
"Head of Household/Qualifying Widow(er) (1 or less dependents)",
"$17,762 to $21,600"
]
},
{
"cells": [
"Head of Household/Qualifying Widow(er) (2 or more dependents)",
"$21,173 to $24,800"
]
}
]
}
Questions Objects
- id represents the question id for the current question set.
- questionText represents the text recommend tp display the question.
- validationRegex represents the only values that the api will allow in relation to the matching question.
- validationErrorMessage represents a recommended error message related to the question.
- htmlType represents the html recommendation for a UI to display. HTML types used are INPUT, SELECT, TEXTAREA, PARAGRAPH, UNORDERED_LIST, IMAGE, and TABLE.
- displayType represents additional information about our HTML recommendation if required for that HTML type. Display types used are TEXT, RADIO, CHECKBOX, MULTI_SELECT_CHECKBOX, MONTH_YEAR, YEAR, TELEPHONE, EMAIL, ZIPCODE, INTEGER, PERCENT, and DOLLAR.
- required contains the element whenRequired. The whenRequired element has three enum values (ALWAYS, DEPENDENT, and NEVER). Based upon these values, it can be determined whether a question must be answered and sent back to the API to complete the fillPdf process.
- questionOptions can be represented in three ways. This will be broken down below
Required, Validation Regex, and Validation Error Message
Before moving on it we want to make it clear that the required field is independent from the validation regex and validation error message field.
The required field only pertains to whether a question is required to be submitted to the API. If whenRequired is set to NEVER and no value is submitted then the validationRegex and validationErrorMessage will never be triggered. On the other hand, if a value is submitted, then it will be validated by the validationRegex and if it is an incorrect value we will display the validationErrorMessage.
"questionOptions": [
{
"label": "Yes",
"value": true
},
{
"label": "No",
"value": false
}
]
- questionOptions can represent an object array with labels and values. Labels represent the text that should be displayed.
These types of questionOptions allow you to continue to the next question set to determine forms.
"questionOptions": [
{
"label": "I am not a RESIDENT of Alabama and meet the conditions set forth under the Military Spouses Residency Relief Act (P. L. 111-97) and will have no Alabama income tax liability",
"formsToComplete": [
{
"id": "AL103",
"name": "A4-MS",
"title": "Nonresident Military Spouse Withholding Tax Exemption Certificate",
"formVersion": "2019.9.0",
"formLocality": "AL",
"formType": "EXEMPT_MILITARY_SPOUSE",
"initialQuestionSet": "QS1"
}
]
},
{
"label": "Quiero continuar en Español",
"formsToComplete": [
{
"id": "AL101SP",
"name": "A4(SP)",
"title": "Certificado para todo Empleado de Exención de Retencion de Ingresos para Pago de Impuestos",
"formVersion": "2016.5.0",
"formLocality": "AL",
"formType": "RESIDENT",
"initialQuestionSet": "QS1"
}
]
},
{
"label": "I want to continue in English",
"formsToComplete": [
{
"id": "AL101",
"name": "A4",
"title": "Employee's Withholding Exemption Tax Certificate",
"formVersion": "2014.3.0",
"formLocality": "AL",
"formType": "RESIDENT",
"initialQuestionSet": "QS1"
}
]
}
]
- questionOptions can represent labels and a formsToComplete array. Labels represent the text recommend to be displayed, while the formsToComplete array gives the list of forms recommended and other important information about the form based on the question option chosen.
"questionOptions": [
{
"label": "I want to claim exemption from Kentucky withholding",
"formsToComplete": [
{
"id": "KY101",
"name": "K-4",
"title": "Kentucky's Withholding Certificate",
"formVersion": "2020.12.0",
"formLocality": "KY",
"formType": "RESIDENT",
"initialQuestionSet": "QS1"
}
]
},
{
"label": "I want to increase my Kentucky additional withholding amount",
"formsToComplete": [
{
"id": "KY101",
"name": "K-4",
"title": "Kentucky's Withholding Certificate",
"formVersion": "2020.12.0",
"formLocality": "KY",
"formType": "RESIDENT",
"initialQuestionSet": "QS1"
}
]
},
{
"label": "None of the above"
}
],
- questionOptions can represent labels and an empty formsToComplete array. Given a certain type of question option, it is possible that you will have no forms to complete. Above if the user selects "None of the above", they will not receive a formsToComplete array.
Forms To Complete Object
- id represents the actual form id which can be referenced from the getAllFormIds endpoint.
- name the actual name of the form to be completed
- formVersion the latest and recommended form version to be completed
- formLocality what the forms locality is
- formType what type of form resident, nonresident, military, exempt, pension etc..
- initialQuestionSet is provided and most always defaults to QS1 for what question set is the start of the form process
Navigation Objects
navigationType represents one of the two types of navigation a question can take (CONSTANT or VARIABLE).
Constant navigation objects represent static navigation, in which, the next question set is always the next question set, regardless of the answers to questions contained within the current question set. Variable navigation objects represent dynamic navigation, in which, the next question is dependent upon the selected answer for question within the current question set.
A constant navigation object will consist of the following:
- navigationType with a value of CONSTANT
- navigationMapping which will contain a boolean flag hasMoreQuestions.
- When hasMoreQuestions with a value of true represents that there are additional question sets that need to be completed. The navigationMapping will include nextQuestionSetId for the ID of the next question set.
- When hasMoreQuestions with a value of false represents that there are no more questions to be asked. The navigationMapping will not include nextQuestionSetId.
"navigation": {
"navigationType": "CONSTANT",
"navigationMapping": {
"hasMoreQuestions": false
}
}
A variable navigation object will consist of the following:
- navigationType
- questionId matches the id from the question object.
- navigationMappings represent an additional object to determine how to navigate through question sets. It will contain additional objects whose keys match the question options values. These objects will contain two additional keys, nextQuestionSetId and hasMoreQuestions.
- nextQuestionSetId will return a string value in the format (QS#).
- hasMoreQuestions will return a boolean. A value of true means that there are additional question sets that need to be completed. A value of false means that this question is the last question in the question set.
In the example below, we can see that selecting an answer of true will result in hasMoreQuestions returning false, and a formsToComplete array returned with the selected question option. Selecting false requires additional questions to make a form determination.
{
"id": "QS1",
"questions": [
{
"id": "isTerminatingMilitarySpouseExemption",
"questionText": "Do you currently have a military spouse exemption that you no longer qualify for OR no longer wish to claim?",
"validationErrorMessage": "Please select an option",
"htmlType": "INPUT",
"displayType": "RADIO",
"required": {
"whenRequired": "ALWAYS"
},
"questionOptions": [
{
"label": "Yes",
"value": true,
"formsToComplete": [
{
"id": "AZ101",
"name": "A-4",
"title": "Employee's Arizona Withholding Election",
"formVersion": "2020.12.0",
"formLocality": "AZ",
"formType": "RESIDENT",
"initialQuestionSet": "QS1"
},
{
"id": "AZ102",
"name": "WEC",
"title": "Employee Withholding Exemption Certificate",
"formVersion": "2020.12.0",
"formLocality": "AZ",
"formType": "EXEMPT",
"initialQuestionSet": "QS1"
}
]
},
{
"label": "No",
"value": false
}
],
"isCalculated": false
}
],
"breadcrumbTitle": "Military Spouse Exemption",
"navigation": {
"navigationType": "VARIABLE",
"questionId": "isTerminatingMilitarySpouseExemption",
"navigationMappings": {
"false": {
"nextQuestionSetId": "QS2",
"hasMoreQuestions": true
},
"true": {
"hasMoreQuestions": false
}
}
}
}
Before Moving On From Navigation!
Due to the nature of using a VARIABLE navigation type, the next page (question set) could have multiple paths. As specifically designed, our API returns "navigationMappings" as there could be more than one path.
In contrast, using a CONSTANT navigation type, the next page (question set) is always the next question with no variance. Therefore, by design our API will return "navigationMapping" as there is only one path.
Language Support
The flowQuestionSet endpoint also provides language support for English, Spanish, and French using the Accept-Language request HTTP header.
Updated about 3 years ago
