Reference

Auth

client.auth.issue_access_token(...) -> AccessTokenResponse

📝 Description

Issues a short-lived access token from the authenticated API key. Access tokens can optionally be bound to a specific employer or employee for scoped access. Tokens expire after 15 minutes.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.auth.issue_access_token(
    grant_type="client_credentials",
)

⚙️ Parameters

grant_type: GrantType

Token issuance flow. Currently only 'client_credentials' supported.

client_credentials - client_credentials

bound_entity: typing.Optional[BoundEntity] — Optional entity to bind the token to for scoped access

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Employees

client.employees.get(...) -> EmployeeResponse

📝 Description

Retrieves detailed information for a specific employee by ID. Returns employee details including personal information, employment status, classification and compensation-type effective dates, compensation type, and payroll deductions from the most recent statement period. Deductions reflect a snapshot of the current period and are replaced when a new statement is generated.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employees.get(
    employee_id="empl_abc123def456",
)

⚙️ Parameters

employee_id: EmployeeId — Unique employee identifier (empl_*)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employees.update(...) -> EmployeeResponse

📝 Description

Updates employee personal, contact, address, and employment fields. This endpoint currently supports email, phone, gender, address, employee_class, start_date, and compensation_type. effective_date is required and applies to employee_class and compensation_type when those fields are included in the request.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment
import datetime

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employees.update(
    employee_id="empl_abc123def456",
    employee_class="Full Time",
    start_date=datetime.date.fromisoformat("2023-01-15"),
    compensation_type="Salary",
    effective_date=datetime.date.fromisoformat("2023-03-01"),
)

⚙️ Parameters

employee_id: EmployeeId — Unique employee identifier (empl_*)

effective_date: datetime.date — Past or present date applied to each tracked employment field included in this request

email: typing.Optional[str] — Email address

phone: typing.Optional[str] — Phone number

gender: typing.Optional[Gender]

Gender identity

Male - Male
Female - Female
Transgender - Transgender
Non-binary - Non-binary
Prefer not to respond - Prefer not to respond

address: typing.Optional[EmployeeAddressInput] — Employee's residential address

employee_class: typing.Optional[EmployeeClass]

Employment classification

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

start_date: typing.Optional[datetime.date] — Employment start date

compensation_type: typing.Optional[CompensationType]

Employee compensation type

Salary - Salary
Hourly - Hourly

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employees.list_enrollments(...) -> EnrollmentListResponse

📝 Description

Retrieves a paginated list of benefit enrollments for an employee.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employees.list_enrollments(
    employee_id="empl_abc123def456",
    limit=20,
    page=1,
)

⚙️ Parameters

employee_id: EmployeeId — Unique employee identifier (empl_*)

limit: typing.Optional[Limit] — Items per page (default: 20, max: 100)

page: typing.Optional[Page] — Page number (default: 1)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Employers

client.employers.list(...) -> OrganizationEmployerListResponse

📝 Description

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.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.list(
    limit=20,
    page=1,
)

⚙️ Parameters

benefit_family: typing.Optional[typing.Union[BenefitFamilyParamItem, typing.Sequence[BenefitFamilyParamItem]]] — Filter to employers with at least one active benefit in these families.

benefit_lifecycle_stage: typing.Optional[typing.Union[BenefitLifecycleStageItem, typing.Sequence[BenefitLifecycleStageItem]]] — Filter to employers in one of these computed benefit-lifecycle stages.

