GUgusto
Contractors

Update a contractor

Changed on

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

put/v1/contractors/{contractor_uuid}

Request

Path parameters

contractor_uuidstring required

The UUID of the contractor

Headers

X-Gusto-API-Version'2026-06-15'

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

Request body

versionstring required

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

type'Individual' | 'Business'

The contractor type.

wage_type'Fixed' | 'Hourly'

The contractor’s wage type.

start_datestring

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

hourly_ratestring

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

self_onboardingboolean

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.

emailstring

The contractor’s email address.

work_emailstring

The work email address of the contractor. This is provided to support syncing users between our system and yours. You may not use this email address for any other purpose (e.g. marketing).

first_namestring

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

last_namestring

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

middle_initialstring

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

file_new_hire_reportboolean

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_statestring nullable

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.

ssnstring

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_namestring

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

einstring

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

is_activeboolean

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.

Example request

{
  "version": "56d00c178bc7393b2a206ed6a86afcb4",
  "start_date": "2020-01-11",
  "hourly_rate": "40.0"
}

Response

Successful

uuidstring required

The UUID of the contractor in Gusto.

company_uuidstring

The UUID of the company the contractor is employed by.

wage_type'Fixed' | 'Hourly'

The contractor's wage type, either "Fixed" or "Hourly".

is_activeboolean

The status of the contractor with the company.

versionstring

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

type'Individual' | 'Business'

The contractor's type, either "Individual" or "Business".

first_namestring nullable

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

last_namestring nullable

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

middle_initialstring nullable

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

business_namestring nullable

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

einstring nullable

The Federal Employer Identification Number of the contractor business. This attribute is optional for “Business” contractors and will be ignored for “Individual” contractors.

has_einboolean nullable

Whether company's Employer Identification Number (EIN) is present

emailstring nullable

The contractor’s email address. This attribute is optional for “Individual” contractors and will be ignored for “Business” contractors.

work_emailstring nullable

The work email address of the contractor. This is provided to support syncing users between our system and yours. You may not use this email address for any other purpose (e.g. marketing).

start_datestring

The contractor's start date.

hourly_ratestring

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

file_new_hire_reportboolean nullable

The boolean flag indicating whether Gusto will file a new hire report for the contractor

work_statestring nullable

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.

onboardedboolean

The updated onboarding status for the contractor

onboarding_status'admin_onboarding_incomplete' | 'admin_onboarding_review' | 'self_onboarding_not_invited' | 'self_onboarding_invited' | 'self_onboarding_started' | 'self_onboarding_review' | 'onboarding_completed'

One of the "onboarding_status" enum values.

payment_method'Direct Deposit' | 'Check' nullable

The contractor's payment method.

has_ssnboolean

Indicates whether the contractor has an SSN in Gusto.

department_uuidstring nullable

The UUID of the department the contractor is under

departmentstring nullable

The contractor's department in the company.

department_titlestring nullable

The title of the contractor's department.

dismissal_datestring nullable

The contractor's dismissal date.

dismissal_cancellation_eligibleboolean

Whether the contractor's pending dismissal can be cancelled.

rehire_cancellation_eligibleboolean

Whether the contractor's pending rehire can be cancelled.

partner_portal_invitation_sentboolean nullable

Whether an external partner portal invitation webhook has been sent for this contractor. Only included when the include param has the portal_invitations value set.

Example response

{
  "hourly_rate": "50.0"
}

Changes

  • f98575fa2a5eRevision changes
    • info

      added the new optional request property ////

    • info

      added the optional property to the response with the status