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

# Get the contractor's onboarding status

`GET /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/get.ts> (a function with typed inputs; its response is checked against the schema)

Retrieves a contractor's onboarding status. The data returned helps inform the required onboarding steps and respective completion status.

## onboarding_status

### Admin-facilitated onboarding
| onboarding_status | Description |
|:------------------|------------:|
| `admin_onboarding_incomplete` | Admin needs to enter basic information about the contractor. |
| `admin_onboarding_review` | All information has been completed and admin needs to confirm onboarding. |
| `onboarding_completed` | Contractor has been fully onboarded and verified. |

### Contractor self-onboarding

| onboarding_status | Description |
| --- | ----------- |
| `admin_onboarding_incomplete` | Admin needs to enter basic information about the contractor. |
| `self_onboarding_not_invited` | Admin has the intention to invite the contractor to self-onboard (e.g., marking a checkbox), but the system has not yet sent the invitation. |
| `self_onboarding_invited` | Contractor has been sent an invitation to self-onboard. |
| `self_onboarding_started` | Contractor has started the self-onboarding process. |
| `self_onboarding_review` | Admin needs to review contractors's entered information and confirm onboarding. |
| `onboarding_completed` | Contractor has been fully onboarded and verified. |

## onboarding_steps

| onboarding_steps | Requirement(s) to be completed |
|:-----------------|-------------------------------:|
| `basic_details` | Add individual contractor's first name, last name, social security number or Business name and EIN depending on the contractor type |
| `add_address` | Add contractor address. |
| `compensation_details` | Add contractor compensation. |
| `payment_details` | (optional) Set up contractor's direct deposit or set to check. |
| `sign_documents` | Contractor forms (e.g., W9) are generated & signed. |
| `file_new_hire_report` | Contractor new hire report is generated. |

scope: `contractors:read`

## Path parameters

- `contractor_uuid` string, required

## Headers

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

## 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.

---

[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)