hris_provider: typing.Optional[typing.Union[str, typing.Sequence[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: typing.Optional[typing.Union[HrisStatusItem, typing.Sequence[HrisStatusItem]]] — Filter to employers whose HRIS connection is in one of these statuses.

include_cancelled: typing.Optional[IncludeCancelled] — Include cancelled employers (hidden by default unless their stage is explicitly requested).

limit: typing.Optional[Limit] — Items per page.

page: typing.Optional[Page] — Page number.

search: typing.Optional[Search] — 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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.create(...) -> EmployerResponse

📝 Description

Creates a new employer for the authenticated organization. Requires employer name, legal name, EIN, email, and address information. Returns the created employer with its assigned ID.

🔌 Usage

from vitable_connect import VitableConnect, EmployerAddressInput
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.create(
    name="NewCo Industries",
    legal_name="NewCo Industries LLC",
    ein="12-3456789",
    email="hr@newco.com",
    address=EmployerAddressInput(
        address_line1="789 Business Blvd",
        address_line2="Floor 5",
        city="Seattle",
        state="WA",
        zipcode="98101",
    ),
    phone_number="2065550100",
    reference_id="partner-emp-001",
)

⚙️ Parameters

name: str — Employer display name

legal_name: str — Legal business name

ein: str — Employer Identification Number (format: XX-XXXXXXX)

email: str — Email address for billing and communications

address: EmployerAddressInput — Employer address

phone_number: typing.Optional[str] — Employer phone number (10-digit US format, e.g. 5551234567)

reference_id: typing.Optional[str] — External reference ID for this employer

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.get(...) -> EmployerResponse

📝 Description

Retrieves detailed information for a specific employer by ID. The employer must belong to the authenticated organization.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.get(
    employer_id="empr_abc123def456",
)

⚙️ Parameters

employer_id: EmployerId — Unique employer identifier (empr_*)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.update(...) -> EmployerResponse

📝 Description

Updates an existing employer. All fields are optional — only provided fields are updated. PO Box addresses are rejected.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.update(
    employer_id="empr_abc123def456",
)

⚙️ Parameters

employer_id: EmployerId — Unique employer identifier (empr_*)

name: typing.Optional[str] — Employer display name

legal_name: typing.Optional[str] — Legal business name

address: typing.Optional[UpdateEmployerAddressInput] — Employer address

active: typing.Optional[bool] — Whether the employer is active

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.list_benefit_plan_years(...) -> EmployerBenefitPlanYearsListResponse

📝 Description

Returns the employer's benefit plan years (all years, or one when year is given), each with its benefits, offered states, benefit families, and the year-level enrollment roll-up. The caller must be authorized for the employer; an unknown or unauthorized employer returns 404.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.list_benefit_plan_years(
    employer_id="empr_abc123def456",
)

⚙️ Parameters

employer_id: EmployerId — Unique employer identifier (empr_*)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.get_benefit_plan_year(...) -> EmployerBenefitPlanYearResponse

📝 Description

Returns one benefit plan year in full — its benefit details plus the per-benefit enrollment rate and SPD link — addressed by its benefit_plan_year_id. The caller must be authorized for the employer; an unknown or unauthorized plan year returns 404.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.get_benefit_plan_year(
    employer_id="empr_abc123def456",
    benefit_plan_year_id="plyr_abc123def456",
)

⚙️ Parameters

employer_id: EmployerId — Unique employer identifier (empr_*)

benefit_plan_year_id: BenefitPlanYearId — Unique benefit-plan-year identifier (plyr_*).

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.list_benefit_plan_year_enrollments(...) -> PlanYearEnrollmentListResponse

📝 Description

Returns a paginated list of every member with an enrollment in one of an employer's plan years, any election status: what they elected, where their coverage stands, dependent count, carrier, plan, tier, and the plan's total monthly cost. The caller must be authorized for the employer empr_<...>; an unknown or unauthorized employer, or an unknown plan year plyr_<...>, returns 404.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.list_benefit_plan_year_enrollments(
    employer_id="empr_abc123def456",
    benefit_plan_year_id="plyr_abc123def456",
    limit=20,
    page=1,
)

⚙️ Parameters

employer_id: EmployerId — Unique employer identifier (empr_*).

benefit_plan_year_id: BenefitPlanYearId — Unique benefit-plan-year identifier (plyr_*).

election_status: typing.Optional[typing.Union[ElectionStatusItem, typing.Sequence[ElectionStatusItem]]] — Filter by election status. Repeat the parameter to match several.

limit: typing.Optional[Limit] — Items per page (default: 20, max: 100)

page: typing.Optional[Page] — Page number (default: 1)

search: typing.Optional[EmployerSearch] — Case-insensitive search. Matches member name partially, and the member_id exactly — either your own reference id or the prefixed grpmbr_<...> id.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.submit_census_sync(...) -> CensusSyncDetailResponse

📝 Description

Submits a census sync payload for the specified employer. The employees in the payload will be queued for processing. Returns an accepted response with the timestamp of acceptance.

🔌 Usage

from vitable_connect import VitableConnect, CensusSyncEmployeeRequest, CensusSyncEmployeeAddressRequest
from vitable_connect.environment import VitableConnectEnvironment
import datetime

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.submit_census_sync(
    employer_id="empr_abc123def456",
    employees=[
        CensusSyncEmployeeRequest(
            reference_id="EMP-001",
            first_name="Jane",
            last_name="Doe",
            date_of_birth=datetime.date.fromisoformat("1990-05-15"),
            email="jane.doe@acme.com",
            phone="4155550100",
            address=CensusSyncEmployeeAddressRequest(
                address_line1="123 Main Street",
                address_line2="Apt 4B",
                city="San Francisco",
                state="CA",
                zipcode="94102",
            ),
            start_date=datetime.date.fromisoformat("2024-01-15"),
            employee_class="Full Time",
            compensation_type="Salary",
        ),
        CensusSyncEmployeeRequest(
            first_name="John",
            last_name="Smith",
            date_of_birth=datetime.date.fromisoformat("1985-11-20"),
            email="john.smith@acme.com",
            phone="4155550101",
            start_date=datetime.date.fromisoformat("2024-03-01"),
            employee_class="Part Time",
            compensation_type="Hourly",
        )
    ],
)

⚙️ Parameters

employer_id: EmployerId — Unique employer identifier (empr_*)

employees: typing.List[CensusSyncEmployeeRequest]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.list_employees(...) -> EmployeeListResponse

📝 Description

Retrieves a paginated list of employees for a specific employer. The caller must be authorized for the employer; an unknown or unauthorized employer returns 404. Results are paginated using page and limit parameters and can be narrowed with a case-insensitive search (first name, last name, or email) and an employment_status filter (active or terminated). Each employee includes payroll deductions from the most recent statement period. When a new deduction statement is generated, previous period deductions are replaced.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.list_employees(
    employer_id="empr_abc123def456",
    limit=20,
    page=1,
    search="jane",
)

⚙️ Parameters

employer_id: EmployerId — Unique employer identifier (empr_*)

employment_status: typing.Optional[EmployeeStatus] — Filter by employment status (active or terminated)

limit: typing.Optional[Limit] — Items per page (default: 20, max: 100)

page: typing.Optional[Page] — Page number (default: 1)

search: typing.Optional[EmployeeSearch] — Case-insensitive search across employee first name, last name, and email

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.get_hris(...) -> EmployerHrisResponse

📝 Description

Returns the employer's HRIS connection — provider, status, last sync, and synced row count — or null when the employer has no integration. The caller must be authorized for the employer; an unknown or unauthorized employer returns 404.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.get_hris(
    employer_id="empr_abc123def456",
)

⚙️ Parameters

employer_id: EmployerId — Unique employer identifier (empr_*)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.list_invoices(...) -> EmployerInvoicesListResponse

📝 Description

Returns a cursor-paginated page of the employer's billing invoices, newest first. Pass the next_offset from a previous page as offset to fetch the next page. The caller must be authorized for the employer; an unknown or unauthorized employer returns 404.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.list_invoices(
    employer_id="empr_abc123def456",
    limit=20,
)

