List employers

client.employers.list(?, ?): PageNumberPage<EmployerListResponse { active, address, benefit_families, 13 more } >

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, employer id or contact email, benefit-family/lifecycle/HRIS filters, and page/limit pagination.

ParametersExpand Collapse

query: EmployerListParams { benefit_family, benefit_lifecycle_stage, hris_provider, 5 more }

benefit_family?: Array<"mec" | "mvp" | "ichra" | 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?: Array<"open_enrollment" | "renewal" | "active" | 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?: Array<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?: Array<"Pending" | "Active" | "Inactive" | 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?: boolean

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

limit?: number

Items per page.

minimum1

maximum100

page?: number

Page number.

minimum1

search?: string | null

Employer filter. Matches the display name or the legal name case-insensitively as a substring, or one of these exactly: the EIN (with or without its dash), the employer id, or the contact email of one of the employer’s non-disabled admins.

minLength1

ReturnsExpand Collapse

EmployerListResponse { active, address, benefit_families, 13 more }

One employer row of the organization’s book (list projection).

Carries the enriched/computed columns (enrollment roll-up, benefit-family tags, HRIS connection, benefit-lifecycle stage) alongside the flat CRM fields of the underlying employer (legal name, EIN, contact, address, timestamps) for parity with the legacy Employer contract.

active: boolean

Whether the employer is currently active in the system.

address: 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 | null

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

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

benefit_lifecycle_stage: BenefitLifecycleStage { as_of_date, stage }

as_of_date: string | null

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

Employer Identification Number (masked in responses).

email: string | null

Email address for billing and communications.

formatemail

employer_id: string

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

enrollment_rate_summary: EnrollmentRateSummary { 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: HRISStatus | null

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

Legal business name for compliance and tax purposes.

name: string

Employer name.

organization_id: string | null

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

phone_number: string | null

Employer phone number.

reference_id: string | null

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

List employers

import VitableConnect from '@vitable-inc/vitable-connect';

const client = new VitableConnect({
  apiKey: process.env['VITABLE_CONNECT_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const employerListResponse of client.employers.list()) {
  console.log(employerListResponse.employer_id);
}

{
  "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
  }
}