Employers

List employers

employers.list() -> SyncPageNumberPage[EmployerListResponse]

GET/v1/employers

Create employer

employers.create() -> EmployerResponse

POST/v1/employers

Get employer

employers.retrieve() -> EmployerResponse

GET/v1/employers/{employer_id}

Update employer

employers.update(, ) -> EmployerResponse

PUT/v1/employers/{employer_id}

Submit census sync

employers.submit_census_sync(, ) -> EmployerSubmitCensusSyncResponse

POST/v1/employers/{employer_id}/census-sync

List employees

employers.list_employees(, ) -> SyncPageNumberPage[Employee]

GET/v1/employers/{employer_id}/employees

Update employer settings

employers.update_settings(, ) -> EmployerUpdateSettingsResponse

PUT/v1/employers/{employer_id}/settings

List HRIS providers

employers.list_hris_providers() -> EmployerListHRISProvidersResponse

GET/v1/employers/hris-providers

Get an employer's HRIS connection

employers.retrieve_hris() -> EmployerRetrieveHRISResponse

GET/v1/employers/{employer_id}/hris

List an employer's benefit plan years

employers.list_benefit_plan_years() -> EmployerListBenefitPlanYearsResponse

GET/v1/employers/{employer_id}/benefit-plan-years

Get one of an employer's benefit plan years

employers.retrieve_benefit_plan_year(, ) -> EmployerRetrieveBenefitPlanYearResponse

GET/v1/employers/{employer_id}/benefit-plan-years/{benefit_plan_year_id}

List a benefit plan year's enrollments

employers.list_benefit_plan_year_enrollments(, ) -> SyncPageNumberPage[EmployerListBenefitPlanYearEnrollmentsResponse]

GET/v1/employers/{employer_id}/benefit-plan-years/{benefit_plan_year_id}/enrollments

List an employer's billing invoices

employers.list_invoices(, ) -> EmployerListInvoicesResponse

GET/v1/employers/{employer_id}/invoices

Get an employer invoice's PDF download link

employers.retrieve_invoice_pdf(, ) -> EmployerRetrieveInvoicePdfResponse

GET/v1/employers/{employer_id}/invoices/{invoice_id}/pdf

Retrieve Payroll Access Setup

employers.retrieve_payroll_access_setup() -> EmployerRetrievePayrollAccessSetupResponse

GET/v1/employers/{employer_id}/payroll-access-setup

Submit Payroll Access Setup

employers.submit_payroll_access_setup(, ) -> EmployerSubmitPayrollAccessSetupResponse

PUT/v1/employers/{employer_id}/payroll-access-setup

List an employer's payroll-deduction statements

employers.list_payroll_deduction_statements(, ) -> SyncPageNumberPage[EmployerListPayrollDeductionStatementsResponse]

GET/v1/employers/{employer_id}/payroll-deduction-statements

Ensure Payroll Integration Email

employers.ensure_payroll_integration_email() -> EmployerEnsurePayrollIntegrationEmailResponse

PUT/v1/employers/{employer_id}/payroll-integration-email

ModelsExpand Collapse

class Employer: …

Serializer for Employer entity in public API responses.

id: str

Unique employer identifier with ‘empr_’ prefix

active: bool

Whether the employer is currently active in the system

address: Address

Nested address within EmployerSerializer.

address_line_1: str

Primary street address

city: str

City name

state: str

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

zipcode: str

ZIP code (5 or 9 digit)

address_line_2: Optional[str]

Secondary street address (apt, suite, etc.)

contact: Optional[Contact]

Primary company-admin contact (email + phone; company admins have no person name).

email: Optional[str]

Primary contact email

formatemail

phone: Optional[str]

Primary contact phone, or null

created_at: datetime

Timestamp when the employer was created

formatdate-time

ein: Optional[str]

Employer Identification Number (format: XX-XXXXXXX)

legal_name: str

Legal business name for compliance and tax purposes

Display name of the employer

organization_id: Optional[str]

ID of the parent organization (org_*)

updated_at: datetime

Timestamp when the employer was last updated