⚙️ Parameters

employer_id: EmployerId — Unique employer identifier (empr_*)

limit: typing.Optional[Limit] — Maximum number of invoices per page

offset: typing.Optional[Offset] — Opaque cursor from a previous page's next_offset

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.get_invoice_pdf(...) -> EmployerInvoicePdfResponse

📝 Description

Returns the time-limited PDF download link for a single invoice belonging to the employer's billing customer. invoice_id is the external Chargebee id (not a prefixed UUID). The caller must be authorized for the employer; an unknown or unauthorized employer or invoice returns 404.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.get_invoice_pdf(
    employer_id="empr_abc123def456",
    invoice_id="INV-00042",
)

⚙️ Parameters

employer_id: EmployerId — Unique employer identifier (empr_*)

invoice_id: InvoiceId — External Chargebee invoice id (not a prefixed UUID).

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.get_payroll_access_setup(...) -> PayrollAccessSetupStatusResponse

📝 Description

Return whether the employer has submitted payroll access setup.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.get_payroll_access_setup(
    employer_id="empr_abc123def456",
)

⚙️ Parameters

employer_id: EmployerId

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.submit_payroll_access_setup(...) -> PayrollAccessSetupStatusResponse

📝 Description

Submit the employer's payroll access setup answers.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.submit_payroll_access_setup(
    employer_id="empr_abc123def456",
    employees_in_payroll_acknowledged=True,
    payroll_data_impacts_eligibility_acknowledged=True,
    classifications_accurate=True,
    all_benefit_eligible_employees_present=True,
    is_controlled_group=True,
    access_method="SELF_SETUP",
    has_additional_payroll_system=True,
)

