Skip to navigation
Embedded BenefitsGuides

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:

Monitoring Your Workforce

Fetch your employee roster with pagination:

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 for the full response schema. For details on status transitions, see the Employee Lifecycle concept page.

Updating Your Roster

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

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 for benefits eligibility
  • Previously deactivated employees: Reactivated if they reappear in a sync

For the full details on matching behavior, see the Census Sync concept page.

See the Submit Census Sync endpoint for the full request and response schema.

Employee Lifecycle Events

Listen for these webhook events to track employee status changes:

EventMeaning
employee.eligibility_grantedEmployee became eligible for benefits
employee.eligibility_terminatedEmployee’s eligibility was revoked
employee.deactivatedEmployee was deactivated (e.g., removed in census sync)

For the full set of employee events and what triggers them, see the Employee Lifecycle concept page and the 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 concept page.

Webhook Best Practices

  • Verify signatures: Always verify webhook signatures using HMAC-SHA512. See Verifying Signatures.
  • Handle retries: Vitable retries failed deliveries with exponential backoff, up to 14 attempts. See 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:

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 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 for details.