---
title: "Change the contractor's onboarding status"
method: PUT
path: "/v1/contractors/{contractor_uuid}/onboarding_status"
tags: ["Contractors"]
---

# Change the contractor's onboarding status

`PUT /v1/contractors/{contractor_uuid}/onboarding_status`

## Request

- Base URL: `https://api.gusto-demo.com`
- URL: `https://api.gusto-demo.com/v1/contractors/{contractor_uuid}/onboarding_status`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/gusto/apis/gusto-api/docs/v1/contractors/:contractor_uuid/onboarding_status/put.ts> (a function with typed inputs; its response is checked against the schema)

Updates a contractor's onboarding status.

Below is a list of valid onboarding status changes depending on the intended action to be performed on behalf of the contractor.

| Action | current onboarding_status | new onboarding_status |
|:------------------|:------------:|----------:|
| Mark a contractor as self-onboarding | `admin_onboarding_incomplete` | `self_onboarding_not_invited` |
| Invite a contractor to self-onboard | `admin_onboarding_incomplete` or `self_onboarding_not_invited` | `self_onboarding_invited` |
| Cancel a contractor's self-onboarding | `self_onboarding_invited` or `self_onboarding_not_invited` | `admin_onboarding_incomplete` |
| Review a contractor's self-onboarded info | `self_onboarding_started` | `self_onboarding_review` |
| Finish a contractor's onboarding | `admin_onboarding_review` or `self_onboarding_review` | `onboarding_completed` |

scope: `contractors:write`

## Path parameters

- `contractor_uuid` string, required

## Headers

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

## Request body

- ContractorOnboardingStatusUpdateRequestBody: Request body for updating a contractor's onboarding status.
  - `onboarding_status` 'admin_onboarding_incomplete' | 'admin_onboarding_review' | 'self_onboarding_not_invited' | 'self_onboarding_invited' | 'self_onboarding_started' | 'self_onboarding_review' | 'onboarding_completed', required: The updated onboarding status for the contractor.

## Response `200`

Successful

- ContractorOnboardingStatus: The representation of an contractor's onboarding status.
  - `uuid` string, required: Unique identifier for this contractor.
  - `onboarding_status` 'onboarding_completed' | 'admin_onboarding_review' | 'admin_onboarding_incomplete' | 'self_onboarding_not_invited' | 'self_onboarding_invited' | 'self_onboarding_started' | 'self_onboarding_review': One of the "onboarding_status" enum values.
  - `onboarding_steps` object[]: List of steps required to onboard a contractor.
    - `title` string: User-friendly description of the onboarding step.
    - `id` string: String identifier for the onboarding step.
    - `required` boolean: When true, this step is required.
    - `completed` boolean: When true, this step has been completed.
    - `requirements` string[]: A list of onboarding steps required to begin this step.

## Other responses

- `404`: Not Found The requested resource does not exist. Make sure the provided UUID is valid.
- `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.dev/gusto/apis/gusto-api.md) - [All operations](https://skmtc.dev/gusto/apis/gusto-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gusto/apis/gusto-api/revisions/f98575fa2a5e?raw)