⚙️ Parameters

employer_id: EmployerId

employees_in_payroll_acknowledged: bool — Attestation that all benefit-eligible employees appear in the payroll system.

payroll_data_impacts_eligibility_acknowledged: bool — Attestation that changes to payroll data affect benefit eligibility.

classifications_accurate: bool — Attestation that employee classifications in payroll are accurate. Set false to report corrections in the fields below.

all_benefit_eligible_employees_present: bool — Attestation that every benefit-eligible employee is present in payroll.

is_controlled_group: bool — Whether this employer belongs to a controlled group of related entities.

access_method: AccessMethod

has_additional_payroll_system: bool — Whether a second payroll system is in use. When true, supply the additional_* fields below.

classification_correction_source: typing.Optional[ClassificationCorrectionSource] — Where corrected classifications come from, when classifications_accurate is false.

misclassified_employee_names: typing.Optional[typing.List[str]] — Names of employees whose payroll classification needs correcting.

remaining_employee_action: typing.Optional[RemainingEmployeeAction] — How to handle employees still missing from the payroll system.

missing_employee_resolution: typing.Optional[MissingEmployeeResolution] — How any missing employees will be added, when some are absent.

same_payroll_covers_other_eins: typing.Optional[bool] — Whether this payroll system also covers other EINs in the controlled group.

login_url: typing.Optional[str] — Sign-in URL for the payroll system.

username: typing.Optional[str] — Username Vitable should use to access the payroll system.

phone: typing.Optional[str] — Phone number used for payroll-system verification codes.

password: typing.Optional[str] — Password Vitable should use to access the payroll system.

integration_confirmed: typing.Optional[bool] — Whether the payroll integration has been confirmed as working.

additional_access_method: typing.Optional[AdditionalAccessMethod] — How Vitable will access the second payroll system.

additional_login_url: typing.Optional[str] — Sign-in URL for the second payroll system.

additional_username: typing.Optional[str] — Username Vitable should use for the second payroll system.

additional_phone: typing.Optional[str] — Phone number used for second payroll-system verification codes.

additional_password: typing.Optional[str] — Password Vitable should use for the second payroll system.

additional_integration_confirmed: typing.Optional[bool] — Whether the second payroll integration has been confirmed as working.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.list_payroll_deduction_statements(...) -> EmployerPayrollDeductionStatementListResponse

📝 Description

Returns a paginated list of the employer's payroll-deduction statements, newest period first, each with its period, generation date, distinct employee count, total deduction, change-file link, and deduction frequency. Statements superseded by a later correction are excluded. The caller must be authorized for the employer; an unknown or unauthorized employer returns 404.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.list_payroll_deduction_statements(
    employer_id="empr_abc123def456",
    limit=20,
    page=1,
)

⚙️ Parameters

employer_id: EmployerId — Unique employer identifier (empr_*)

