Eligibility Policies

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.

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 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 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
employee.eligibility_granted	Fired when an employee satisfies the waiting period and becomes benefits-eligible. Learn more
employee.eligibility_terminated	Fired when an employee’s benefits eligibility is revoked. Learn more

Related API Endpoints

• POST /v1/employers/{id}/benefit-eligibility-policies — Create an eligibility policy for an employer
• GET /v1/benefit-eligibility-policies/{id} — Retrieve a specific eligibility policy
• GET /v1/webhook-events — Query webhook events to check for missed notifications
• GET /v1/webhook-events/{event_id}/deliveries — Check delivery status for a specific webhook event