---
title: "Update the employee's onboarding status"
method: PUT
path: "/v1/employees/{employee_id}/onboarding_status"
tags: ["Employees"]
---

# Update the employee's onboarding status

`PUT /v1/employees/{employee_id}/onboarding_status`

## Request

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

Updates an employee's onboarding status.
Below is a list of valid onboarding status changes depending on the intended action to be performed on behalf of the employee.

| Action | current onboarding_status | new onboarding_status |
|:------------------|:------------:|----------:|
| Mark an employee as self-onboarding | `admin_onboarding_incomplete` | `self_onboarding_pending_invite` |
| Invite an employee to self-onboard | `admin_onboarding_incomplete` or `self_onboarding_pending_invite` | `self_onboarding_invited` |
| Cancel an employee's self-onboarding | `self_onboarding_invited` or `self_onboarding_pending_invite` | `admin_onboarding_incomplete` |
| Review an employee's self-onboarded info | `self_onboarding_completed_by_employee` | `self_onboarding_awaiting_admin_review` |
| Finish an employee's onboarding | `admin_onboarding_incomplete` or `self_onboarding_awaiting_admin_review` | `onboarding_completed` |

scope: `employees:manage`

## Path parameters

- `employee_id` string, required

## Headers

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

## Request body

- object
  - `onboarding_status` 'admin_onboarding_incomplete' | 'self_onboarding_pending_invite' | 'self_onboarding_invited' | 'self_onboarding_invited_started' | 'self_onboarding_invited_overdue' | 'self_onboarding_completed_by_employee' | 'self_onboarding_awaiting_admin_review' | 'onboarding_completed', required: Onboarding status value

## Response `200`

successful

- EmployeeOnboardingStatus: The representation of an employee's onboarding status.
  - `uuid` string, required: Unique identifier for this employee.
  - `onboarding_status` string: One of the "onboarding_status" enum values.
  - `onboarding_steps` object[]: List of steps required to onboard an employee.
    - `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.
  - `blockers` object[]: Validation issues that should be resolved before this employee's onboarding is complete. Each entry identifies an affected field, a category describing the type of problem, and a human-readable message. Supported categories: - `duplicate_value`: Another employee in the same company already has this value. To resolve, cancel this onboarding and initiate a rehire if it's a returning employee, or contact support to investigate the conflict. This list may grow over time as new validation rules are added.
    - `field` 'ssn': The employee field affected.
    - `category` 'duplicate_value': Category of the blocker. See the array-level description for resolution guidance.
    - `message` string: Human-readable description of the blocker.

## Other responses

- `404`: Not Found The requested resource does not exist. Make sure the provided UUID is valid.
- `422`: invalid status transition

---

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