Implementation Options

Both SPF API and SPF Hosted clients have the ability to choose how employees navigate between forms provided by SPF.

• Guided Mode: Ideal for employee onboarding — employees are coached through an automated process ensuring forms are correct and complete.
• Choose Mode: Ideal for companies and employees who know the exact forms they need — gives employees the ability to select forms at-will while field validation ensures employees complete forms accurately.

The implementation option is set at the Company level and not employee level; therefore, you'll want to determine what implementation option works best for your application.

Guided Mode

Guided Mode is 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.

Below is an example of the Choose Mode interface for an employee who lives and works in Alabama.

Guided Mode for Hosted

To enabled Guided Mode, set the "enabled" element within "guidedMode" to true in the SPF Registration file.

        "guidedMode": {
            "enabled": true,
            "disableLocalitySelection": false,
            "disableFederal": false
        }

Guided Mode for On-Premise

To enabled Guided Mode, set the "enabled" element within "guidedMode" to true in the Settings JSON file or SPF Registration.

Guided Mode for API

The /guided-flows (POST) endpoint returns the list of applicable flows based on the home address and one or more work addresses sent in for the employee.

The 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 required additional information to filter the applicable forms.

To see a complete example and diagram of this flow, check out the Guided Flows Example within the guide.

Choose Mode

Choose Mode returns the list of all possible withholding forms the employee may complete for that specific onboarding scenario. This option is ideal when a user knows what form(s) they need to complete.

Below is an example of Choose Mode for an employee who has both an Alabama residence and work address.

Choose Mode for Hosted

To enabled Choose Mode, set the "enabled" element within "chooseMode" to true in the SPF Registration file.

        "chooseMode": {
            "enabled": true,
            "excludedForms": []
        }

Choose Mode for On-Premise

To enabled Choose Mode, set the "enabled" element within "chooseMode" to true in the Settings JSON file.

Choose Mode for API

The /forms (POST) endpoint receives a single home address and one or more work addresses representing the employee’s physical work locations. It returns a list of applicable forms for the employee’s withholding scenario.

The /formQuestionSet (GET) endpoint returns a question set for a given form. Each question set may contain one or more questions, validation regular expression, and navigation aids.

To see a complete example and diagram of this flow, check out the Form Completion Example within the guide.