List employers

GET/v1/employers

Returns the caller’s employer book — every employer with its computed columns (enrollment-rate summary, benefit-family tags, HRIS connection, benefit-lifecycle stage) merged with the employer’s flat CRM fields (legal name, EIN, contact, address, timestamps). The book is derived from the authenticated principal: one organization’s employers, or every organization’s for a caller whose reach is not a single organization. Supports search by display name, legal name or exact EIN, benefit-family/lifecycle/HRIS filters, and page/limit pagination.

Query ParametersExpand Collapse

benefit_family: optional array of "mec" or "mvp" or "ichra" or 3 more

Filter to employers with at least one active benefit in these families.

One of the following:

"mec"

"mvp"

"ichra"

"vpc"

"dental"

"vision"

benefit_lifecycle_stage: optional array of "open_enrollment" or "renewal" or "active" or 2 more

Filter to employers in one of these computed benefit-lifecycle stages.

One of the following:

"open_enrollment"

"renewal"

"active"

"onboarding"

"cancelled"

hris_provider: optional array of string

Filter to employers whose HRIS connection is with one of these payroll providers (e.g. ADP RUN). Matched case-insensitively; free text, so read the available values from the HRIS-providers endpoint rather than assuming a fixed set.

hris_status: optional array of "Pending" or "Active" or "Inactive" or 2 more

Filter to employers whose HRIS connection is in one of these statuses.

One of the following:

"Pending"

"Active"

"Inactive"

"Paused"

"Terminated"

include_cancelled: optional boolean

Include cancelled employers (hidden by default unless their stage is explicitly requested).

limit: optional number

Items per page.

minimum1

maximum100

page: optional number

Page number.

minimum1

search: optional string

Employer filter. Matches the display name or the legal name case-insensitively as a substring, or the EIN exactly (with or without its dash).

minLength1

ReturnsExpand Collapse

data: array of { active, address, benefit_families, 13 more }

active: boolean

Whether the employer is currently active in the system.

address: { address_line_1, address_line_2, city, 2 more }

Shared read serializer for a postal address on public API responses.

One definition for the address block every public resource emits (employer, employee, …), so the 5-field shape isn’t hand-rolled per endpoint. Read-only: it renders an already-built address value object (e.g. AddressDVO) whose attributes map 1:1 to these fields.

address_line_1: string

Primary street address.

address_line_2: string

Secondary street address (apt, suite, etc.).

city: string

City name.

state: string

Two-letter state code (e.g. CA, NY).

zipcode: string

ZIP code (5 or 9 digit).

benefit_families: array of string

Distinct benefit-family tags across the employer’s active benefits (e.g. MEC, ICHRA, VPC).

benefit_lifecycle_stage: { as_of_date, stage }

as_of_date: string

Anchor date for the stage (e.g. renewal date); null when not applicable.

formatdate

stage: string

Computed employer benefit-lifecycle stage: open_enrollment, renewal, active, onboarding, or cancelled.

created_at: string

Timestamp when the employer was created.

formatdate-time

ein: string

Employer Identification Number (masked in responses).

email: string

Email address for billing and communications.

formatemail

employer_id: string

Prefixed employer identifier (empr_<base64-encoded-uuid>).

enrollment_rate_summary: { eligible, enrolled, percentage }

Enrolled/eligible employees roll-up.

eligible: number

Employees eligible for at least one active benefit.

enrolled: number

Employees enrolled in at least one active benefit.

percentage: number

enrolled / eligible as a whole-number percent (0 when none eligible).

hris_status: { provider, provider_label, status }

HRIS connection, or null when the employer has none.

provider: string

Id of the HRIS/payroll provider the employer is connected to (e.g. paylocity).

provider_label: string

Display name of that provider (e.g. Paylocity).

status: string

Connection status reported by the integration.

legal_name: string

Legal business name for compliance and tax purposes.

name: string

Employer name.

organization_id: string

ID of the parent organization (org_*), or null when unknown.

phone_number: string

Employer phone number.

reference_id: string

The organization’s own reference id for this employer, or null when none was assigned.

updated_at: string

Timestamp when the employer was last updated.

formatdate-time

pagination: Pagination { limit, page, total, total_pages }

Pagination metadata for list responses.

limit: number

Items per page

page: number

Current page number

total: number

Total number of items

total_pages: number

Total number of pages

List employers

curl https://api.vitablehealth.com/v1/employers \
    -H "Authorization: Bearer $VITABLE_CONNECT_API_KEY"

{
  "data": [
    {
      "employer_id": "empr_abc123def456",
      "organization_id": "org_xyz789",
      "reference_id": "partner-emp-001",
      "name": "Acme Corporation",
      "legal_name": "Acme Corporation Inc.",
      "ein": "XX-XXX1234",
      "email": "hr@acme.com",
      "phone_number": "4155550100",
      "active": true,
      "address": {
        "address_line_1": "123 Main Street",
        "address_line_2": "Suite 100",
        "city": "San Francisco",
        "state": "CA",
        "zipcode": "94102"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-06-20T14:45:00Z",
      "enrollment_rate_summary": {
        "eligible": 84,
        "enrolled": 78,
        "percentage": 93
      },
      "benefit_families": [
        "MEC",
        "ICHRA"
      ],
      "hris_status": {
        "provider": "paychex_flex",
        "provider_label": "Paychex Flex",
        "status": "Active"
      },
      "benefit_lifecycle_stage": {
        "stage": "active",
        "as_of_date": "2026-12-31"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}

Returns Examples

{
  "data": [
    {
      "employer_id": "empr_abc123def456",
      "organization_id": "org_xyz789",
      "reference_id": "partner-emp-001",
      "name": "Acme Corporation",
      "legal_name": "Acme Corporation Inc.",
      "ein": "XX-XXX1234",
      "email": "hr@acme.com",
      "phone_number": "4155550100",
      "active": true,
      "address": {
        "address_line_1": "123 Main Street",
        "address_line_2": "Suite 100",
        "city": "San Francisco",
        "state": "CA",
        "zipcode": "94102"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-06-20T14:45:00Z",
      "enrollment_rate_summary": {
        "eligible": 84,
        "enrolled": 78,
        "percentage": 93
      },
      "benefit_families": [
        "MEC",
        "ICHRA"
      ],
      "hris_status": {
        "provider": "paychex_flex",
        "provider_label": "Paychex Flex",
        "status": "Active"
      },
      "benefit_lifecycle_stage": {
        "stage": "active",
        "as_of_date": "2026-12-31"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}