---
title: Employer Onboarding | Vitable Docs
description: Set up an employer from scratch — create the company, configure eligibility, and import employees.
---

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](/getting-started/authentication/index.md) for details.

## Step 1: Create an Employer

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

Terminal window

```
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](/api/resources/employers/methods/create/index.md) 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.

Terminal window

```
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](/webhooks/events/index.md) page for payload details.

For a deeper understanding of how policies affect eligibility evaluation, see the [Eligibility Policies](/embedded_benefits/concepts/eligibility-policies/index.md) concept page.

See the [Create Eligibility Policy endpoint](/api/resources/employers/methods/create_benefit_eligibility_policy/index.md) 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.

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",
        "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](/api/resources/employers/methods/submit_census_sync/index.md) 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](/webhooks/introduction/index.md) 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](/embedded_benefits/concepts/census-sync/index.md) 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](/webhooks/introduction/index.md) 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](/embedded_benefits/guides/employee-enrollment/index.md) to set up the embedded benefits experience for your employees.

## Related API Endpoints

- [`POST /v1/employers`](/api/resources/employers/methods/create/index.md) — Create an employer
- [`POST /v1/employers/{id}/benefit-eligibility-policies`](/api/resources/employers/methods/create_benefit_eligibility_policy/index.md) — Create an eligibility policy
- [`POST /v1/employers/{id}/census-sync`](/api/resources/employers/methods/submit_census_sync/index.md) — Submit a census sync
- [`GET /v1/employers/{id}/employees`](/api/resources/employers/methods/list_employees/index.md) — List employees for an employer