Skip to content
Vitable Docs Vitable Docs Vitable Docs
API Reference

Employers

List employers
client.employers.list(EmployerListParams { benefit_family, benefit_lifecycle_stage, hris_provider, 5 more } query?, RequestOptionsoptions?): PageNumberPage<EmployerListResponse { active, address, benefit_families, 13 more } >
GET/v1/employers
Create employer
client.employers.create(EmployerCreateParams { address, ein, email, 4 more } body, RequestOptionsoptions?): EmployerResponse { data }
POST/v1/employers
Get employer
client.employers.retrieve(stringemployerID, RequestOptionsoptions?): EmployerResponse { data }
GET/v1/employers/{employer_id}
Update employer
client.employers.update(stringemployerID, EmployerUpdateParams { active, address, legal_name, name } body?, RequestOptionsoptions?): EmployerResponse { data }
PUT/v1/employers/{employer_id}
Submit census sync
client.employers.submitCensusSync(stringemployerID, EmployerSubmitCensusSyncParams { employees } body, RequestOptionsoptions?): EmployerSubmitCensusSyncResponse { data }
POST/v1/employers/{employer_id}/census-sync
List employees
client.employers.listEmployees(stringemployerID, EmployerListEmployeesParams { employment_status, limit, page, search } query?, RequestOptionsoptions?): PageNumberPage<Employee { id, classification_effective_date, compensation_type, 20 more } >
GET/v1/employers/{employer_id}/employees
Update employer settings
client.employers.updateSettings(stringemployerID, EmployerUpdateSettingsParams { pay_frequency } body, RequestOptionsoptions?): EmployerUpdateSettingsResponse { data }
PUT/v1/employers/{employer_id}/settings
List HRIS providers
client.employers.listHRISProviders(RequestOptionsoptions?): EmployerListHRISProvidersResponse { data }
GET/v1/employers/hris-providers
Get an employer's HRIS connection
client.employers.retrieveHRIS(stringemployerID, RequestOptionsoptions?): EmployerRetrieveHRISResponse { data }
GET/v1/employers/{employer_id}/hris
List an employer's benefit plan years
client.employers.listBenefitPlanYears(stringemployerID, RequestOptionsoptions?): EmployerListBenefitPlanYearsResponse { data }
GET/v1/employers/{employer_id}/benefit-plan-years
Get one of an employer's benefit plan years
client.employers.retrieveBenefitPlanYear(stringbenefitPlanYearID, EmployerRetrieveBenefitPlanYearParams { employer_id } params, RequestOptionsoptions?): EmployerRetrieveBenefitPlanYearResponse { data }
GET/v1/employers/{employer_id}/benefit-plan-years/{benefit_plan_year_id}
List a benefit plan year's enrollments
client.employers.listBenefitPlanYearEnrollments(stringbenefitPlanYearID, EmployerListBenefitPlanYearEnrollmentsParams { employer_id, election_status, limit, 2 more } params, RequestOptionsoptions?): 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
client.employers.listInvoices(stringemployerID, EmployerListInvoicesParams { limit, offset } query?, RequestOptionsoptions?): EmployerListInvoicesResponse { data, pagination }
GET/v1/employers/{employer_id}/invoices
Get an employer invoice's PDF download link
client.employers.retrieveInvoicePdf(stringinvoiceID, EmployerRetrieveInvoicePdfParams { employer_id } params, RequestOptionsoptions?): EmployerRetrieveInvoicePdfResponse { data }
GET/v1/employers/{employer_id}/invoices/{invoice_id}/pdf
Retrieve Payroll Access Setup
client.employers.retrievePayrollAccessSetup(stringemployerID, RequestOptionsoptions?): EmployerRetrievePayrollAccessSetupResponse { data }
GET/v1/employers/{employer_id}/payroll-access-setup
Submit Payroll Access Setup
client.employers.submitPayrollAccessSetup(stringemployerID, EmployerSubmitPayrollAccessSetupParams { access_method, all_benefit_eligible_employees_present, classifications_accurate, 20 more } body, RequestOptionsoptions?): EmployerSubmitPayrollAccessSetupResponse { data }
PUT/v1/employers/{employer_id}/payroll-access-setup
List an employer's payroll-deduction statements
client.employers.listPayrollDeductionStatements(stringemployerID, EmployerListPayrollDeductionStatementsParams { limit, page } query?, RequestOptionsoptions?): PageNumberPage<EmployerListPayrollDeductionStatementsResponse { csv_file_url, deduction_frequency, deduction_frequency_label, 6 more } >
GET/v1/employers/{employer_id}/payroll-deduction-statements
Ensure Payroll Integration Email
client.employers.ensurePayrollIntegrationEmail(stringemployerID, RequestOptionsoptions?): EmployerEnsurePayrollIntegrationEmailResponse { data }
PUT/v1/employers/{employer_id}/payroll-integration-email
ModelsExpand Collapse
Employer { id, active, address, 10 more }