limit: typing.Optional[Limit] — Maximum number of statements per page

page: typing.Optional[Page] — Page number to retrieve (starts at 1)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.ensure_payroll_integration_email(...) -> PayrollIntegrationEmailResponse

📝 Description

Provision and return the employer's payroll integration email.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.ensure_payroll_integration_email(
    employer_id="empr_abc123def456",
)

⚙️ Parameters

employer_id: EmployerId

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.update_settings(...) -> EmployerSettingsResponse

📝 Description

Updates configuration settings for a specific employer. The employer must belong to the authenticated organization.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.update_settings(
    employer_id="empr_abc123def456",
    pay_frequency="bi_weekly",
)

⚙️ Parameters

employer_id: EmployerId — Unique employer identifier (empr_*)

pay_frequency: DeductionFrequency

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employers.list_hris_providers() -> OrganizationHrisProvidersResponse

📝 Description

Returns the distinct HRIS/payroll providers across the same book GET /v1/employers returns, sorted for display. Use these as the values for the employers list's hris_provider filter — filter on provider, show provider_label. The stored providers are free text, so they cannot be enumerated in advance.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.employers.list_hris_providers()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Enrollments

client.enrollments.get(...) -> EnrollmentResponse

📝 Description

Retrieves a single enrollment: the employee and employer it belongs to, the benefit product, its status, the coverage period, the employee payroll deduction and employer contribution, and the enrolled plan's Summary of Benefits and Coverage document when one is on file. An enrollment the caller cannot reach is indistinguishable from one that does not exist.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.enrollments.get(
    enrollment_id="enrl_AAAAAAAAAAAAAAAAAAAAAQ",
)

⚙️ Parameters

enrollment_id: EnrollmentId — Unique enrollment identifier (enrl_*)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.enrollments.reissue(...) -> ReissueEnrollmentResponse

📝 Description

Closes the targeted enrollment and creates a new unanswered enrollment for the same member and plan year. VPC never requires a qualifying life event; other products require an accepted, member-owned event outside open enrollment. User-backed callers must provide a reason; it is optional for organization API-key callers. Tenant mismatches return a non-disclosing 404 before the request body is validated.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.enrollments.reissue(
    enrollment_id="enrl_AAAAAAAAAAAAAAAAAAAAAQ",
    reason="Member needs a new election after a qualifying event.",
    ticket_number="BPT-1234",
    qualifying_life_event_id="qle_AAAAAAAAAAAAAAAAAAAAAQ",
)

⚙️ Parameters

enrollment_id: EnrollmentId — Unique enrollment identifier (enrl_*)

reason: typing.Optional[str] — Audit reason for the reissue; required for user-backed callers and optional for long-lived organization API-key callers

ticket_number: typing.Optional[str] — Optional support or operational ticket number

qualifying_life_event_id: typing.Optional[str] — Accepted member qualifying life event identifier (qle_*)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.enrollments.terminate(...)

📝 Description

Terminates enrolled coverage immediately. An accepted qualifying life event owned by the enrollment member is required unless the plan is VPC or ICHRA. User-backed callers must provide a reason; it is optional for organization API-key callers. API keys may act across the caller organization's book. Tenant mismatches return the same non-disclosing 404 before the request body is validated.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.enrollments.terminate(
    enrollment_id="enrl_AAAAAAAAAAAAAAAAAAAAAQ",
    reason="Member requested coverage termination after a qualifying event.",
    ticket_number="BPT-1234",
    qualifying_life_event_id="qle_AAAAAAAAAAAAAAAAAAAAAQ",
)

⚙️ Parameters

enrollment_id: EnrollmentId — Unique enrollment identifier (enrl_*)

reason: typing.Optional[str] — Audit reason for the termination; required for user-backed callers and optional for long-lived organization API-key callers

ticket_number: typing.Optional[str] — Optional support or operational ticket number

qualifying_life_event_id: typing.Optional[str] — Accepted member qualifying life event identifier (qle_*)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Groups

client.groups.list(...) -> GroupListResponse