formatdate-time

email: Optional[str]

Email address for billing and communications

formatemail

phone_number: Optional[str]

Employer phone number (E.164 format recommended)

reference_id: Optional[str]

Partner-assigned reference ID for the employer

class EmployerResponse: …

Response containing a single employer resource.

data: Employer

Serializer for Employer entity in public API responses.

id: str

Unique employer identifier with ‘empr_’ prefix

active: bool

Whether the employer is currently active in the system

address: Address

Nested address within EmployerSerializer.

address_line_1: str

Primary street address

city: str

City name

state: str

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

zipcode: str

ZIP code (5 or 9 digit)

address_line_2: Optional[str]

Secondary street address (apt, suite, etc.)

contact: Optional[Contact]

Primary company-admin contact (email + phone; company admins have no person name).

email: Optional[str]

Primary contact email

formatemail

phone: Optional[str]

Primary contact phone, or null

created_at: datetime

Timestamp when the employer was created

formatdate-time

ein: Optional[str]

Employer Identification Number (format: XX-XXXXXXX)

legal_name: str

Legal business name for compliance and tax purposes

Display name of the employer

organization_id: Optional[str]

ID of the parent organization (org_*)

updated_at: datetime

Timestamp when the employer was last updated

formatdate-time

email: Optional[str]

Email address for billing and communications

formatemail

phone_number: Optional[str]

Employer phone number (E.164 format recommended)

reference_id: Optional[str]

Partner-assigned reference ID for the employer

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.

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

class EmployerSubmitCensusSyncResponse: …

Response containing a single census sync detail resource.

data: Data

accepted_at: datetime

formatdate-time

employer_id: str

class EmployerUpdateSettingsResponse: …

Response containing a single employer settings resource.

data: Data

pay_frequency: Optional[Literal["weekly", "bi_weekly", "semi_monthly", "monthly"]]

weekly - Weekly
bi_weekly - Bi Weekly
semi_monthly - Semi Monthly
monthly - Monthly

One of the following:

"weekly"

"bi_weekly"

"semi_monthly"

"monthly"

class EmployerListHRISProvidersResponse: …

Unpaginated {"data": [...]} list of organization hris providers.

data: List[Data]

provider: str

HRIS/payroll provider id, as stored on the connection (e.g. adp_run). Filter with this.

provider_label: str

Display name of that provider (e.g. ADP Run).

class EmployerRetrieveHRISResponse: …

Response containing a single employer hris resource.

data: Data

hris: Optional[DataHRIS]

HRIS connection details, or null when the employer has no integration.

last_sync_on: Optional[datetime]

When the last sync completed, or null when none has.

formatdate-time

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.

synced_row_count: Optional[int]

Rows in the latest completed sync, or null when none has.

class EmployerListBenefitPlanYearsResponse: …

data: List[Data]

benefit_id: str

Prefixed benefit identifier (bprd_*).

benefit_plan_year_id: str

Prefixed plan-year identifier (plyr_*).

carrier: Optional[str]

Carrier name, or null (e.g. ICHRA).

coverage_end: Optional[date]

Coverage end.

formatdate

coverage_start: date

Coverage start.

formatdate

employee_contribution: Optional[DataEmployeeContribution]

Employee contribution range.

max_cents: int

Highest per-tier contribution in cents.

min_cents: int

Lowest per-tier contribution in cents.

employer_contribution: Optional[DataEmployerContribution]

Employer contribution range.

max_cents: int

Highest per-tier contribution in cents.

min_cents: int

Lowest per-tier contribution in cents.

enrollment_rate: DataEnrollmentRate

Enrolled/eligible rate for this plan year.

eligible: int

Employees eligible for this plan year.

enrolled: int

Employees enrolled in this plan year.

percentage: int

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

family: Literal["mec", "mvp", "ichra", 3 more]

mec - Mec
mvp - Mvp
ichra - Ichra
vpc - Vpc
dental - Dental
vision - Vision

One of the following:

"mec"

"mvp"

"ichra"

"vpc"

"dental"

"vision"

is_current: bool

