API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Employers

List employers

employers.list(**kwargs) -> PageNumberPage<EmployerListResponse { active, address, benefit_families, 13 more } >

GET/v1/employers

Create employer

employers.create(**kwargs) -> EmployerResponse { data }

POST/v1/employers

Get employer

employers.retrieve(employer_id) -> EmployerResponse { data }

GET/v1/employers/{employer_id}

Update employer

employers.update(employer_id, **kwargs) -> EmployerResponse { data }

PUT/v1/employers/{employer_id}

Submit census sync

employers.submit_census_sync(employer_id, **kwargs) -> EmployerSubmitCensusSyncResponse { data }

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

List employees

employers.list_employees(employer_id, **kwargs) -> PageNumberPage<Employee { id, classification_effective_date, compensation_type, 20 more } >

GET/v1/employers/{employer_id}/employees

Update employer settings

employers.update_settings(employer_id, **kwargs) -> EmployerUpdateSettingsResponse { data }

PUT/v1/employers/{employer_id}/settings

List HRIS providers

employers.list_hris_providers() -> EmployerListHRISProvidersResponse { data }

GET/v1/employers/hris-providers

Get an employer's HRIS connection

employers.retrieve_hris(employer_id) -> EmployerRetrieveHRISResponse { data }

GET/v1/employers/{employer_id}/hris

List an employer's benefit plan years

employers.list_benefit_plan_years(employer_id) -> EmployerListBenefitPlanYearsResponse { data }

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

Get one of an employer's benefit plan years

employers.retrieve_benefit_plan_year(benefit_plan_year_id, **kwargs) -> EmployerRetrieveBenefitPlanYearResponse { data }

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(benefit_plan_year_id, **kwargs) -> PageNumberPage<EmployerListBenefitPlanYearEnrollmentsResponse { carrier, dependent_count, election_status, 11 more } >

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

List an employer's billing invoices

employers.list_invoices(employer_id, **kwargs) -> EmployerListInvoicesResponse { data, pagination }

GET/v1/employers/{employer_id}/invoices

Get an employer invoice's PDF download link

employers.retrieve_invoice_pdf(invoice_id, **kwargs) -> EmployerRetrieveInvoicePdfResponse { data }

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

Retrieve Payroll Access Setup

employers.retrieve_payroll_access_setup(employer_id) -> EmployerRetrievePayrollAccessSetupResponse { data }

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

Submit Payroll Access Setup

employers.submit_payroll_access_setup(employer_id, **kwargs) -> EmployerSubmitPayrollAccessSetupResponse { data }

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

List an employer's payroll-deduction statements

employers.list_payroll_deduction_statements(employer_id, **kwargs) -> PageNumberPage<EmployerListPayrollDeductionStatementsResponse { csv_file_url, deduction_frequency, deduction_frequency_label, 6 more } >

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

Ensure Payroll Integration Email

employers.ensure_payroll_integration_email(employer_id) -> EmployerEnsurePayrollIntegrationEmailResponse { data }

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

ModelsExpand Collapse

class Employer { id, active, address, 10 more }

Serializer for Employer entity in public API responses.

id: String

Unique employer identifier with ‘empr_’ prefix

active: bool

Whether the employer is currently active in the system

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

Nested address within EmployerSerializer.

address_line_1: String

Primary street address

city: String

City name

state: String

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

zipcode: String

ZIP code (5 or 9 digit)

address_line_2: String

Secondary street address (apt, suite, etc.)

contact: { email, phone}

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

email: String

Primary contact email

formatemail

phone: String

Primary contact phone, or null

created_at: Time

Timestamp when the employer was created

formatdate-time

ein: String

Employer Identification Number (format: XX-XXXXXXX)

legal_name: String

Legal business name for compliance and tax purposes

name: String

Display name of the employer

organization_id: String

ID of the parent organization (org_*)

updated_at: Time

Timestamp when the employer was last updated

formatdate-time

email: String

Email address for billing and communications

formatemail

phone_number: String

Employer phone number (E.164 format recommended)

reference_id: String

Partner-assigned reference ID for the employer

class EmployerResponse { data }

Response containing a single employer resource.

data: Employer { id, active, address, 10 more }

Serializer for Employer entity in public API responses.

id: String

