---
title: Employee Lifecycle | Vitable Docs
description: How employees transition between statuses in the Vitable API and which webhook events signal each change.
---

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](/embedded_benefits/concepts/enrollment-lifecycle/index.md) 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](/webhooks/events/index.md)                                                  |
| `employee.eligibility_terminated` | An employee’s benefits eligibility has been revoked. [Learn more](/webhooks/events/index.md)                                           |
| `employee.deactivated`            | An employee has been deactivated (e.g., omitted from census sync, admin termination). [Learn more](/webhooks/events/index.md)          |
| `enrollment.terminated`           | An enrollment has been ended (enrollment moves to `inactive`). [Learn more](/embedded_benefits/concepts/enrollment-lifecycle/index.md) |

## Related API Endpoints

- [`GET /v1/employees/{id}`](/api/resources/employees/methods/retrieve/index.md) — Retrieve an employee’s current data, including `status`, `hire_date`, and `employee_class`.
- [`GET /v1/employers/{id}/employees`](/api/resources/employers/methods/list_employees/index.md) — List all employees for an employer. Supports pagination with `page` and `limit` query parameters.
- [`GET /v1/webhook-events`](/api/resources/webhook_events/methods/list/index.md) — Query webhook events to recover missed events or audit delivery history.
- [`GET /v1/webhook-events/{event_id}/deliveries`](/api/resources/webhook_events/methods/list_deliveries/index.md) — Check delivery attempts for a specific webhook event.