Guides

Employee self-onboarding

Enable employees to self-onboard into a company

Suggest Edits

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.

📘

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.

Prerequisites

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

  • First name and last name
  • 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 endpoint.

Sample request

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": "[email protected]",
}
'

Sample response

{
  "uuid": "75ca5773-afa4-49b8-8fad-912cc6503ed8",
  "first_name": "John",
  "middle_initial": null,
  "last_name": "Doe",
  "email": [email protected],
  "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": "[email protected]"
}

2. Create self-onboarding flow

Create a flow for a given employee to self-onboard using the POST companies/{company_uuid}/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 --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

{
  "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 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.

Sample request

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

{
  "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 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 endpoint.

Sample request

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

{
  "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": []
    }
  ]
}

Updated 1 day ago