---
title: Eligibility Policies | Vitable Docs
description: How eligibility policies control waiting periods and employee classifications to determine when employees become benefits-eligible.
---

An eligibility policy defines the rules that determine when an employee becomes eligible for benefits after being added to an employer’s roster. Each policy specifies a waiting period and an employee classification, and Vitable evaluates these rules automatically when employees are created through census sync.

Each employer can have only **one active eligibility policy** at a time. To change a policy, archive the existing one first, then create a new one.

You create eligibility policies as part of employer setup, before submitting your first census sync. Once a policy is in place, Vitable applies it to every matching employee and fires the `employee.eligibility_granted` webhook when an employee satisfies the waiting period.

## Quick Reference

### Waiting Period Values

| Value                        | Meaning                                           |
| ---------------------------- | ------------------------------------------------- |
| `None`                       | Eligible immediately on hire date                 |
| `1st of the following month` | Eligible on the first day of the month after hire |
| `30 days`                    | Eligible 30 days after hire date                  |
| `60 days`                    | Eligible 60 days after hire date                  |

### Classification Values

| Value       | Applies To               |
| ----------- | ------------------------ |
| `Full time` | Full Time employees only |
| `Part time` | Part Time employees only |
| `All`       | All employee classes     |

### Policy Fields

| Field            | Description                                                       |
| ---------------- | ----------------------------------------------------------------- |
| `id`             | Unique identifier for the policy                                  |
| `employer_id`    | The employer this policy belongs to                               |
| `waiting_period` | One of `None`, `1st of the following month`, `30 days`, `60 days` |
| `classification` | One of `Full time`, `Part time`, `All`                            |
| `active`         | Whether the policy is currently in effect                         |
| `created_at`     | When the policy was created                                       |
| `updated_at`     | When the policy was last modified                                 |

## Understanding the Policy Creation Flow

```
sequenceDiagram
    participant P as Partner
    participant V as Vitable API
    P->>V: POST /v1/employers/{id}/benefit-eligibility-policies
    V-->>P: 200 Policy created
    Note over V: Employees evaluated against policy
    alt Waiting period: None
        V--)P: webhook: employee.eligibility_granted (immediate)
    else Waiting period: 1st of following month / 30 days / 60 days
        Note over V: Waiting period elapses
        V--)P: webhook: employee.eligibility_granted
    end
```

**Diagram summary:** When you create a policy and employees are synced, Vitable checks the waiting period. If `None`, employees are eligible immediately. If `1st of the following month`, they become eligible on the first of the month following their hire date. If `30 days` or `60 days`, they become eligible after that number of days. In all cases, Vitable fires the `employee.eligibility_granted` webhook once the waiting period is satisfied.

## Creating a Policy

To create an eligibility policy, send a request to `POST /v1/employers/{id}/benefit-eligibility-policies` with the `waiting_period` and `classification` fields. Vitable responds with the created policy and fires the `employer.eligibility_policy_created` webhook.

Terminal window

```
curl -X POST https://api.vitablehealth.com/v1/employers/empr_abc123/benefit-eligibility-policies \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "waiting_period": "1st of the following month",
    "classification": "Full time"
  }'
```

You should create your eligibility policy after creating the employer and before submitting a census sync. This ensures that employees are evaluated against the policy as soon as they are created.

For a complete walkthrough of the setup sequence — creating an employer, setting a policy, and submitting a census sync — see the [Employer Onboarding](/embedded_benefits/guides/employer-onboarding/index.md) guide.

### Changing an Existing Policy

Eligibility policies cannot be updated in place. To change an employer’s policy, archive the current policy, then create a new one. Archived policies remain in the system for historical reference but no longer affect eligibility evaluation.

## Understanding Waiting Periods

The `waiting_period` field controls how long after an employee’s hire date they must wait before becoming benefits-eligible. Vitable calculates the eligibility date automatically based on the employee’s `start_date` submitted during census sync (returned as `hire_date` on the employee record).

Here is a concrete example. An employee hired on January 15 would become eligible on the following dates depending on the policy:

