Skip to content
Vitable Docs Vitable Docs Vitable Docs
Embedded Benefits
Guides
Employer Onboarding

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

Step 1: Create an Employer

Section titled “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 for the full request and response schema.

Step 2: Import Employees

Section titled “Step 2: 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

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

Section titled “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

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

Troubleshooting

Section titled “Troubleshooting”
  • No employee.eligibility_granted webhooks after census sync: 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

Section titled “What’s Next”

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

Section titled “Related API Endpoints”