---
title: Benefits Administration | Vitable Docs
description: 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/index.md)
- Enrollment experience set up — see [Employee Enrollment](/embedded_benefits/guides/employee-enrollment/index.md)

## Monitoring Your Workforce

Fetch your employee roster with pagination:

Terminal window

```
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/resources/employers/methods/list_employees/index.md) for the full response schema. For details on status transitions, see the [Employee Lifecycle](/embedded_benefits/concepts/employee-lifecycle/index.md) concept page.

## Updating Your Roster

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

Terminal window

```
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"
      }
    ]
  }'
```

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 against the employer’s eligibility policy
- **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/index.md) concept page.

See the [Submit Census Sync endpoint](/api/resources/employers/methods/submit_census_sync/index.md) 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/index.md) concept page and the [Webhooks Events](/webhooks/events/index.md) 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/index.md) concept page.

## Webhook Best Practices

- **Verify signatures:** Always verify webhook signatures using HMAC-SHA512. See [Verifying Signatures](/webhooks/signatures/index.md).
- **Handle retries:** Vitable retries failed deliveries with exponential backoff, up to 14 attempts. See [Reliability](/webhooks/reliability/index.md).
- **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/index.md) — Benefits administration dashboard for managing enrollments and coverage
- [Employer Billing Widget](/drops/employer-billing/index.md) — 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/index.md) 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/index.md) for details.

## Related API Endpoints

- [`GET /v1/employers/{id}/employees`](/api/resources/employers/methods/list_employees/index.md) — List employees for an employer
- [`POST /v1/employers/{id}/census-sync`](/api/resources/employers/methods/submit_census_sync/index.md) — Submit a census sync
- [`GET /v1/employees/{id}/enrollments`](/api/resources/employees/methods/list_enrollments/index.md) — List enrollments for an employee