| Waiting Period               | Hire Date  | Eligibility Date |
| ---------------------------- | ---------- | ---------------- |
| `None`                       | January 15 | January 15       |
| `1st of the following month` | January 15 | February 1       |
| `30 days`                    | January 15 | February 14      |
| `60 days`                    | January 15 | March 16         |

When the eligibility date arrives, Vitable fires the `employee.eligibility_granted` webhook. This is the signal that the employee’s enrollment window is open and they can begin selecting benefits.

An employee can have an `active` status in the API but not yet be benefits-eligible. Benefits eligibility is not a field on the employee resource — it is signaled exclusively by the `employee.eligibility_granted` and `employee.eligibility_terminated` webhook events.

## Understanding Classifications

The `classification` field determines which employees the policy applies to, based on the `employee_class` value submitted during census sync.

Census sync accepts six employee class values: `Full Time`, `Part Time`, `Temporary`, `Intern`, `Seasonal`, and `Individual Contractor`. The policy `classification` maps to these classes as follows:

| Policy Classification | Matching Employee Classes                                                            |
| --------------------- | ------------------------------------------------------------------------------------ |
| `Full time`           | `Full Time`                                                                          |
| `Part time`           | `Part Time`                                                                          |
| `All`                 | `Full Time`, `Part Time`, `Temporary`, `Intern`, `Seasonal`, `Individual Contractor` |

When Vitable processes a census sync, it matches each employee’s `employee_class` against the `classification` of active policies for that employer. Only employees whose class matches an active policy are evaluated for benefits eligibility.

If you create a policy with `classification` set to `Full time`, employees with any other class — including `Part Time`, `Temporary`, `Intern`, `Seasonal`, and `Individual Contractor` — will not be evaluated for benefits eligibility under that policy. Make sure your policies cover all the employee classes you intend to offer benefits to.

## Troubleshooting

**No matching policy for an employee class.** If an employee is synced with an `employee_class` that does not match any active eligibility policy, that employee will not become benefits-eligible. You will not receive an `employee.eligibility_granted` webhook for them. Verify that your policies cover the employee classes present in your census data.

**Policy created after census sync.** If you submit a census sync before creating an eligibility policy, the synced employees will receive immediate eligibility if the company already has benefits configured. To apply specific waiting period rules, always create your eligibility policy before submitting census data.

**Missed webhook events.** If your endpoint was down when the `employer.eligibility_policy_created` or `employee.eligibility_granted` webhook was sent, you can query `GET /v1/webhook-events` to retrieve missed events. You can also check delivery status for a specific event using `GET /v1/webhook-events/{event_id}/deliveries`. See the [Reliability](/webhooks/reliability/index.md) guide for details on retry behavior.

To confirm which policies are active for an employer, use `GET /v1/benefit-eligibility-policies/{id}` to retrieve a specific policy and check its `active` field.

## Related Webhooks

| Event                                 | Description                                                                                                                                              |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `employer.eligibility_policy_created` | Fired when a new eligibility policy is created for an employer. [Learn more](/webhooks/events/index.md)                                                  |
| `employee.eligibility_granted`        | Fired when an employee satisfies the waiting period and becomes benefits-eligible. [Learn more](/embedded_benefits/concepts/employee-lifecycle/index.md) |
| `employee.eligibility_terminated`     | Fired when an employee’s benefits eligibility is revoked. [Learn more](/embedded_benefits/concepts/employee-lifecycle/index.md)                          |

## Related API Endpoints

- [`POST /v1/employers/{id}/benefit-eligibility-policies`](/api/resources/employers/methods/create_benefit_eligibility_policy/index.md) — Create an eligibility policy for an employer
- [`GET /v1/benefit-eligibility-policies/{id}`](/api/resources/benefit_eligibility_policies/methods/retrieve/index.md) — Retrieve a specific eligibility policy
- [`GET /v1/webhook-events`](/api/resources/webhook_events/methods/list/index.md) — Query webhook events to check for missed notifications
- [`GET /v1/webhook-events/{event_id}/deliveries`](/api/resources/webhook_events/methods/list_deliveries/index.md) — Check delivery status for a specific webhook event