GuidesAPI ReferenceChangelogAPI PolicyAPI StatusGusto Security

Onboarding Flows (Pre-built UI)

Try It Now

The purpose of this Onboarding Demo is to see the Flows in action without needing API keys. If you intend to make API calls after onboarding a company, you should create a Partner Managed Company and make the API call to generate Flows.


Gusto Embedded Payroll Flows are embeddable pre-built UI flows that allow you to easily onboard company and employee information needed to set up a customer for payroll. Flows can be used to accelerate your time to market and save your team weeks of engineering resources.


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.

Gusto supports an end-to-end Company Onboarding Flow to capture all of the company and employee information needed for payroll as well as individual onboarding steps via modular Flows.

flow_typeentity_typeentity_uuidFlow descriptionRequirements
company_onboardingn/an/aFull company onboarding flown/a
add_addressesn/an/aManage company's work, mailing, and filing addressesn/a
federal_tax_setupn/an/aReview and update company federal tax detailsn/a
select_industryn/an/aSelect the company industryn/a
add_bank_infon/an/aAdd bank info manually or via Plaidn/a
verify_bank_infon/an/aBank deposits verificationadd_bank_info
add_employeesn/an/aManage all employee onboardingadd_addresses
state_setupn/an/aReview and update company state taxesadd_addresses, add_employees
payroll_schedulen/an/aSet company's payroll schedulen/a
sign_all_formsn/an/aAdd signatory and sign company documentsadd_employees, federal_tax_setup, state_setup, add_bank_info, payroll_schedule
employee_form_signing'Employee'employee's UUIDFor employee to review and sign documentsadd_employees

How To Use Flows

Flows can be hosted in a new tab or iframed into your application. Flows are generated via API call to our Flows endpoint. For security purposes, all generated flows will expire within 1 hour of inactivity. Additionally, flows will be deactivated 24 hours from creation time, however you can regenerate the flows at any time to resume onboarding by calling the same endpoint.

Request Sample:

curl --request POST \
  --url{{company_uuid}}/flows \
  --header 'Authorization: Bearer {{access_token}}’' \
  --header 'Content-Type: application/json' \
  --data '{
  "flow_type": "employee_form_signing",
  “entity_type”: “Employee”,
  “entity_uuid”: “{{employee_uuid}}”


Some onboarding steps require other onboarding steps to be completed in advance. If you plan to leverage specific modular flows, it’s important that you take into account these prerequisites to ensure the Flow you’re leveraging will work as intended. You can reference the table above or call the get the company's onboarding status endpoint to identify what steps of onboarding must be completed in advance.

For example, if you plan to use the Add Employees Flow, you need to Add Addresses since a location_id is needed to create a job for an employee. The company work locations can be created via API call or by using the Add Addresses Flow.

Get the company’s onboarding status response example:

      "title": "Add Your Employees",
      "id": "add_employees",
      "required": true,
      "completed": true,
      "requirements": [

From this response you can see add_addresses is required to Add Employees. This is because a location_id (address) is required to create a job for an employee which is necessary to complete the Add Employee flow.

Create a job request example:

  "title": "Regional Manager",
  "location_id": 1363316536327002,
  "hire_date": "2020-12-21"

Completing Onboarding

If you plan on using the Company Onboarding Flow, there is a step to ‘Complete Setup’ which will finalize the onboarding process and kick off Gusto’s company verification process. If you plan on using APIs, or APIs and modular Flows, you will need to call get the company's onboarding status to ensure all onboarding steps are completed and, if applicable, make another call to finish company onboarding to initiate this process.

Finishing company onboarding automatically triggers Gusto’s internal approval process which must be completed before a company can process payroll. The approval process can take up to one business day so it is recommended that company onboarding is completed accordingly to ensure employees are paid on time. You can check the company’s approval status using our Get a company endpoint where "company_status": "Approved".

If you need to make any changes to company or employee info post onboarding, you can recall the Flows to make the necessary adjustments. State tax information cannot be edited via Flows so you must contact Support.