---
updatedAt: 2026-06-09T21:16:08.000Z
agentTools:
  siteIndex: https://docs.gusto.com/llms.txt
  projectIndex: https://docs.gusto.com/embedded-payroll/llms.txt
---

# Employee self-onboarding

Enable employees to self-onboard into a company

Employee self-onboarding allows employers to delegate part of the onboarding process to employees, saving time and improving data security.

Whether you decide to implement a custom Employee Self-Management experience or use our Flows, it’s important to:

1. Retrieve the employee’s onboarding status to track the completion status of required onboarding steps, and
2. Make the API calls to update these statuses as each is completed.

<Callout icon="📘" theme="info">
  Gusto will not send emails to your end user’s employees. All email or in-app invitations to self-onboard must be incorporated into your Embedded Payroll build.
</Callout>

## Prerequisites

The following information is required to invite an employee to self-onboard:

* First name and last name
* Email
* Start date
* Work address
* Compensation details (including FLSA status, payment amount, and pay frequency)

## How self-onboarding works

1. Employer enters basic employee information.
2. Employer sends the employee an invitation to self-onboard.
3. Employee opens the self-onboarding flow and provides their personal information.
4. Employee submits the form, triggering a notification for the employer.
5. Employer reviews the submitted data and finalizes onboarding. This step includes answering employer-specific state tax questions.

## 1. Create an employee and set them to self-onboarding

