List employers

employers.list() -> SyncPageNumberPage[EmployerListResponse]

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: Optional[List[Literal["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: Optional[List[Literal["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: Optional[SequenceNotStr[str]]

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[List[Literal["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: Optional[bool]

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

limit: Optional[int]

Items per page.

minimum1

maximum100

page: Optional[int]

Page number.

minimum1

search: Optional[str]

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

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

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

Primary street address.

address_line_2: Optional[str]

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

city: str

City name.

state: str

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

zipcode: str

ZIP code (5 or 9 digit).

benefit_families: List[str]

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

benefit_lifecycle_stage: BenefitLifecycleStage

as_of_date: Optional[date]

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

formatdate

stage: str

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

created_at: datetime

Timestamp when the employer was created.

formatdate-time

ein: Optional[str]

Employer Identification Number (masked in responses).

email: Optional[str]

Email address for billing and communications.

formatemail

employer_id: str

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

enrollment_rate_summary: EnrollmentRateSummary

Enrolled/eligible employees roll-up.

eligible: int

Employees eligible for at least one active benefit.

enrolled: int

Employees enrolled in at least one active benefit.

percentage: int

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

hris_status: Optional[HRISStatus]

HRIS connection, or null when the employer has none.

provider: str

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

provider_label: str

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

status: str

Connection status reported by the integration.

legal_name: Optional[str]

Legal business name for compliance and tax purposes.

name: str

Employer name.

organization_id: Optional[str]

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

phone_number: Optional[str]

Employer phone number.

reference_id: Optional[str]

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

updated_at: datetime

Timestamp when the employer was last updated.

formatdate-time

List employers

import os
from vitable_connect import VitableConnect

client = VitableConnect(
    api_key=os.environ.get("VITABLE_CONNECT_API_KEY"),  # This is the default and can be omitted
)
page = client.employers.list()
page = page.data[0]
print(page.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
  }
}