Get the employee's onboarding status
GET {{baseUrl}}/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.
scope: employees:read
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_reviewfrom 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) |
HEADERS
| Key | Datatype | Required | Description |
|---|---|---|---|
X-Gusto-API-Version | string | Determines the date-based API version associated with your API call. If none is provided, your application's minimum API version is used. | |
Accept | string |
RESPONSES
status: OK
{"uuid":"c44d66dc-c41b-4a60-9e25-5e93ff8583f2","onboarding_status":"admin_onboarding_incomplete","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"]}]}