--- title: "Update a contractor" method: PUT path: "/v1/contractors/{contractor_uuid}" tags: ["Contractors"] --- # Update a contractor `PUT /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` ## Path parameters - `contractor_uuid` string, required ## Headers - `X-Gusto-API-Version` '2026-06-15' ## Request body - ContractorUpdateRequestBody — Request body for updating a contractor. - `version` string, required — The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for information on how to use this field. - `type` 'Individual' | 'Business' — The contractor type. - `wage_type` 'Fixed' | 'Hourly' — The contractor’s wage type. - `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 — 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. - `email` 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 — 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, 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. - `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. ## Response `200` Successful - Contractor — The representation of a contractor (individual or business) in Gusto. - `uuid` string, required — The UUID of the contractor in Gusto. - `company_uuid` string — The UUID of the company the contractor is employed by. - `wage_type` 'Fixed' | 'Hourly' — The contractor's wage type, either "Fixed" or "Hourly". - `is_active` boolean — The status of the contractor with the company. - `version` string — The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for information on how to use this field. - `type` 'Individual' | 'Business' — The contractor's type, either "Individual" or "Business". - `first_name` string, nullable — The contractor’s first name. This attribute is required for “Individual” contractors and will be ignored for “Business” contractors. - `last_name` string, nullable — The contractor’s last name. This attribute is required for “Individual” contractors and will be ignored for “Business” contractors. - `middle_initial` string, nullable — The contractor’s middle initial. This attribute is optional for “Individual” contractors and will be ignored for “Business” contractors. - `business_name` string, nullable — The name of the contractor business. This attribute is required for “Business” contractors and will be ignored for “Individual” contractors. - `ein` string, 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_ein` boolean, nullable — Whether company's Employer Identification Number (EIN) is present - `email` string, nullable — The contractor’s email address. This attribute is optional for “Individual” contractors and will be ignored for “Business” contractors. - `start_date` string — The contractor's start date. - `address` object, nullable — The contractor’s home address. - `street_1` string - `street_2` string, nullable - `city` string - `state` string - `zip` string - `country` string - `hourly_rate` string — The contractor’s hourly rate. This attribute is required if the wage_type is “Hourly”. - `file_new_hire_report` boolean, nullable — The boolean flag indicating whether Gusto will file a new hire report for the contractor - `work_state` string, 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. - `onboarded` boolean — 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_ssn` boolean — Indicates whether the contractor has an SSN in Gusto. - `department_uuid` string, nullable — The UUID of the department the contractor is under - `department` string, nullable — The contractor's department in the company. - `department_title` string, nullable — The title of the contractor's department. - `dismissal_date` string, nullable — The contractor's dismissal date. - `upcoming_employment` object, nullable — The contractor's upcoming employment details, if a rehire is scheduled. - `start_date` string — The start date of the upcoming employment. - `setup_status` string, nullable — The setup status of the upcoming employment. - `dismissal_cancellation_eligible` boolean — Whether the contractor's pending dismissal can be cancelled. - `rehire_cancellation_eligible` boolean — Whether the contractor's pending rehire can be cancelled. - `member_portal_invitation_status` object, nullable — Member portal invitation status information. Only included when the include param has the portal_invitations value set. - `status` 'pending' | 'sent' | 'verified' | 'complete' | 'cancelled' — The current status of the member portal invitation. - `token_expired` boolean, nullable — Whether the invitation token has expired. - `welcome_email_sent_at` string, date-time, nullable — The date and time when the welcome email was sent. - `last_password_resent_at` string, date-time, nullable — The date and time when the password reset was last resent. - `partner_portal_invitation_sent` boolean, 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. ## Other responses - `404` — Not Found The requested resource does not exist. Make sure the provided UUID is valid. - `409` — Conflict - `422` — Unprocessable 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](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details. --- [API](https://skmtc.net/gusto/apis/gusto-api.md) · [All operations](https://skmtc.net/gusto/apis/gusto-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gusto/gusto-api/revisions/826dfa57fb3b/schema)