Update a contractor

put

https://api.gusto-demo.com/v1/contractors/{contractor_uuid}

Update a contractor.

Warning

Watch out when changing a contractor's type (when the contractor is finished onboarding). Specifically, changing contractor type can be dangerous since Gusto won't recognize and file two separate 1099s if they simply change from business to individual

scope: contractors:write

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

contractor_uuid

string

required

The UUID of the contractor

Body Params

version

string

required

The current version of the object. See the versioning guide for information on how to use this field.

type

string

enum

Defaults to Individual

The contractor type.

Allowed:

wage_type

string

enum

The contractor’s wage type.

Allowed:

start_date

string

The day when the contractor will start working for the company.

hourly_rate

string

The contractor’s hourly rate. This attribute is required if the wage_type is Hourly.

self_onboarding

boolean

Defaults to false

Whether the contractor or the payroll admin will complete onboarding in Gusto. Self-onboarding is recommended so that contractors receive Gusto accounts. If self_onboarding is true, then email is required.

string

The contractor’s email address.

first_name

string

The contractor’s first name. This attribute is required for Individual contractors and will be ignored for Business contractors.

last_name

string

The contractor’s last name. This attribute is required for Individual contractors and will be ignored for Business contractors.

middle_initial

string

The contractor’s middle initial. This attribute is optional for Individual contractors and will be ignored for Business contractors.

file_new_hire_report

boolean

Defaults to false

The boolean flag indicating whether Gusto will file a new hire report for the contractor. This attribute is optional for Individual contractors and will be ignored for Business contractors.

work_state

string | null

State where the contractor will be conducting the majority of their work for the company. This value is used when generating the new hire report. This attribute is required for Individual contractors if file_new_hire_report is true and will be ignored for Business contractors.

ssn

string

This attribute is optional for Individual contractors and will be ignored for Business contractors. Social security number is needed to file the annual 1099 tax form.

business_name

string

The name of the contractor business. This attribute is required for Business contractors and will be ignored for Individual contractors.

ein

string

The employer identification number of the contractor business. This attribute is optional for Business contractors and will be ignored for Individual contractors.

is_active

boolean

The status of the contractor. If the contractor's start date is in the future, updating this field to true means we are setting the start date to today. Attempting to deactivate a contractor while a dismissal is already scheduled, or reactivate while a rehire is already scheduled, will return a 422 error. Cancel the pending transition first using the appropriate cancel endpoint.

Headers

X-Gusto-API-Version

string

enum

Defaults to 2026-02-01

Determines the date-based API version associated with your API call. If none is provided, your application's minimum API version is used.

Allowed:

Responses

200Successful

404Not Found The requested resource does not exist. Make sure the provided UUID is valid.

422Unprocessable Entity This may happen when the body of your request contains errors such as invalid_attribute_value, or the request fails due to an invalid_operation. See the Errors Categories guide for more details.