Quickstart

Gusto Flows are ready-to-use UI components, built on top of Gusto Embedded’s API. Flows are designed to quickly integrate essential payroll functionalities into your application without extensive engineering effort, accelerating your time to market.

Learn how Gusto Flows work at a high level, or use our “Try it Now” tool to demo Gusto Flows without API keys.

Key features:

• Pre-built and ready-to-use, Flows can be styled using custom fonts and branding settings which are modifiable from the Gusto’s Developer Portal at Organizations > {ORGANIZATION_NAME} > Flow Settings. Read more at Customize flows.
• Flexible implementation: Use flows on their own or in conjunction with Gusto Embedded’s API.

1. Generate and host a flow

Flows can be hosted in a new tab or iframed into your application, and are generated with a POST request to the create a flow endpoint. You must specify the flow type and entity details in the request (find this information on our Flow Types guide.

Below is an example API request for generating an employee_form_signing flow. The create a flow endpoint accepts these parameters:

• flow_type: Defines the type of flow being created (for example, employee_form_signing).
• entity_type: Specifies the type of entity (for example, Employee).
• entity_uuid: The unique identifier of the entity for which the flow is being generated.

curl --request POST \
  --url https://api.gusto-demo.com/v1/companies/{{company_uuid}}/flows \
  --header 'Authorization: Bearer COMPANY_ACCESS_TOKEN’' \
  --header 'Content-Type: application/json' \
  --data '{
  "flow_type": "employee_form_signing",
  “entity_type”: “Employee”,
  “entity_uuid”: “{{employee_uuid}}”
}'

Considerations for hosting

• New tab: The flow opens in a separate browser tab, providing a clean and distraction-free environment for users. This is ideal for workflows that require full attention or have multiple steps.
• Embedded via iframe: The flow is integrated into an existing web application using an iframe.
  • Allows seamless user interaction without leaving the main application.
  • Requires handling cross-origin communication using browser API methods like postMessage.

Data persistence

Users navigate through the flow, providing necessary information. Each time a user clicks Save and continue the entered data is saved to Gusto’s database.

📘

For security purposes, Gusto Flows expire after 1 hour of inactivity and automatically deactivate 24 hours from creation time. However you can regenerate the flows at any time to resume onboarding by calling the same endpoint.

If a Flow times out or a user closes the Flow and returns to it later, the Flow will regenerate with any previously-entered data.

2. Set up flow handling

Flows emit flow event JSON objects when users complete specific actions. Events use the browser API postMessage to inform the parent application of user progress.

Applications can listen for flow events to trigger UI updates or navigation changes. To learn more about when flow events are triggered and how to listen for them, see our Flow Events guide.

Example flow event structure

{
  "event": "gusto:flow-finish",
  "metadata": {
    "flowType": "industry_selection",
    "companyUuid": "4206ae3f-5f02-4cac-b22f-3a2676449f2f"
  }
}

3. Account for data dependencies

Many flows have mandatory prerequisites to allow for seamless payroll, onboarding, and tax setup. Understanding these prerequisites helps you implement flows correctly and avoid errors during integration​.

Find a list of all flow dependencies in the Flow Types guide.

Example

For example, the "Add Employees" (add_employees) flow depends on having a registered company address because each employee must be assigned to a physical work location, and the location’s uuid is a required parameter in the job creation API

1. Make the request to generate the add_employees flow, as in this example:

   cURL

   curl --request POST \
     --url https://api.gusto-demo.com/v1/companies/{{company_uuid}}/flows \
     --header 'Authorization: Bearer COMPANY_ACCESS_TOKEN’' \
     --header 'Content-Type: application/json' \
     --data '
   {
     "flow_type": "add_employees"
   }'
   

2. Look at the response and observe how add_addresses is listed in the requirements array.

   JSON

   {
     "title": "Add Your Employees",
     "id": "add_employees",
     "required": true,
     "completed": false,
     "requirements": [
       "add_addresses"
     ]
   }
   

3. Add an address using the add_addresses flow or with the create a company location endpoint, as shown below:

   cURL

   curl --request POST \
     --url https://api.gusto-demo.com/v1/companies/{{company_uuid}}/locations \
     --header 'Authorization: Bearer COMPANY_ACCESS_TOKEN’' \
     --header 'Content-Type: application/json' \
     --data '{
     "phone_number": "8009360383",
     "street_1": "123 Main St",
     "city": "San Francisco",
     "state": "CA",
     "zip": "94105"
   }'
   

4. Make the request to generate the add_employees flow again.

FAQ

Can flows be used with the Embedded API?

Flows can be used on their own or in conjunction with our APIs if you already have UI to collect payroll pertinent information. For example, if you already collect company addresses and employee information, you can pass this information via API and use specific modular Flows to capture the remaining information needed to complete onboarding. Using this hybrid approach, you only need to surface screens that are absolutely necessary to the end-customer.

Can I combine flows?

You can mix and match flow_types in the same category to create custom flows suitable for your needs. To view the categories for flows review the Flow Types guide. You can also rearrange the flow_types in any order you see fit.

📘

Data Dependencies

Please be mindful of data dependencies in each step to achieve the best user experience

To create a custom onboarding flow that only includes add_addresses, add_employees, and sign_all_forms steps, use a comma delimited string.

{  
	flow_type: "add_addresses,add_employees,sign_all_forms"  
}

Next steps

Learn more about how to customize flows, the available flow types, and how to listen for flow events.