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

# Get the employee's onboarding status

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

# Description
Retrieves an employee'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 complete the full employee-onboarding. |
| `onboarding_completed` | Employee has been fully onboarded and verified. |

### Employee self-onboarding
| onboarding_status | Description |
|:------------------|------------:|
| `admin_onboarding_incomplete` | Admin needs to enter basic information about the employee. |
| `self_onboarding_pending_invite` | Admin has the intention to invite the employee to self-onboard (e.g., marking a checkbox), but the system has not yet sent the invitation. |
| `self_onboarding_invited` | Employee has been sent an invitation to self-onboard. |
| `self_onboarding_invited_started` | Employee has started the self-onboarding process. |
| `self_onboarding_invited_overdue` | Employee's start date has passed, and employee has still not completed self-onboarding. |
| `self_onboarding_completed_by_employee` | Employee has completed entering in their information. The status should be updated via API to "self_onboarding_awaiting_admin_review" from here, once the Admin has started reviewing. |
| `self_onboarding_awaiting_admin_review` | Admin has started to verify the employee's information. |
| `onboarding_completed` | Employee has been fully onboarded and verified. |

## onboarding_steps

| onboarding_steps | Requirement(s) to be completed |
|:-----------------|-------------------------------:|
| `personal_details` | Add employee's first name, last name, email, date of birth, social security number |
| `compensation_details` | Associate employee to a job & compensation. |
| `add_work_address` | Add employee work address. |
| `add_home_address` | Add employee home address. |
| `federal_tax_setup` | Set up federal tax withholdings. |
| `state_tax_setup` | Set up state tax withholdings. |
| `direct_deposit_setup` | (optional) Set up employee's direct deposit. |
| `employee_form_signing` | Employee forms (e.g., W4, direct deposit authorization) are generated & signed. |
| `file_new_hire_report` | File a new hire report for this employee. |
| `admin_review` | Admin reviews & confirms employee details (only required for Employee self-onboarding) |

scope: `employees:read`

## Path parameters

- `employee_id` string, required

## Headers

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

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

---

[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/versions/826dfa57fb3b/schema)