Employer Onboarding

This guide walks you through onboarding a new employer in three steps: create the employer, set an eligibility policy, and import employees via census sync. By the end, your employer will be fully configured and employees will be processing for benefits eligibility.

Before you begin, make sure you have a valid API key. See Authentication for details.

Step 1: Create an Employer

Create a new employer by sending their company details to the API.

curl -X POST https://api.vitablehealth.com/v1/employers \
  -H "Authorization: Bearer $VITABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bean Works Coffee",
    "legal_name": "Bean Works Coffee LLC",
    "ein": "00-0000000",
    "email": "admin@beanworks.example.com",
    "phone_number": "+15555550100",
    "reference_id": "your-internal-id-123",
    "address": {
      "address_line_1": "123 Main Street",
      "city": "Austin",
      "state": "TX",
      "zipcode": "78701"
    }
  }'

The reference_id field lets you map this employer to your own internal identifier. It is optional but recommended.

See the Create Employer endpoint for the full request and response schema.

Step 2: Create an Eligibility Policy

An eligibility policy defines which employees qualify for benefits and how long they must wait.

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

Classification options: Full time, Part time, All

Waiting period options: 1st of the following month, 30 days, 60 days, None

Each employer can have only one active eligibility policy. Attempting to create a second will fail with a 422 error. To change an employer’s policy, archive the existing one first, then create a new one.

Webhook: After successful creation, you will receive an employer.eligibility_policy_created event. See the Webhooks Events page for payload details.

For a deeper understanding of how policies affect eligibility evaluation, see the Eligibility Policies concept page.

See the Create Eligibility Policy endpoint for the full request and response schema.

Step 3: Import Employees

Submit your employee roster using census sync. This is an asynchronous operation — the request is validated immediately and employees are processed in the background.

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",
        "start_date": "2024-01-15",
        "employee_class": "Full time"
      },
      {
        "first_name": "James",
        "last_name": "Chen",
        "date_of_birth": "1985-11-22",
        "email": "james@beanworks.example.com",
        "phone": "5555550102",
        "reference_id": "emp-002"
      }
    ]
  }'

Required fields per employee: first_name, last_name, date_of_birth, email, phone

Optional fields: reference_id, address, start_date, employee_class, compensation_type

Census sync replaces an employer’s entire employee roster. Employees not included in the new payload will be deactivated. This is not an append operation — always submit the complete, current list of employees.

Limits: Minimum 1 employee, maximum 5,000. Each reference_id must be unique within the payload.

Response: 202 Accepted with an accepted_at timestamp confirming the sync was queued.

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

What Happens Next

After your census sync is accepted, Vitable processes employees asynchronously:

1. Each employee is validated and created (or matched to an existing record)
2. Eligibility is evaluated against your employer’s policy
3. For each employee who qualifies, an employee.eligibility_granted webhook fires

If the employer has no eligibility policy, all employees are granted eligibility immediately. If a policy exists with a waiting period, eligibility is granted when the waiting period expires.

There is no sync-completion webhook. There is no single event that signals the entire census sync is done. Listen for individual employee.eligibility_granted events to track progress.

Always verify your webhook endpoint is configured and reachable before submitting a census sync, so you receive eligibility events as they fire.

For details on how employees are matched across syncs, see the Census Sync concept page.

Troubleshooting

• 422 when creating eligibility policy: You already have an active policy for this employer. Archive the existing one first, then create the new one.
• No employee.eligibility_granted webhooks after census sync: If the employer has an eligibility policy with a waiting period, eligibility is not granted immediately — events fire when the waiting period expires. Also verify your webhook endpoint is configured and reachable via the Webhooks section.
• Census sync returns 400: Check that all employees have the required fields (first_name, last_name, date_of_birth, email, phone) and that reference_id values are unique within the payload.

What’s Next

Proceed to Employee Enrollment to set up the embedded benefits experience for your employees.

Related API Endpoints

• POST /v1/employers — Create an employer
• POST /v1/employers/{id}/benefit-eligibility-policies — Create an eligibility policy
• POST /v1/employers/{id}/census-sync — Submit a census sync
• GET /v1/employers/{id}/employees — List employees for an employer