Transition to support W-2 employees

In Gusto, contractor-only companies are configured to manage contractors exclusively. To accommodate W-2 employees, the company must make the updates described in this guide to ensure compliance with payroll requirements.

1. Update the contractor-only status

To allow W-2 employees and support payroll, update the company’s configuration by setting "contractor_only" to false using the PUT /v1/companies/{company_id} endpoint.

The "contractor_only" attribute can only be changed from true to false.

Sample request

curl --request PUT \
     --url https://api.gusto-demo.com/v1/companies/{company_id} \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
          "contractor_only": false
     }'

2. Complete additional onboarding steps

Once the "contractor_only" status is updated, the following onboarding steps are required before running payroll for W-2 employees:

1. Add employees: Use the add_employees attribute to include all W-2 employees who will be part of the company payroll.
2. Enter state tax information: Use the state_setup attribute to configure state-specific tax details to comply with payroll regulations.
3. Create a pay schedule: Use the payroll_schedule attribute to define the pay period frequency and associated settings for W-2 employees.

To complete these steps, you can launch a flow using the POST /v1/companies/{company_uuid}/flows endpoint.

Sample request

curl --request POST \
     --url 'https://api.gusto-demo.com/v1/companies/{company_uuid}/flows' \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer COMPANY_API_TOKEN'
     --header 'content-type: application/json'
     --data '
{
  "flow_type": "add_employees,state_setup,payroll_schedule"
}

Sample response

{
    "url": "FLOW_URL"
}

3. Verify payroll readiness

After completing the onboarding steps, confirm no payroll blockers are preventing W-2 employee payroll processing by calling the GET /v1/companies/{company_uuid}/payrolls/blockers endpoint.

If the response is an empty array [], the company is ready to process payroll for W-2 employees.

Sample request

curl --request GET \
     --url 'https://api.gusto-demo.com/v1/company/{company_uuid}/payrolls/blockers' \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer COMPANY_API_TOKEN'