Serializer for Employer entity in public API responses.

id: string

Unique employer identifier with ‘empr_’ prefix

active: boolean

Whether the employer is currently active in the system

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

Secondary street address (apt, suite, etc.)

contact: Contact | null

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

email: string | null

Primary contact email

formatemail
phone: string | null

Primary contact phone, or null

created_at: string

Timestamp when the employer was created

formatdate-time
ein: string | null

Employer Identification Number (format: XX-XXXXXXX)

name: string

Display name of the employer

organization_id: string | null

ID of the parent organization (org_*)

updated_at: string

Timestamp when the employer was last updated

formatdate-time
email?: string | null

Email address for billing and communications

formatemail
phone_number?: string | null

Employer phone number (E.164 format recommended)

reference_id?: string | null

Partner-assigned reference ID for the employer

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

Whether the employer is currently active in the system

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

Secondary street address (apt, suite, etc.)

contact: Contact | null

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

email: string | null

Primary contact email

formatemail
phone: string | null

Primary contact phone, or null

created_at: string

Timestamp when the employer was created

formatdate-time
ein: string | null

Employer Identification Number (format: XX-XXXXXXX)

name: string

Display name of the employer

organization_id: string | null

ID of the parent organization (org_*)

updated_at: string

Timestamp when the employer was last updated

formatdate-time
email?: string | null

Email address for billing and communications

formatemail
phone_number?: string | null

Employer phone number (E.164 format recommended)

reference_id?: string | null

Partner-assigned reference ID for the employer

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.

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
EmployerSubmitCensusSyncResponse { data }

Response containing a single census sync detail resource.

data: Data { accepted_at, employer_id }
accepted_at: string
formatdate-time
employer_id: string
EmployerUpdateSettingsResponse { data }

Response containing a single employer settings resource.

data: Data { pay_frequency }
pay_frequency: "weekly" | "bi_weekly" | "semi_monthly" | "monthly" | null
  • weekly - Weekly
  • bi_weekly - Bi Weekly
  • semi_monthly - Semi Monthly
  • monthly - Monthly
One of the following:
"weekly"
"bi_weekly"
"semi_monthly"
"monthly"
EmployerListHRISProvidersResponse { data }

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

data: Array<Data>
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).

EmployerRetrieveHRISResponse { data }

Response containing a single employer hris resource.

data: Data { hris }
hris: HRIS | null

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

last_sync_on: string | null

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

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

EmployerListBenefitPlanYearsResponse { data }
data: Array<Data>
benefit_id: string

Prefixed benefit identifier (bprd_*).

benefit_plan_year_id: string

Prefixed plan-year identifier (plyr_*).

carrier: string | null

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

coverage_end: string | null

Coverage end.

formatdate
coverage_start: string

Coverage start.

formatdate
employee_contribution: EmployeeContribution | null

Employee contribution range.

max_cents: number

Highest per-tier contribution in cents.

min_cents: number

Lowest per-tier contribution in cents.

employer_contribution: EmployerContribution | null