Whether this is the current plan year.

network_names: List[str]

Displayed networks: [“multi”] for ICHRA, otherwise the plan year’s distinct network names.

offered_states: List[str]

Distinct offered state codes.

open_enrollment_end: Optional[date]

Open-enrollment end.

formatdate

open_enrollment_start: date

Open-enrollment start.

formatdate

premium_in_cents: Optional[int]

Monthly premium in cents; only for an ICHRA benefit with effective coverage.

product_name: str

Benefit/product display name.

status: Literal["active", "upcoming", "open_enrollment", "inactive"]

active - Active
upcoming - Upcoming
open_enrollment - Open Enrollment
inactive - Inactive

One of the following:

"active"

"upcoming"

"open_enrollment"

"inactive"

year: int

Calendar coverage year.

class EmployerRetrieveBenefitPlanYearResponse: …

Response containing a single employer benefit plan year resource.

data: Data

One plan year, detail view.

Standalone (no shared base) so the exact detail payload is readable in one place; the list serializer is a separate class even where fields overlap. Detail carries the SPD link and omits the list-only is_current flag.

benefit_id: str

Prefixed benefit identifier (bprd_*).

benefit_plan_year_id: str

Prefixed plan-year identifier (plyr_*).

carrier: Optional[str]

Carrier name, or null (e.g. ICHRA).

contribution_strategy: DataContributionStrategy

How the plan year prices contributions: exactly one collection is populated, determined by the plan year’s family (ICHRA vs tier-priced).

contribution_tiers: List[DataContributionStrategyContributionTier]

Coverage tiers and their costs; empty for ICHRA benefits.

benefit_plan_id: str

Prefixed benefit-plan identifier (bpln_*).

benefit_plan_name: str

Benefit plan name.

benefit_plan_tier_name: str

Coverage-tier name.

cost: int

Monthly employee deduction in cents.

cost_per_dependent: int

Monthly employee deduction per dependent, in cents.

coverage_tier: Literal["Unspecified", "EE", "ES", 2 more]

Unspecified - Unspecified
EE - EE
ES - ES
EC - EC
EF - EF

One of the following:

"Unspecified"

"EE"

"ES"

"EC"

"EF"

dependents_required_in: bool

Whether dependents are required for this tier.

spouse_required_in: bool

Whether a spouse is required for this tier.

ichra_contribution_classes: List[DataContributionStrategyIchraContributionClass]

ICHRA contribution classes; empty for tier-priced benefits.

amount_in_cents: int

Monthly allowance in cents.

compensation: Literal["Unspecified", "Salary", "Hourly"]

Unspecified - Unspecified
Salary - Salary
Hourly - Hourly

One of the following:

"Unspecified"

"Salary"

"Hourly"

contribution_class_id: str

Prefixed contribution-class identifier (iccl_*).

employment: Literal["Unspecified", "Full Time", "Part Time", 2 more]

Unspecified - Unspecified
Full Time - Full Time
Part Time - Part Time
Temporary - Temporary
Seasonal - Seasonal

One of the following:

"Unspecified"

"Full Time"

"Part Time"

"Temporary"

"Seasonal"

family_status: Literal["Unspecified", "EE", "ES", 2 more]

Unspecified - Unspecified
EE - EE
ES - ES
EC - EC
EF - EF

One of the following:

"Unspecified"

"EE"

"ES"

"EC"

"EF"

location: Literal["Unspecified", "State"]

Unspecified - Unspecified
State - State

One of the following:

"Unspecified"

"State"

location_value: Optional[str]

Location matcher value (CSV of state codes), or null.

max_age: Optional[int]

Age-band upper bound, or null.

min_age: Optional[int]

Age-band lower bound, or null.

coverage_end: Optional[date]

Coverage end.

formatdate

coverage_start: date

Coverage start.

formatdate

eligibility_policy: Optional[DataEligibilityPolicy]

The plan year’s active eligibility policy. Mirrors the internal PlanYearEligibilityPolicyDTO but exposes only the public subset (no raw ids, active_in, or timestamps).

