Employee Lifecycle
Every employee in Vitable moves through a defined lifecycle from creation to termination. Understanding these transitions helps you keep your system in sync with Vitable and respond to changes as they happen. This guide covers the two API statuses, the webhook events that signal lifecycle changes, and how benefits eligibility fits in.
Quick Reference
Employees have a binary status — active or inactive. Eligibility is tracked separately from active status. An employee can be active but not yet eligible (e.g., waiting period in progress).
Understanding Employee Statuses
The GET /v1/employees/{id} endpoint returns one of two values in the status field: active or inactive. There are no other API statuses.
Diagram summary:
- An employee enters the
Activestate when created through a census sync. - While
Active, the employee may receiveemployee.eligibility_grantedoremployee.eligibility_terminatedwebhook events as their benefits eligibility changes. - An employee transitions to
Inactivewhen they are deactivated (e.g., omitted from a census sync, or terminated by an admin). - The
employee.deactivatedwebhook event fires to signal that the employee has been deactivated.
Handling New Hires
When you submit employee data through POST /v1/employers/{id}/census-sync, Vitable creates employee records asynchronously. Each new employee starts with status: "active".
Diagram summary:
- Vitable creates the employee record with
status: "active"after processing the census sync. - Vitable evaluates the employee’s benefits eligibility.
- When an employee becomes eligible, the
employee.eligibility_grantedevent fires.
After the census sync completes, you can verify that employees were created by calling GET /v1/employers/{id}/employees and paginating through the results.
Benefits eligibility is not a field on the employee resource. It is signaled exclusively through webhook events. Listen for the employee.eligibility_granted event to know when an employee can enroll.
Tracking Eligibility Events
Two webhook events track benefits eligibility changes:
-
employee.eligibility_grantedfires when an employee becomes eligible for benefits. Once you receive this event, the employee’s enrollment window opens and they can select benefits. -
employee.eligibility_terminatedfires when an employee’s benefits eligibility is revoked, including as part of a termination flow. After this event, the employee can no longer enroll in new benefits.
You can fetch the employee’s current data at any time with GET /v1/employees/{id} to check fields like employee_class, hire_date, and termination_date.
Handling Terminations
When an employee is terminated, the termination_date field is set and the status changes to inactive. This triggers a cascade of events.
Diagram summary:
- An
Activeemployee transitions toInactivewhen a termination date is set. - The
employee.eligibility_terminatedevent fires, signaling that the employee is no longer eligible for benefits. - The
employee.deactivatedevent fires after termination processing completes. - For each active enrollment, an
enrollment.terminatedevent fires as the enrollment transitions toinactive.
When an employee is deactivated, all of their active enrollments are also ended. Each enrollment transitions from enrolled to inactive, and you receive an enrollment.terminated webhook event for each one. Make sure your system handles these cascading events. See the Enrollment Lifecycle guide for details on enrollment status transitions.
Understanding the Deactivation Event
The employee.deactivated event fires when an employee has been deactivated within Vitable — for example, when they are omitted from a census sync or terminated by an admin. When you fetch the employee after receiving this event, the response shows status: "inactive".
Use this event as confirmation that deactivation processing on Vitable’s side is complete. It is safe to perform any final cleanup in your system (archiving records, removing access, etc.) after receiving employee.deactivated.
Troubleshooting
Missing eligibility events. If your webhook endpoint was down when employee.eligibility_granted fired, you may not know that an employee is eligible for benefits. Use GET /v1/webhook-events to query for missed events within a timeframe, and GET /v1/webhook-events/{event_id}/deliveries to check delivery status.
Unexpected deactivation cascades. A single employee deactivation produces multiple webhook events: employee.eligibility_terminated, employee.deactivated, and one enrollment.terminated per active enrollment. If your handler processes these independently, make sure it handles them idempotently. Use the event_id to deduplicate.
You can always fetch the current state of any employee with GET /v1/employees/{id}. After receiving a webhook event, use the resource_id from the payload to retrieve fresh data rather than relying on cached state.
Related Webhooks
Related API Endpoints
GET /v1/employees/{id}— Retrieve an employee’s current data, includingstatus,hire_date, andemployee_class.GET /v1/employers/{id}/employees— List all employees for an employer. Supports pagination withpageandlimitquery parameters.GET /v1/webhook-events— Query webhook events to recover missed events or audit delivery history.GET /v1/webhook-events/{event_id}/deliveries— Check delivery attempts for a specific webhook event.