Guided Flows Example

Guided Flows Explained

Guided flows were designed to help determine the precise withholding form(s) a user may need based on their unique withholding scenario. This is accomplished by leveraging a user'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 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 - I am exempt from withholding on compensation for independent (or eligible dependent) personal services of a Nonresident Alien Individual, see instructions for Form 8233
  • Quiero continuar en Español
  • I want to continue in English

Based on the user selection above, a designated form is determined that the user can complete for their specific withholding scenario. The "Guided Process" is very helpful for users that need help determining the relevant payroll withholding form(s) to complete.


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 the provided with the formsToComplete object that identifies the formIDs. The final question set can be identified when hasMoreQuestions 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.


Jump to top