rules: List[DataEligibilityPolicyRule]

Eligibility rules; never empty for a valid policy.

compensation_type: Literal["Salary", "Hourly", "All"]

Salary - Salary
Hourly - Hourly
All - All

One of the following:

"Salary"

"Hourly"

"All"

eligible_geographical_location: DataEligibilityPolicyRuleEligibleGeographicalLocation

Geographic matcher.

state_codes: List[str]

States the rule is restricted to; empty when type is All.

type: Literal["All", "StateCodes"]

All - All
StateCodes - State Codes

One of the following:

"All"

"StateCodes"

employee_class: Literal["Full Time", "Part Time", "Temporary", 4 more]

Full Time - Full Time
Part Time - Part Time
Temporary - Temporary
Intern - Intern
Seasonal - Seasonal
Individual Contractor - Individual Contractor
All - All

One of the following:

"Full Time"

"Part Time"

"Temporary"

"Intern"

"Seasonal"

"Individual Contractor"

"All"

termination_n_months: Optional[int]

Months of continued coverage; set only when termination_rule is END_OF_N_MONTHS.

termination_rule: Literal["END_OF_N_MONTHS", "END_OF_PLAN_YEAR"]

END_OF_N_MONTHS - End Of N Months
END_OF_PLAN_YEAR - End Of Plan Year

One of the following:

"END_OF_N_MONTHS"

"END_OF_PLAN_YEAR"

waiting_period: Optional[Literal["FIRST_OF_FOLLOWING_MONTH", "THIRTY_DAYS", "SIXTY_DAYS"]]

FIRST_OF_FOLLOWING_MONTH - First Of Following Month
THIRTY_DAYS - Thirty Days
SIXTY_DAYS - Sixty Days

One of the following:

"FIRST_OF_FOLLOWING_MONTH"

"THIRTY_DAYS"

"SIXTY_DAYS"

employee_contribution: Optional[DataEmployeeContribution]

Employee contribution range.

max_cents: int

Highest per-tier contribution in cents.

min_cents: int

Lowest per-tier contribution in cents.

employer_contribution: Optional[DataEmployerContribution]

Employer contribution range.

max_cents: int

Highest per-tier contribution in cents.

min_cents: int

Lowest per-tier contribution in cents.

enrollment_rate: DataEnrollmentRate

Enrolled/eligible rate for this plan year.

eligible: int

Employees eligible for this plan year.

enrolled: int

Employees enrolled in this plan year.

percentage: int

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

family: Literal["mec", "mvp", "ichra", 3 more]

mec - Mec
mvp - Mvp
ichra - Ichra
vpc - Vpc
dental - Dental
vision - Vision

One of the following:

"mec"

"mvp"

"ichra"

"vpc"

"dental"

"vision"

network_names: List[str]

Displayed networks: [“multi”] for ICHRA, otherwise the plan year’s distinct network names.

offered_states: List[str]

Distinct offered state codes.

open_enrollment_end: Optional[date]

Open-enrollment end.

formatdate

open_enrollment_start: date

Open-enrollment start.

formatdate

premium_in_cents: Optional[int]

Monthly premium in cents; only for an ICHRA benefit with effective coverage.

product_name: str

Benefit/product display name.

spd_file_url: Optional[str]

Summary Plan Description (SPD) link, or null.

status: Literal["active", "upcoming", "open_enrollment", "inactive"]

active - Active
upcoming - Upcoming
open_enrollment - Open Enrollment
inactive - Inactive

One of the following:

"active"

"upcoming"

"open_enrollment"

"inactive"

year: int

Calendar coverage year.

class EmployerListBenefitPlanYearEnrollmentsResponse: …

carrier: Optional[str]

The carrier for this enrollment: the individual-market carrier for an ICHRA plan, otherwise the benefit’s own. Null when the benefit has no carrier.

dependent_count: int

Dependents covered under this enrollment today. Counts the same dependents premium_in_cents is priced for, so a dependent whose termination is dated in the future still counts.

minimum0

election_status: Literal["Enrolled", "Waived", "Pending", "Expired"]

