guided-flows (POST)
The guided-flows endpoint receives one home address and one or more work address(es) representing the employee’s physical work location(s). It returns a list of applicable flows for the employee’s withholding scenario.
{
"homeAddress": {
"streetAddress1": "11 S Union St",
"city": "Montgomery",
"state": "AL",
"zipCode": "36130"
},
"workAddresses": [
{
"streetAddress1": "64 N Union St",
"city": "Montgomery",
"state": "AL",
"zipCode": "36130"
},
{
"streetAddress1": "1700 W Washington St",
"city": "Phoenix",
"state": "AZ",
"zipCode": "85007"
}
]
}
Resulting flows are then used to filter the list of all applicable forms down to a list of required forms. Note that some states/scenarios do not require additional information to filter the applicable forms.
{
"flows": [
{
"id": "FEDERAL",
"locality": "FEDERAL",
"hasFlowQuestions": true,
"initialQuestionSetId": "QS1",
"localityFullName": "Federal"
},
{
"id": "AL_RESIDENT",
"locality": "AL",
"residencyStatus": "RESIDENT",
"hasFlowQuestions": true,
"initialQuestionSetId": "QS1",
"localityFullName": "Alabama"
},
{
"id": "AZ_NONRESIDENT",
"locality": "AZ",
"residencyStatus": "NONRESIDENT",
"hasFlowQuestions": true,
"initialQuestionSetId": "QS1",
"localityFullName": "Arizona"
}
],
"locationData": [
{
"id": "home",
"inputAddress": {
"streetAddress1": "11 S Union St",
"city": "Montgomery",
"state": "AL",
"zipCode": "36130"
},
"normalizedAddress": {
"streetAddress1": "11 S Union St",
"city": "Montgomery",
"state": "AL",
"zipCode": "36130-2102"
},
"addressResultMessages": {
"GS01": {
"message": "Geocoded to Street Level",
"description": "The record was coded to the street level (Zip+4 for US, full postal code for CA)."
},
"AS01": {
"message": "Valid Address",
"description": "The address is valid and deliverable according to official postal agencies."
}
},
"latitude": "32.376634",
"longitude": "-86.299645",
"geocoded": false,
"verified": true
},
{
"id": "work1",
"inputAddress": {
"streetAddress1": "64 N Union St",
"city": "Montgomery",
"state": "AL",
"zipCode": "36130"
},
"normalizedAddress": {
"streetAddress1": "64 N Union St",
"city": "Montgomery",
"state": "AL",
"zipCode": "36130-3020"
},
"addressResultMessages": {
"GS01": {
"message": "Geocoded to Street Level",
"description": "The record was coded to the street level (Zip+4 for US, full postal code for CA)."
},
"AS01": {
"message": "Valid Address",
"description": "The address is valid and deliverable according to official postal agencies."
}
},
"latitude": "32.378229",
"longitude": "-86.299726",
"geocoded": false,
"verified": true
},
{
"id": "work2",
"inputAddress": {
"streetAddress1": "1700 W Washington St",
"city": "Phoenix",
"state": "AZ",
"zipCode": "85007"
},
"normalizedAddress": {
"streetAddress1": "1700 W Washington St",
"city": "Phoenix",
"state": "AZ",
"zipCode": "85007-2812"
},
"addressResultMessages": {
"GS05": {
"message": "Geocoded to Rooftop Level",
"description": "The record was geocoded down to the rooftop level, meaning the point is within the property boundaries, usually the center."
},
"AS17": {
"message": "No USPS Mail Delivery",
"description": "US Only. The address is classified as not receiving mail by the USPS. This may be deliverable by third party delivery companies."
},
"AS02": {
"message": "Street Only Match",
"description": "The street address was verified but the suite/apartment number is missing or invalid."
}
},
"latitude": "33.448573",
"longitude": "-112.094486",
"geocoded": true,
"verified": true
}
]
}
Displayed above is an example object we will return based upon the home and work address(es) sent in.
- id represents the ID for flow you path you can take. "AL_RESIDENT" means that you would follow the path to filter down to Alabama forms that an Alabama resident would fill out based on your home and work addresses.
- locality represents the current flows state abbreviation. If locality is "FEDERAL" it will not include a residency status.
- residencyStatus represents that as an employee, you are a resident or nonresident of the state abbreviation listed in locality.
- hasFlowQuestions is a boolean that when set to true, means that there are additional question sets needed to filter down to the appropriate forms list.
- initialQuestionSetId represents the starting question set for the guided-flows process.
- localityFullName represents the current flows state full name.
You can use the id and initialQuestionSetId to submit to the /flowQuestionSet/{flowId}/{questionSetId} endpoint to get details about the next question set.
Location Data
For more information about the location data object navigate to Location Data Page
Reciprocal States and States without Guided-Flows
In certain scenarios, some states do not have guided-flows. This could be due to a reciprocity agreement or that sometimes certain forms are always returned based upon a set of home and work addresses.
See the example below:
{
"homeAddress": {
"streetAddress1": "501 N 3rd St",
"city": "Harrisburg",
"state": "PA",
"zipCode": "17120"
},
"workAddresses": [
{
"streetAddress1": "200 W Washington St",
"city": "Indianapolis",
"state": "IN",
"zipCode": "46204"
}
]
}
Given the agreement between Pennsylvania and Indiana, it can be determined that the "IN_NONRESIDENT" flow will result in form IN102 being required. Because of this, hasFlowQuestions is set to false and the specific formsToComplete array is provided without any further flow-based filtering with the flowQuestionSet endpoint.
See the example below:
{
"flows": [
{
"id": "FEDERAL",
"locality": "FEDERAL",
"hasFlowQuestions": true,
"initialQuestionSetId": "QS1",
"localityFullName": "Federal"
},
{
"id": "PA_RESIDENT",
"locality": "PA",
"residencyStatus": "RESIDENT",
"hasFlowQuestions": true,
"initialQuestionSetId": "QS1",
"localityFullName": "Pennsylvania"
},
{
"id": "IN_NONRESIDENT",
"locality": "IN",
"residencyStatus": "NONRESIDENT",
"hasFlowQuestions": false,
"formsToComplete": [
{
"id": "IN101",
"name": "WH-4",
"title": "Employee's Withholding Exemption and County Status Certificate",
"formVersion": "2020.12.0",
"formLocality": "IN",
"formType": "RESIDENT",
"initialQuestionSet": "QS1"
},
{
"id": "IN102",
"name": "WH-47",
"title": "Certificate of Residence",
"formVersion": "2021.3.0",
"formLocality": "IN",
"formType": "NON_RESIDENT",
"initialQuestionSet": "QS1"
}
],
"localityFullName": "Indiana"
}
]
}
Displayed above is an example object of formsToComplete returned based upon the home and work address(es) provided. These forms will come with additional information you can collect and display in your application.
- 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
Lock In Letters
At times, the IRS may give an employer an order to withhold taxes at a minimum rate. Therefore, SPF-API provides a mechanism to prevent employees from changing certain state or federal withholding forms. Refer to the Lock In Letter documenation for more details and a sample request.
Nexus
Nexus can be specified using the guided-flows endpoint. Refer to the Nexus documentation for more details and a sample request.
At Symmetry, we have a dedicated Tax Research team that helps us filter down forms based upon a business's tax presence when they have operations in more than one state. Deciding which state's payroll tax to withhold from an employee can be a confusing process.
No matter which state or multiple states an employee or employer operates in, SPF-API will automatically filter down the proper withholding forms for each scenario and return it in the forms (POST) endpoint.
Interstate Employees
Interstate commerce means any work involving or related to the movement of persons or things (including intangibles, such as information) across state lines or from foreign countries. Interstate employees are not taxed at the states they drive through or where the destination resides.
For Pennsylvania residents, this has the effect of limiting multi-state form determination to Federal forms and PA local forms, removing any other forms outside of those jurisdictions. To mark a PA resident employee as an interstate employee, set the interstateEmployee field to true.
Updated over 3 years ago