Employer contribution range.

max_cents: number

Highest per-tier contribution in cents.

min_cents: number

Lowest per-tier contribution in cents.

enrollment_rate: EnrollmentRate { eligible, enrolled, percentage }

Enrolled/eligible rate for this plan year.

eligible: number

Employees eligible for this plan year.

enrolled: number

Employees enrolled in this plan year.

percentage: number

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

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

Open-enrollment end.

formatdate
open_enrollment_start: string

Open-enrollment start.

formatdate
premium_in_cents: number | null

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

Calendar coverage year.

EmployerRetrieveBenefitPlanYearResponse { data }

Response containing a single employer benefit plan year resource.

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

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

contribution_strategy: ContributionStrategy { 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<ContributionTier>

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

Monthly employee deduction in cents.

cost_per_dependent: number

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

Whether dependents are required for this tier.

spouse_required_in: boolean

Whether a spouse is required for this tier.

ichra_contribution_classes: Array<IchraContributionClass>

ICHRA contribution classes; empty for tier-priced benefits.

amount_in_cents: number

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

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

max_age: number | null

Age-band upper bound, or null.

min_age: number | null

Age-band lower bound, or null.

coverage_end: string | null

Coverage end.

formatdate
coverage_start: string

Coverage start.

formatdate
eligibility_policy: EligibilityPolicy | null

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

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: EligibleGeographicalLocation { 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: number | null

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" | null
  • 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: EmployeeContribution | null

Employee contribution range.

max_cents: number

Highest per-tier contribution in cents.

min_cents: number

Lowest per-tier contribution in cents.

employer_contribution: EmployerContribution | null

Employer contribution range.

max_cents: number

Highest per-tier contribution in cents.

min_cents: number

Lowest per-tier contribution in cents.

enrollment_rate: EnrollmentRate { eligible, enrolled, percentage }

Enrolled/eligible rate for this plan year.

eligible: number

Employees eligible for this plan year.

enrolled: number

Employees enrolled in this plan year.

percentage: number

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

Open-enrollment end.

formatdate
open_enrollment_start: string

Open-enrollment start.

formatdate
premium_in_cents: number | null

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

product_name: string

Benefit/product display name.

spd_file_url: string | null

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

Calendar coverage year.

EmployerListBenefitPlanYearEnrollmentsResponse { carrier, dependent_count, election_status, 11 more }
carrier: string | null

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

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

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

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

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

Chosen plan name, or null when unanswered/waived.

policy_status: "Coverage Upcoming" | "Coverage Effective" | "Coverage Ended" | "Cancelled" | null
  • 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: number | null

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

Chosen coverage tier, or null when unanswered/waived.

EmployerListInvoicesResponse { data, pagination }

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

data: Array<Data>
invoice_id: string

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

period: string | null

Invoice date as an ISO string, or null.

status: string | null

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

total: number | null

Invoice total in dollars, or null.

formatdouble
EmployerRetrieveInvoicePdfResponse { data }

Response containing a single employer invoice pdf resource.

data: Data { download_url }
download_url: string

Time-limited Chargebee PDF download link for the invoice.

EmployerRetrievePayrollAccessSetupResponse { data }

Response containing a single payroll access setup status resource.

data: Data { completed, submitted_at }
completed: boolean
submitted_at: string | null
formatdate-time
EmployerSubmitPayrollAccessSetupResponse { data }

Response containing a single payroll access setup status resource.

data: Data { completed, submitted_at }
completed: boolean
submitted_at: string | null
formatdate-time
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 | null

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

Distinct employees covered by the statement’s entries.

period_end: string

Deduction period end date.

formatdate
period_start: string

Deduction period start date.

formatdate
run_date: string

When the statement was generated.

formatdate-time
statement_id: string

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

total_deduction_cents: number

Total payroll deduction for the period, in cents.

EmployerEnsurePayrollIntegrationEmailResponse { data }

Response containing a single payroll integration email resource.

data: Data { integration_email }
integration_email: string
formatemail