List employers

employers.list(**kwargs) -> 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

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: bool

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

limit: Integer

Items per page.

minimum1

maximum100

page: Integer

Page number.

minimum1

search: String

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

class 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: bool

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[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: Date

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: Time

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: Integer

Employees eligible for at least one active benefit.

enrolled: Integer

Employees enrolled in at least one active benefit.

percentage: Integer

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: Time

Timestamp when the employer was last updated.

formatdate-time

List employers

require "vitable_connect"

vitable_connect = VitableConnect::Client.new(
  api_key: "My API Key",
  environment: "environment_1" # defaults to "production"
)

page = vitable_connect.employers.list

puts(page)

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