Guided Flows Example

Guided Flows Explained

Guided flows were designed to help determine the precise withholding form(s) an employee may need based on their unique withholding scenario. This is accomplished by leveraging the employee's home location and one or more work locations. Based on address details, applicable flows are determined which contain targeted questions that help to identify the specific form(s) needed. For example, the US FEDERAL flow is comprised of one question set that has a single question with four different options for a user to choose from:

• 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
• Nonresident Alien who is EXEMPT - I am exempt from withholding on compensation for independent (or eligible dependent) personal services of a Nonresident Alien Individual, see instructions for Form 8233
• Standard Federal Withholding (English) - I am not qualified for a Foreign Earned Income Exclusion. I want to complete the standard Federal W4
• Retención Federal Estándar (Español) - No estoy calificado para una exclusión de ingresos del trabajo en el extranjero. Quiero completar el estándar Federal W4

Based on the employee's selection above, a designated form is determined that the user can complete for their specific withholding scenario. The "Guided Mode" process is very helpful for users that need support to determine the relevant payroll withholding form(s) to complete.

Example

Below is a high-level example of the endpoints that can be used to determine the flows necessary to identify the specific forms an employee may be required to complete for proper payroll withholdings.

1. Provide address information to the guided-flows endpoint.
2. The applicable flows will be provided.
3. Provide the flowId to the flowQuestionSet endpoint and specify the first question set: /flowQuestionSet/FEDERAL/QS1.
4. Iterate over the flowQuestionSet until provided with the <span style="font-family:courier">formsToComplete</span> object that identifies the formIDs. The final question set can be identified when <span style="font-family:courier">hasMoreQuestions</span> equals false. See the flowQuestionSet endpoint for more detailed implementation instructions.
5. Repeat steps 3 & 4 above with the additional flows provided by the /guided-flows endpoint until all flows have been completed.
6. The provided form ID(s) from the guided flow can be used to complete the form(s).

The image below provides a graphical representation of the guided process and includes the SPF API endpoints necessary to determine relevant withholding forms.