📝 Description

Returns a paginated list of groups belonging to the authenticated organization.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.groups.list(
    limit=20,
    page=1,
)

⚙️ Parameters

limit: typing.Optional[Limit] — Items per page (default: 20, max: 100)

page: typing.Optional[Page] — Page number (default: 1)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.groups.create(...) -> GroupResponse

📝 Description

Creates a new group scoped to the authenticated organization.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.groups.create(
    name="Tier 1",
    external_reference_id="mol_seg_001",
)

⚙️ Parameters

name: str — Display name for the group.

external_reference_id: str — Your own identifier for this group. Use it to correlate the group with a record in your system; it must be unique within your organization.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.groups.get(...) -> GroupResponse

📝 Description

Retrieves a single group by its prefixed ID. Returns 404 if the group does not belong to the authenticated organization.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.groups.get(
    group_id="grp_abc123def456",
)

⚙️ Parameters

group_id: GroupId — Unique group identifier (grp_*)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.groups.update(...) -> GroupResponse

📝 Description

Partially updates a group's name or external reference ID. Returns 404 if the group does not belong to the authenticated organization.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.groups.update(
    group_id="grp_abc123def456",
    name="Tier 1 (renamed)",
    external_reference_id="mol_seg_001_v2",
)

⚙️ Parameters

group_id: GroupId — Unique group identifier (grp_*)

name: typing.Optional[str] — New display name for the group. Omit to leave unchanged.

external_reference_id: typing.Optional[str] — New external reference ID for the group. Omit to leave unchanged.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Members

client.members.get(...) -> MemberResponse

📝 Description

Retrieves a member's profile by ID — identity, demographics, address, contact details, tobacco status, and profile status. Access is scoped to the authenticated principal; a member not visible to the caller returns a 404.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.members.get(
    member_id="mbr_abc123def456",
)

⚙️ Parameters

member_id: MemberId — Unique member identifier (mbr_*)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.members.list_dependents(...) -> MemberDependentsResponse

📝 Description

Lists a member's active legal dependents — name, relationship, date of birth, age, and sex at birth. Access is scoped to the authenticated principal; a member not visible to the caller returns a 404.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.members.list_dependents(
    member_id="mbr_abc123def456",
)

⚙️ Parameters

member_id: MemberId

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.members.list_employments(...) -> MemberEmploymentsResponse

📝 Description

Lists a member's employment across every employer — the same employee record shape as the employer's employees list, plus the employer name. For an organization caller the rows are scoped to companies in that organization's book; a member (self/household) or Vitable Admin sees all employments. A member not visible to the caller returns a 404.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.members.list_employments(
    member_id="mbr_abc123def456",
)

⚙️ Parameters

member_id: MemberId

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.members.list_enrollments(...) -> MemberEnrollmentsResponse

📝 Description

Lists a member's benefit enrollments across every employer — benefit type and product, employer, carrier, plan, tier, employee deduction, employer contribution and total premium, the individual enrollment coverage boundary (coverage_end), the separate pre-effective cancellation boundary (cancelled_date), and the distinct benefit plan-year boundary (plan_year_coverage_end) used to determine whether the plan year itself has ended, the date the enrollment record was created (issued_date, the value Ops labels Issued on, reported for every row whatever the member answered), the window the member could answer in -- which never opens before the enrollment was issued, so a row issued mid-open-enrollment starts its window on its issue date -- whether a qualifying life event would currently be required for reissue under the product/open-enrollment rule, enrollment/open-enrollment window, and two statuses: election_status (what the member answered) and policy_status (what became of their coverage, null unless they enrolled). Every row includes a stable enrollment ID and the exact employer and benefit plan-year IDs used to fetch that row's plan-year detail. The full list is returned across all states so the client derives active plans (effective and upcoming) and the enrollment history from those per-row statuses. For an organization caller the rows are scoped to companies in that organization's book; a member (self/household) or Vitable Admin sees all enrollments. A member not visible to the caller returns a 404.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.members.list_enrollments(
    member_id="mbr_abc123def456",
)

