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

# Employer Onboarding

> Set up an employer from scratch — create the company and import employees.

This guide walks you through onboarding a new employer in two steps: create the employer and import employees via census sync.

Before you begin, make sure you have a valid API key. See [Authentication](/getting-started/authentication) for details.

#### Create an Employer

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

```bash
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/employers/create) for the full request and response schema.

#### 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.

```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",
        "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`

> **Warning**
>
> 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/employers/submit-census-sync) 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. Benefits eligibility is evaluated
3. For each employee who qualifies, an `employee.eligibility_granted` webhook fires

> **Warning**
>
> 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.

> **Tip**
>
> Always verify your [webhook endpoint](/webhooks) 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) concept page.

## Troubleshooting

* **No `employee.eligibility_granted` webhooks after census sync:** Verify your webhook endpoint is configured and reachable via the [Webhooks](/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](/embedded_benefits/guides/employee-enrollment) to set up the embedded benefits experience for your employees.

## Related API Endpoints

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