---
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`

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