Create an employee and set `self_onboarding: true` with the [POST /v1/companies/\{company\_id}/employees](https://docs.gusto.com/embedded-payroll/reference/post-v1-employees) endpoint.

**Sample request**

```curl
curl --request POST \
     --url https://api.gusto-demo.com/v1/companies/<company-uuid>/employees \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>' \
     --header 'content-type: application/json' \
     --data '
{
  "self_onboarding": true,
  "first_name": "John",
  "last_name": "Doe",
  "email": "johndoe@example.com",
}
'
```

**Sample response**

```json
{
  "uuid": "75ca5773-afa4-49b8-8fad-912cc6503ed8",
  "first_name": "John",
  "middle_initial": null,
  "last_name": "Doe",
  "email": johndoe@example.com,
  "company_uuid": "931d085b-cb0a-4608-822a-722444349ead",
  "manager_uuid": null,
  "version": "9fd9f63e0d6487537569075da85a0c7f",
  "current_employment_status": null,
  "onboarding_status": "self_onboarding_pending_invite",
  "preferred_first_name": null,
  "department_uuid": null,
  "employee_code": "c46701",
  "payment_method": "Check",
  "department": null,
  "terminated": false,
  "two_percent_shareholder": null,
  "onboarded": false,
  "historical": false,
  "has_ssn": false,
  "onboarding_documents_config": {
    "uuid": null,
    "i9_document": false
  },
  "jobs": [],
  "eligible_paid_time_off": [],
  "terminations": [],
  "garnishments": [],
  "date_of_birth": null,
  "ssn": "",
  "phone": null,
  "work_email": "johndoe@example.com"
}
```

## 2. Create self-onboarding flow

Create a flow for a given employee to self-onboard using the [POST companies/\{company\_uuid}/flows](https://docs.gusto.com/embedded-payroll/reference/post-v1-company-flows) endpoint.

You need to set the following:

* `flow_type` to `employee_self_management`
* `entity_uuid` to the employee's UUID
* `entity_type` to `Employee`

You will receive a link and need to share it with your end-user’s employee.

**Sample request**

```curl
curl --request POST \
     --url https://api.gusto-demo.com/v1/companies/<company-uuid>/flows \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>' \
     --header 'content-type: application/json' \
     --data '
{
  "flow_type": "employee_self_management",
  "entity_type": "Employee",
  "entity_uuid": "9bc2737d-e0dc-445e-8632-46deada3884e"
}
'
```

**Sample response**

```json
{
  "url": "https://flows.gusto-demo.com/flows/fN4yJDNiJLtMqfdjTzr6ANLzySpA-ImGrA6CqZ1q8cM"
}
```

## 3. Track onboarding progress

Monitor the employee's onboarding status with the [GET /v1/employees/\{employee\_id}/onboarding\_status](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-onboarding_status) endpoint.

This includes the following automatic status transitions:

* `self_onboarding_invited_started` – employee has opened the onboarding link
* `self_onboarding_invited_overdue` – employee has not started within the expected time
* `self_onboarding_completed_by_employee` – employee has finished entering information

> 📘 All onboarding statuses
>
> For the full list of onboarding statuses, see the reference page for [GET /v1/employees/\{employee\_id}/onboarding\_status](https://docs.gusto.com/embedded-payroll/reference/get-v1-employees-employee_id-onboarding_status).

**Sample request**

```curl
curl --request GET \
     --url https://api.gusto-demo.com/v1/employees/<employee-uuid>/onboarding_status \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>'
```

**Sample response**

```json
{
  "uuid": "<employee-uuid>",
  "onboarding_status": "self_onboarding_invited",
  "onboarding_steps": [
    {
      "title": "Personal details",
      "id": "personal_details",
      "required": true,
      "completed": false,
      "requirements": []
    },
    {
      "title": "Enter compensation details",
      "id": "compensation_details",
      "required": true,
      "completed": false,
      "requirements": []
    },
    {
      "title": "Add work address",
      "id": "add_work_address",
      "required": true,
      "completed": false,
      "requirements": []
    },
    {
      "title": "Add home address",
      "id": "add_home_address",
      "required": true,
      "completed": false,
      "requirements": []
    },
    {
      "title": "Enter federal tax withholdings",
      "id": "federal_tax_setup",
      "required": true,
      "completed": false,
      "requirements": []
    },
    {
      "title": "Enter state tax information",
      "id": "state_tax_setup",
      "required": true,
      "completed": false,
      "requirements": [
        "add_work_address",
        "add_home_address"
      ]
    },
    {
      "title": "Direct deposit setup",
      "id": "direct_deposit_setup",
      "required": false,
      "completed": false,
      "requirements": []
    },
    {
      "title": "Employee form signing",
      "id": "employee_form_signing",
      "required": true,
      "completed": false,
      "requirements": [
        "federal_tax_setup",
        "state_tax_setup"
      ]
    },
    {
      "title": "File new hire report",
      "id": "file_new_hire_report",
      "required": true,
      "completed": false,
      "requirements": [
        "add_work_address"
      ]
    },
    {
      "title": "Admin review",
      "id": "admin_review",
      "required": true,
      "completed": false,
      "requirements": [
        "personal_details",
        "compensation_details",
        "add_home_address",
        "add_work_address",
        "federal_tax_setup",
        "state_tax_setup"
      ]
    }
  ]
}
```

## 4. Update onboarding status

As each onboarding step is completed by the employee, update the `“completed”: true` using the [PUT employees/\{employee\_id}/onboarding\_status](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-onboarding_status) endpoint.

When the employee finishes all onboarding steps, the status becomes `self_onboarding_awaiting_admin_review` and notifies the employer.

## 5. Review and finalize the onboarding status

The employer must review the employee’s information and provide required information. When this is done, update the employee’s onboarding status to `onboarding_completed` using the [PUT employees/\{employee\_id}/onboarding\_status](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-onboarding_status) endpoint.

**Sample request**

```curl
curl --request PUT \
     --url https://api.gusto-demo.com/v1/employees/75ca5773-afa4-49b8-8fad-912cc6503ed8/onboarding_status \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>' \
     --header 'content-type: application/json' \
     --data '
{
  "onboarding_status": "onboarding_completed"
}
'
```

**Sample response**

```json
{
  "uuid": "75ca5773-afa4-49b8-8fad-912cc6503ed8",
  "onboarding_status": "onboarding_completed",
  "onboarding_steps": [
    {
      "title": "Personal Details",
      "id": "personal_details",
      "required": true,
      "completed": true,
      "requirements": []
    },
    {
      "title": "Compensation Details",
      "id": "compensation_details",
      "required": true,
      "completed": true,
      "requirements": []
    },
    {
      "title": "Add Home Address",
      "id": "add_home_address",
      "required": true,
      "completed": true,
      "requirements": []
    },
    {
      "title": "Federal Tax Setup",
      "id": "federal_tax_setup",
      "required": true,
      "completed": true,
      "requirements": []
    },
    {
      "title": "Direct Deposit Setup",
      "id": "direct_deposit_setup",
      "required": false,
      "completed": true,
      "requirements": []
    },
    {
      "title": "Employee Form Signing",
      "id": "employee_form_signing",
      "required": true,
      "completed": true,
      "requirements": []
    },
    {
      "title": "Admin Review",
      "id": "admin_review",
      "required": true,
      "completed": true,
      "requirements": []
    }
  ]
}
```

<br />