> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.vitablehealth.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.vitablehealth.com/_mcp/server.

# Benefits Administration

> Manage your workforce after setup — update rosters, monitor lifecycle events, and handle payroll deductions.

This guide covers ongoing administration after your initial setup — monitoring employees, updating rosters, handling lifecycle events, and processing payroll deductions.

**Prerequisites:**

* Employer onboarded with employees — see [Employer Onboarding](/embedded_benefits/guides/employer-onboarding)
* Enrollment experience set up — see [Employee Enrollment](/embedded_benefits/guides/employee-enrollment)

## Monitoring Your Workforce

Fetch your employee roster with pagination:

```bash
curl "https://api.vitablehealth.com/v1/employers/{employer_id}/employees?page=1&limit=50" \
  -H "Authorization: Bearer $VITABLE_API_KEY"
```

Each employee has an `active` or `inactive` status. Inactive employees have been deactivated — typically because they were removed in a census sync or terminated by an admin.

See the [List Employees endpoint](/api/employers/list-employees) for the full response schema. For details on status transitions, see the [Employee Lifecycle](/embedded_benefits/concepts/employee-lifecycle) concept page.

## Updating Your Roster

To add, remove, or update employees, re-submit a census sync with the complete, current roster:

```bash
curl -X POST https://api.vitablehealth.com/v1/employers/{employer_id}/census-sync \
  -H "Authorization: Bearer $VITABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "employees": [
      {
        "first_name": "Maria",
        "last_name": "Garcia",
        "date_of_birth": "1990-05-15",
        "email": "maria@beanworks.example.com",
        "phone": "5555550101",
        "reference_id": "emp-001",
        "employee_class": "Full Time"
      }
    ]
  }'
```

> **Warning**
>
> Each census sync **replaces an employer's entire employee roster**. Always submit the full, current list of employees — anyone omitted from the payload will be deactivated. The system matches existing employees using `reference_id` and other available information to preserve their records and enrollment history.

**What happens during a sync:**

* **Matched employees:** Records are updated (e.g., changed `start_date`, `employee_class`)
* **Unmatched existing employees:** Deactivated — you receive `employee.deactivated` events
* **New employees:** Created and evaluated for benefits eligibility
* **Previously deactivated employees:** Reactivated if they reappear in a sync

For the full details on matching behavior, see the [Census Sync](/embedded_benefits/concepts/census-sync) concept page.

See the [Submit Census Sync endpoint](/api/employers/submit-census-sync) for the full request and response schema.

## Employee Lifecycle Events

Listen for these webhook events to track employee status changes:

| Event                             | Meaning                                                 |
| --------------------------------- | ------------------------------------------------------- |
| `employee.eligibility_granted`    | Employee became eligible for benefits                   |
| `employee.eligibility_terminated` | Employee's eligibility was revoked                      |
| `employee.deactivated`            | Employee was deactivated (e.g., removed in census sync) |

For the full set of employee events and what triggers them, see the [Employee Lifecycle](/embedded_benefits/concepts/employee-lifecycle) concept page and the [Webhooks Events](/webhooks/events) page.

## Payroll Deductions

Vitable generates payroll deduction statements on a **monthly schedule** (1st of each month). For each employee with active enrollments, you receive an `employee.deduction_created` webhook event with the deduction details.

Fetch deductions for an employee via the API to configure your payroll system.

For timing expectations, deduction fields, and integration patterns, see the [Payroll Deductions](/embedded_benefits/concepts/payroll-deductions) concept page.

## Webhook Best Practices

* **Verify signatures:** Always verify webhook signatures using HMAC-SHA512. See [Verifying Signatures](/webhooks/signatures).
* **Handle retries:** Vitable retries failed deliveries with exponential backoff, up to 14 attempts. See [Reliability](/webhooks/reliability).
* **Idempotency:** Your endpoint may receive the same event more than once. Handle duplicate deliveries gracefully.

## Embedded Administration UI

Instead of building a custom administration interface with the API, you can embed Vitable's pre-built employer widgets directly into your platform:

* [Employer Benefits Widget](/drops/employer-benefits) — Benefits administration dashboard for managing enrollments and coverage
* [Employer Billing Widget](/drops/employer-billing) — Billing dashboard for invoices, payments, and billing history

Both widgets use **employer-bound** access tokens and handle the full UI experience, so your customers' HR teams can manage benefits without leaving your platform. See the [Vitable Drops](/drops/overview) overview for all available widgets.

## Troubleshooting

* **Employees disappeared after census sync:** Census sync replaces the entire roster for that employer. If employees were omitted from the payload, they were deactivated. Re-submit a sync with the complete list to reactivate them.
* **`employee.deduction_created` not firing:** This event fires on a monthly schedule (1st of each month), not immediately after enrollment. Verify the employee has an active enrollment with status `enrolled` and wait for the next monthly deduction cycle.
* **Webhook deliveries failing:** Check that your endpoint returns a 2xx status within 30 seconds. Vitable retries with exponential backoff up to 14 attempts. See [Webhooks Reliability](/webhooks/reliability) for details.

## Related API Endpoints

* [`GET /v1/employers/{id}/employees`](/api/employers/list-employees) — List employees for an employer
* [`POST /v1/employers/{id}/census-sync`](/api/employers/submit-census-sync) — Submit a census sync
* [`GET /v1/employees/{id}/enrollments`](/api/employees/list-enrollments) — List enrollments for an employee