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

Status	Triggering Action	Webhook Events
active	Census sync creates the employee	employee.eligibility_granted, employee.eligibility_terminated
inactive	Employee is deactivated (e.g., omitted from census sync, admin termination)	employee.deactivated

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.

sequenceDiagram
    participant P as Partner
    participant V as Vitable
    P->>V: Census sync creates employee
    Note over V: Status: active
    V--)P: webhook: employee.eligibility_granted
    Note over V: Employee may later lose eligibility
    V--)P: webhook: employee.eligibility_terminated
    Note over V: Employee removed from roster
    V--)P: webhook: employee.deactivated
    Note over V: Status: inactive

Diagram summary:

• An employee enters the Active state when created through a census sync.
• While Active, the employee may receive employee.eligibility_granted or employee.eligibility_terminated webhook events as their benefits eligibility changes.
• An employee transitions to Inactive when they are deactivated (e.g., omitted from a census sync, or terminated by an admin).
• The employee.deactivated webhook 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". An employee can be active but not yet eligible for benefits if they are still within a waiting period.

sequenceDiagram
    participant P as Partner
    participant V as Vitable
    P->>V: POST /v1/employers/{id}/census-sync
    V-->>P: 202 Accepted
    Note over V: Employee created (status: active)
    Note over V: Eligibility policy evaluated
    Note over V: Waiting period may apply
    V--)P: webhook: employee.eligibility_granted

Diagram summary:

• Vitable creates the employee record with status: "active" after processing the census sync.
• Vitable evaluates the employer’s eligibility policy. If a waiting period applies, the employee remains active but is not yet benefits-eligible.
• Once the waiting period passes (or immediately if none is configured), the employee.eligibility_granted event 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. An employee can be active but not yet eligible for benefits if they are still within a waiting period. 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_granted fires when an employee becomes eligible for benefits. This typically happens after the employer’s eligibility policy waiting period has passed. Once you receive this event, the employee’s enrollment window opens and they can select benefits.

• employee.eligibility_terminated fires when an employee’s benefits eligibility is revoked. This can happen if an employee’s classification changes (for example, moving from Full Time to a classification not covered by the eligibility policy) or 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.

sequenceDiagram
    participant P as Partner
    participant V as Vitable
    Note over V: Employee is active
    Note over V: Termination date set
    V--)P: webhook: employee.eligibility_terminated
    V--)P: webhook: enrollment.terminated (per enrollment)
    V--)P: webhook: employee.deactivated
    Note over V: Status: inactive

Diagram summary:

• An Active employee transitions to Inactive when a termination date is set.
• The employee.eligibility_terminated event fires, signaling that the employee is no longer eligible for benefits.
• The employee.deactivated event fires after termination processing completes.
• For each active enrollment, an enrollment.terminated event fires as the enrollment transitions to inactive.

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.

Employee active but not eligible. If you see an employee with status: "active" but have not received an employee.eligibility_granted event, the employee is likely still within the eligibility policy’s waiting period. Check the employer’s eligibility policy to understand the configured waiting period.

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

Event	Description
employee.eligibility_granted	An employee has become eligible for benefits. Learn more
employee.eligibility_terminated	An employee’s benefits eligibility has been revoked. Learn more
employee.deactivated	An employee has been deactivated (e.g., omitted from census sync, admin termination). Learn more
enrollment.terminated	An enrollment has been ended (enrollment moves to inactive). Learn more

Related API Endpoints

• GET /v1/employees/{id} — Retrieve an employee’s current data, including status, hire_date, and employee_class.
• GET /v1/employers/{id}/employees — List all employees for an employer. Supports pagination with page and limit query 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.