Unique employer identifier with ‘empr_’ prefix

active: bool

Whether the employer is currently active in the system

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

Nested address within EmployerSerializer.

address_line_1: String

Primary street address

city: String

City name

state: String

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

zipcode: String

ZIP code (5 or 9 digit)

address_line_2: String

Secondary street address (apt, suite, etc.)

contact: { email, phone}

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

email: String

Primary contact email

formatemail

phone: String

Primary contact phone, or null

created_at: Time

Timestamp when the employer was created

formatdate-time

ein: String

Employer Identification Number (format: XX-XXXXXXX)

legal_name: String

Legal business name for compliance and tax purposes

name: String

Display name of the employer

organization_id: String

ID of the parent organization (org_*)

updated_at: Time

Timestamp when the employer was last updated

formatdate-time

email: String

Email address for billing and communications

formatemail

phone_number: String

Employer phone number (E.164 format recommended)

reference_id: String

Partner-assigned reference ID for the employer

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

class EmployerSubmitCensusSyncResponse { data }

Response containing a single census sync detail resource.

data: { accepted_at, employer_id}

accepted_at: Time

formatdate-time

employer_id: String

class EmployerUpdateSettingsResponse { data }

Response containing a single employer settings resource.

data: { pay_frequency}

pay_frequency: :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 { data }

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

data: Array[{ provider, provider_label}]

provider: String

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

provider_label: String

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

class EmployerRetrieveHRISResponse { data }

Response containing a single employer hris resource.

data: { hris}

hris: { last_sync_on, provider, provider_label, 2 more}

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

last_sync_on: Time

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

formatdate-time

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.

synced_row_count: Integer

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

class EmployerListBenefitPlanYearsResponse { data }

data: Array[{ benefit_id, benefit_plan_year_id, carrier, 15 more}]

benefit_id: String

Prefixed benefit identifier (bprd_*).

benefit_plan_year_id: String

Prefixed plan-year identifier (plyr_*).

carrier: String

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

coverage_end: Date

Coverage end.

formatdate

coverage_start: Date

Coverage start.

formatdate

employee_contribution: { max_cents, min_cents}

Employee contribution range.

max_cents: Integer

Highest per-tier contribution in cents.

min_cents: Integer

Lowest per-tier contribution in cents.

employer_contribution: { max_cents, min_cents}

Employer contribution range.

max_cents: Integer

Highest per-tier contribution in cents.

min_cents: Integer

Lowest per-tier contribution in cents.

enrollment_rate: { eligible, enrolled, percentage}

Enrolled/eligible rate for this plan year.

eligible: Integer

Employees eligible for this plan year.

enrolled: Integer

Employees enrolled in this plan year.

percentage: Integer

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

family: :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: Array[String]

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

offered_states: Array[String]

Distinct offered state codes.

open_enrollment_end: Date

Open-enrollment end.

formatdate

open_enrollment_start: Date

Open-enrollment start.

formatdate

premium_in_cents: Integer

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

product_name: String

Benefit/product display name.

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

Calendar coverage year.

class EmployerRetrieveBenefitPlanYearResponse { data }

Response containing a single employer benefit plan year resource.

data: { benefit_id, benefit_plan_year_id, carrier, 17 more}

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

Prefixed benefit identifier (bprd_*).

benefit_plan_year_id: String

Prefixed plan-year identifier (plyr_*).

carrier: String

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

contribution_strategy: { contribution_tiers, ichra_contribution_classes}

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

contribution_tiers: Array[{ benefit_plan_id, benefit_plan_name, benefit_plan_tier_name, 5 more}]

Coverage tiers and their costs; empty for ICHRA benefits.

benefit_plan_id: String

Prefixed benefit-plan identifier (bpln_*).

benefit_plan_name: String

Benefit plan name.

benefit_plan_tier_name: String

Coverage-tier name.

cost: Integer

Monthly employee deduction in cents.

cost_per_dependent: Integer

Monthly employee deduction per dependent, in cents.

coverage_tier: :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: Array[{ amount_in_cents, compensation, contribution_class_id, 6 more}]

ICHRA contribution classes; empty for tier-priced benefits.

amount_in_cents: Integer

Monthly allowance in cents.

compensation: :Unspecified | :Salary | :Hourly