⚙️ Parameters

member_id: MemberId

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.members.get_household(...) -> HouseholdMembersResponse

📝 Description

Lists a member's household as a per-participant table — the account holder plus each active household member, with name, relationship, member type, date of birth, and household-admin flag. Access is scoped to the authenticated principal; a member not visible to the caller (or with no household) returns a 404.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.members.get_household(
    member_id="mbr_abc123def456",
)

⚙️ Parameters

member_id: MemberId

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.members.list_id_cards(...) -> MemberDigitalBenefitCardsResponse

📝 Description

Lists a member's benefit ID cards — card type (medical, dental, vision, or rx), employer, plan, provider network, claims payer, carrier contact details, and the disclaimers printed on the card. Medical, dental and vision cards come from the member's active digital benefit cards; the rx card from the member's Ventegra pharmacy benefit (omitted when the member has no free-medication coverage), which carries no plan, network, or carrier details. Access is scoped to the authenticated principal, and an organization caller sees only cards from employers in its book; a member not visible to the caller returns a 404.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.members.list_id_cards(
    member_id="mbr_abc123def456",
)

⚙️ Parameters

member_id: MemberId

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.members.list_qualifying_life_events(...) -> MemberQualifyingLifeEventListResponse

📝 Description

Lists a member's qualifying life events, including events already used for another enrollment. Returns all statuses by default; pass the status query param to filter to one (e.g. approved). Events are ordered newest submission first with stable paging. Custom text is present only when submitted and is otherwise null. A member not visible to the caller returns a 404. API keys and unbound access tokens have organization-wide access. Employer-bound tokens require employment at the bound employer, and employee-bound tokens require the exact employee-member relationship. Organization or scope mismatches return a 404 before pagination is validated.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.members.list_qualifying_life_events(
    member_id="mbr_abc123def456",
    limit=20,
    page=1,
)

⚙️ Parameters

member_id: MemberId — Unique member identifier (mbr_*)

limit: typing.Optional[Limit] — Items per page (default: 20, max: 100)

page: typing.Optional[Page] — Page number (default: 1)

status: typing.Optional[Status] — Optional. Filter to a single QLE status; omit to return all statuses.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.members.list(...) -> MemberListResponse

📝 Description

Retrieves a paginated list of the members in the authenticated organization's book — identity, contact details, and address. The book covers members reached through an employer in the organization's book as well as members of a group it owns. Supports free-text search (name, email, phone number, or exact member id).

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.members.list(
    limit=20,
    page=1,
)

⚙️ Parameters

limit: typing.Optional[Limit] — Items per page (default: 20, max: 100)

page: typing.Optional[Page] — Page number (default: 1)

search: typing.Optional[MemberSearch] — Case-insensitive search across member name, email, and phone number; exact match on member id (prefixed or raw uuid)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Organizations

client.organizations.list() -> OrganizationsListResponse

📝 Description

Lists the organizations the authenticated caller is an active member of (paginated). Returns an empty list when the caller belongs to no organizations.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.organizations.list()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.organizations.create(...) -> Organization

📝 Description

Onboards the authenticated user's partner Organization: creates the local Organization + the creator's admin membership atomically, then mirrors it to WorkOS (creates the WorkOS org and binds the creator as admin). 409 organization_already_exists when the user already has an organization (v0: one organization per user).

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.organizations.create(
    name="Acme Brokerage",
    type="BROKERAGE",
)

⚙️ Parameters

name: str — Legal or trading name of the organization.

type: typing.Optional[CreateOrganizationRequestType] — Category of organization being onboarded.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Plans

client.plans.list(...) -> PlanListResponse

📝 Description

Returns a paginated list of benefit plans linked to the authenticated organization.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.plans.list(
    limit=20,
    page=1,
)

⚙️ Parameters

limit: typing.Optional[Limit] — Items per page (default: 20, max: 100)

page: typing.Optional[Page] — Page number (default: 1)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Webhook Events

client.webhook_events.list(...) -> WebhookEventListResponse

📝 Description