Enrolled - Enrolled
Waived - Waived
Pending - Pending
Expired - Expired

One of the following:

"Enrolled"

"Waived"

"Pending"

"Expired"

employee_deduction_in_cents: Optional[int]

What the employee is deducted monthly, in cents: premium_in_cents less employer_contribution_in_cents, floored at zero. Null when unanswered/waived.

employee_external_reference_id: Optional[str]

Your own reference id for this employee, as you supplied it. Null when you have not set one.

employee_id: str

Our id for this person’s employment with this employer (empl_<...>). A person who leaves and is rehired has two.

employer_contribution_in_cents: Optional[int]

The employer’s monthly share of premium_in_cents, in cents. Null when unanswered/waived.

member_first_name: str

The member’s first name.

member_id: str

Our id for the person (mbr_<...>). Stable across every employer they work for.

member_last_name: str

The member’s last name.

plan: Optional[str]

Chosen plan name, or null when unanswered/waived.

policy_status: Optional[Literal["Coverage Upcoming", "Coverage Effective", "Coverage Ended", "Cancelled"]]

Coverage Upcoming - Coverage Upcoming
Coverage Effective - Coverage Effective
Coverage Ended - Coverage Ended
Cancelled - Cancelled

One of the following:

"Coverage Upcoming"

"Coverage Effective"

"Coverage Ended"

"Cancelled"

premium_in_cents: Optional[int]

Monthly premium in cents for the chosen plan, dependents included. The plan’s own cost, not the employer’s share of it. Null when unanswered/waived.

tier: Optional[str]

Chosen coverage tier, or null when unanswered/waived.

class EmployerListInvoicesResponse: …

Cursor-paginated invoices envelope: { "data": [...], "pagination": { "next_offset": ... } }.

data: List[Data]

invoice_id: str

Chargebee invoice id (external id, not a prefixed UUID).

period: Optional[str]

Invoice date as an ISO string, or null.

status: Optional[str]

Chargebee invoice status (e.g. paid), or null.

total: Optional[float]

Invoice total in dollars, or null.

formatdouble

pagination: Pagination

next_offset: Optional[str]

Opaque JSON-encoded cursor for the next page; null when there are no more pages.

class EmployerRetrieveInvoicePdfResponse: …

Response containing a single employer invoice pdf resource.

data: Data

download_url: str

Time-limited Chargebee PDF download link for the invoice.

class EmployerRetrievePayrollAccessSetupResponse: …

Response containing a single payroll access setup status resource.

data: Data

completed: bool

submitted_at: Optional[datetime]

formatdate-time

class EmployerSubmitPayrollAccessSetupResponse: …

Response containing a single payroll access setup status resource.

data: Data

completed: bool

submitted_at: Optional[datetime]

formatdate-time

class EmployerListPayrollDeductionStatementsResponse: …

One payroll-deduction statement row.

Reads a :class:PayrollDeductionStatementDTO by attribute: the statement_id character field renders the prefixed id via str(), and the date/datetime fields emit ISO-8601 strings.

csv_file_url: Optional[str]

Download link for the change CSV, or null.

deduction_frequency: Literal["weekly", "bi_weekly", "semi_monthly", "monthly"]

weekly - Weekly
bi_weekly - Bi Weekly
semi_monthly - Semi Monthly
monthly - Monthly

One of the following:

"weekly"

"bi_weekly"

"semi_monthly"

"monthly"

deduction_frequency_label: str

Human-readable deduction frequency (e.g. Monthly).

employee_count: int

Distinct employees covered by the statement’s entries.

period_end: date

Deduction period end date.

formatdate

period_start: date

Deduction period start date.

formatdate

run_date: datetime

When the statement was generated.

formatdate-time

statement_id: str

Prefixed payroll-deduction-statement identifier (pstmt_<base64-encoded-uuid>).

total_deduction_cents: int

Total payroll deduction for the period, in cents.

class EmployerEnsurePayrollIntegrationEmailResponse: …

Response containing a single payroll integration email resource.

data: Data

integration_email: str

formatemail