• Unspecified - Unspecified
• Salary - Salary
• Hourly - Hourly

One of the following:

:Unspecified

:Salary

:Hourly

contribution_class_id: String

Prefixed contribution-class identifier (iccl_*).

employment: :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: :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: :Unspecified | :State

• Unspecified - Unspecified
• State - State

One of the following:

:Unspecified

:State

location_value: String

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

max_age: Integer

Age-band upper bound, or null.

min_age: Integer

Age-band lower bound, or null.

coverage_end: Date

Coverage end.

formatdate

coverage_start: Date

Coverage start.

formatdate

eligibility_policy: { rules, termination_n_months, termination_rule, waiting_period}

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: Array[{ compensation_type, eligible_geographical_location, employee_class}]

Eligibility rules; never empty for a valid policy.

compensation_type: :Salary | :Hourly | :All

• Salary - Salary
• Hourly - Hourly
• All - All

One of the following:

:Salary

:Hourly

:All

eligible_geographical_location: { state_codes, type}

Geographic matcher.

state_codes: Array[String]

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

type: :All | :StateCodes

• All - All
• StateCodes - State Codes

One of the following:

:All

:StateCodes

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

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

termination_rule: :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: :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: { max_cents, min_cents}

Employee contribution range.

max_cents: Integer

Highest per-tier contribution in cents.

min_cents: Integer

Lowest per-tier contribution in cents.

employer_contribution: { max_cents, min_cents}

Employer contribution range.

max_cents: Integer

Highest per-tier contribution in cents.

min_cents: Integer

Lowest per-tier contribution in cents.

enrollment_rate: { eligible, enrolled, percentage}

Enrolled/eligible rate for this plan year.

eligible: Integer

Employees eligible for this plan year.

enrolled: Integer

Employees enrolled in this plan year.

percentage: Integer

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

family: :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: Array[String]

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

offered_states: Array[String]

Distinct offered state codes.

open_enrollment_end: Date

Open-enrollment end.

formatdate

open_enrollment_start: Date

Open-enrollment start.

formatdate

premium_in_cents: Integer

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

product_name: String

Benefit/product display name.

spd_file_url: String

Summary Plan Description (SPD) link, or null.

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

Calendar coverage year.

class EmployerListBenefitPlanYearEnrollmentsResponse { carrier, dependent_count, election_status, 11 more }

carrier: String

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

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: :Enrolled | :Waived | :Pending | :Expired

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

One of the following:

:Enrolled

:Waived

:Pending

:Expired

employee_deduction_in_cents: Integer

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

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

employee_id: String

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

employer_contribution_in_cents: Integer

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

member_first_name: String

The member’s first name.

member_id: String

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

member_last_name: String

The member’s last name.

plan: String

Chosen plan name, or null when unanswered/waived.

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

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

Chosen coverage tier, or null when unanswered/waived.

class EmployerListInvoicesResponse { data, pagination }

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

data: Array[{ invoice_id, period, status, total}]

invoice_id: String

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

period: String

Invoice date as an ISO string, or null.

status: String

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

total: Float

Invoice total in dollars, or null.

formatdouble

pagination: { next_offset}

next_offset: String

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

class EmployerRetrieveInvoicePdfResponse { data }

Response containing a single employer invoice pdf resource.

data: { download_url}

download_url: String

Time-limited Chargebee PDF download link for the invoice.

class EmployerRetrievePayrollAccessSetupResponse { data }

Response containing a single payroll access setup status resource.

data: { completed, submitted_at}

completed: bool

submitted_at: Time

formatdate-time

class EmployerSubmitPayrollAccessSetupResponse { data }

Response containing a single payroll access setup status resource.

data: { completed, submitted_at}

completed: bool

submitted_at: Time

formatdate-time

class EmployerListPayrollDeductionStatementsResponse { csv_file_url, deduction_frequency, deduction_frequency_label, 6 more }

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

Download link for the change CSV, or null.

deduction_frequency: :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: String

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

employee_count: Integer

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

When the statement was generated.

formatdate-time

statement_id: String

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

total_deduction_cents: Integer

Total payroll deduction for the period, in cents.

class EmployerEnsurePayrollIntegrationEmailResponse { data }

Response containing a single payroll integration email resource.

data: { integration_email}

integration_email: String

formatemail