Retrieves a paginated list of webhook events for the authenticated organization. Supports filtering by event name, resource type, resource ID, and date range.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.webhook_events.list(
    limit=20,
    page=1,
)

⚙️ Parameters

created_after: typing.Optional[CreatedAfter]

created_before: typing.Optional[CreatedBefore]

event_name: typing.Optional[EventName]

enrollment.accepted - Enrollment Accepted
enrollment.terminated - Enrollment Terminated
enrollment.termination_rescheduled - Enrollment Termination Rescheduled
enrollment.elected - Enrollment Elected
enrollment.granted - Enrollment Granted
enrollment.waived - Enrollment Waived
enrollment.started - Enrollment Started
employee.eligibility_granted - Employee Eligibility Granted
employee.eligibility_terminated - Employee Eligibility Terminated
employee.deactivated - Employee Deactivated
employee.deduction_created - Employee Deduction Created

limit: typing.Optional[Limit]

page: typing.Optional[Page]

resource_id: typing.Optional[ResourceId]

resource_type: typing.Optional[ResourceType]

enrollment - Enrollment
employee - Employee
employer - Employer
dependent - Dependent
plan_year - Plan Year
payroll_deduction - Payroll Deduction

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhook_events.get(...) -> WebhookEventResponse

📝 Description

Retrieves a single webhook event by its prefixed ID. Returns 404 if the event does not exist or belongs to a different organization.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.webhook_events.get(
    event_id="event_id",
)

⚙️ Parameters

event_id: EventId

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhook_events.list_deliveries(...) -> ListWebhookEventDeliveriesResponse

📝 Description

Retrieves all delivery attempts for a webhook event. Returns up to 100 deliveries. Each delivery includes a computed status field (Pending, In Progress, Delivered, or Failed).

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.webhook_events.list_deliveries(
    event_id="event_id",
)

⚙️ Parameters

event_id: EventId

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Groups Members Sync

client.groups.members.sync.submit(...) -> GroupMemberSyncDetailResponse

📝 Description

Submits a member sync payload for the specified group. Members in the payload will be queued for processing asynchronously. Returns HTTP 202 with the batch ID and acceptance timestamp.

🔌 Usage

from vitable_connect import VitableConnect, GroupMemberSyncMemberRequest, AddressRequest
from vitable_connect.environment import VitableConnectEnvironment
import datetime

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.groups.members.sync.submit(
    group_id="grp_abc123def456",
    members=[
        GroupMemberSyncMemberRequest(
            reference_id="EMP-001",
            first_name="Jane",
            last_name="Doe",
            date_of_birth=datetime.date.fromisoformat("1990-05-15"),
            phone="4155550100",
            plan_id="pln_abc123def456",
            address=AddressRequest(
                address_line1="123 Main Street",
                address_line2="Apt 4B",
                city="San Francisco",
                state="CA",
                zipcode="94102",
            ),
            email="jane.doe@acme.com",
        )
    ],
)

⚙️ Parameters

group_id: GroupId

members: typing.List[GroupMemberSyncMemberRequest]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.groups.members.sync.get(...) -> GroupMemberSyncRequestDetailResponse

📝 Description

Retrieves a previously-submitted group member sync request by its grpmsr_ ID. Returns the acceptance timestamp, completion timestamp (if processing has finished), and the per-member results once available. While processing is in flight, completed_at and results are null.

🔌 Usage

from vitable_connect import VitableConnect
from vitable_connect.environment import VitableConnectEnvironment

client = VitableConnect(
    api_key="<token>",
    environment=VitableConnectEnvironment.PRODUCTION,
)

client.groups.members.sync.get(
    group_id="grp_abc123def456",
    request_id="request_id",
)

⚙️ Parameters

group_id: GroupId

request_id: RequestId

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Uh oh!

FilesExpand file tree

reference.md

Latest commit

History

reference.md

File metadata and controls

Reference

Auth

📝 Description

🔌 Usage

⚙️ Parameters

Employees

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

Employers

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

Enrollments

📝 Description

🔌 Usage