# Employees ## Get employee `employees.retrieve(stremployee_id) -> EmployeeRetrieveResponse` **get** `/v1/employees/{employee_id}` Retrieves detailed information for a specific employee by ID. Returns employee details including personal information and employment status. ### Parameters - `employee_id: str` Unique employee identifier (empl_*) ### Returns - `class EmployeeRetrieveResponse: …` Response containing a single employee resource. - `data: Employee` - `id: str` Unique employee identifier with 'empl_' prefix - `created_at: datetime` Timestamp when the employee was created - `date_of_birth: date` Date of birth (YYYY-MM-DD) - `email: str` Email address - `enrollments: List[Enrollment]` Benefit enrollments for this employee - `id: str` Unique enrollment identifier with 'enrl_' prefix - `status: EnrollmentStatus` * `pending` - Pending * `enrolled` - Enrolled * `waived` - Waived * `inactive` - Inactive - `"pending"` - `"enrolled"` - `"waived"` - `"inactive"` - `answered_at: Optional[datetime]` Timestamp when the enrollment decision was made - `first_name: str` Employee's legal first name - `last_name: str` Employee's legal last name - `member_id: str` Unique member identifier with 'mbr_' prefix - `status: str` Employee status (active or terminated) - `updated_at: datetime` Timestamp when the employee was last updated - `address: Optional[Address]` Employee's residential address - `address_line_1: str` Primary street address - `city: str` City name - `state: str` Two-letter state code (e.g., CA, NY) - `zipcode: str` ZIP code (5 or 9 digit) - `address_line_2: Optional[str]` Secondary street address (apt, suite, etc.) - `employee_class: Optional[EmployeeClass]` * `Full Time` - Full Time * `Part Time` - Part Time * `Temporary` - Temporary * `Intern` - Intern * `Seasonal` - Seasonal * `Individual Contractor` - Individual Contractor - `"Full Time"` - `"Part Time"` - `"Temporary"` - `"Intern"` - `"Seasonal"` - `"Individual Contractor"` - `gender: Optional[str]` Gender identity, if provided - `hire_date: Optional[date]` Employee's hire date with the employer - `phone: Optional[str]` Phone number (10-digit US domestic string) - `reference_id: Optional[str]` Partner-assigned reference ID for the employee - `suffix: Optional[str]` Name suffix (e.g., Jr., Sr., III) - `termination_date: Optional[date]` Employee's termination date, if terminated ### Example ```python import os from vitable_connect import VitableConnect client = VitableConnect( api_key=os.environ.get("VITABLE_CONNECT_API_KEY"), # This is the default and can be omitted ) employee = client.employees.retrieve( "empl_abc123def456", ) print(employee.data) ``` #### Response ```json { "data": { "id": "empl_abc123", "member_id": "mbr_xyz789", "reference_id": "partner-ee-001", "first_name": "John", "last_name": "Doe", "suffix": null, "email": "john.doe@example.com", "date_of_birth": "1985-06-15", "gender": null, "phone": "4155551234", "employee_class": "Full Time", "status": "active", "hire_date": "2023-01-15", "termination_date": null, "address": { "address_line_1": "456 Oak Avenue", "address_line_2": "Apt 2B", "city": "San Francisco", "state": "CA", "zipcode": "94102" }, "enrollments": [ { "id": "enrl_abc123", "status": "enrolled", "answered_at": "2023-01-20T10:00:00Z" } ], "created_at": "2023-01-15T09:00:00Z", "updated_at": "2024-06-01T14:30:00Z" } } ``` ## List employee enrollments `employees.list_enrollments(stremployee_id, EmployeeListEnrollmentsParams**kwargs) -> SyncPageNumberPage[Enrollment]` **get** `/v1/employees/{employee_id}/enrollments` Retrieves a paginated list of benefit enrollments for an employee. ### Parameters - `employee_id: str` Unique employee identifier (empl_*) - `limit: Optional[int]` Items per page (default: 20, max: 100) - `page: Optional[int]` Page number (default: 1) ### Returns - `class Enrollment: …` - `id: str` Unique enrollment identifier (enrl_*) - `answered_at: Optional[datetime]` When the employee enrolled or waived - `benefit: Benefit` Nested benefit product summary - `id: str` Benefit product ID (bprd_*) - `category: Literal["Medical", "Dental", "Vision", "Hospital"]` * `Medical` - Medical * `Dental` - Dental * `Vision` - Vision * `Hospital` - Hospital - `"Medical"` - `"Dental"` - `"Vision"` - `"Hospital"` - `name: str` Display name of the benefit product - `product_code: Literal["EBA", "VPC", "VPC_CORE", 12 more]` * `EBA` - Eba Mec * `VPC` - Vpc Enhanced * `VPC_CORE` - Vpc Core * `MEC` - Vpc Mec * `MEC2` - Mec2 * `MEC_PLUS` - Mec Plus * `MVP` - Mvp * `MVP2` - Mvp2 * `MVPSL` - Mvpsl * `MVPSL2` - Mvpsl2 * `VD` - Dental * `VV` - Vision * `ICHRA` - Ichra * `ICHRA_PREMIUM_PLUS` - Ichra Premium Plus * `ICHRA_REIMBURSEMENT_ONLY` - Ichra Reimbursement Only - `"EBA"` - `"VPC"` - `"VPC_CORE"` - `"MEC"` - `"MEC2"` - `"MEC_PLUS"` - `"MVP"` - `"MVP2"` - `"MVPSL"` - `"MVPSL2"` - `"VD"` - `"VV"` - `"ICHRA"` - `"ICHRA_PREMIUM_PLUS"` - `"ICHRA_REIMBURSEMENT_ONLY"` - `coverage_end: Optional[date]` Coverage period end date - `coverage_start: date` Coverage period start date - `created_at: datetime` When the enrollment was created - `employee_deduction_in_cents: Optional[int]` Employee monthly payroll deduction in cents - `employee_id: str` Employee ID (empl_*) - `employer_contribution_in_cents: Optional[int]` Employer monthly contribution in cents - `employer_id: str` Employer ID (empr_*) - `status: EnrollmentStatus` * `pending` - Pending * `enrolled` - Enrolled * `waived` - Waived * `inactive` - Inactive - `"pending"` - `"enrolled"` - `"waived"` - `"inactive"` - `terminated_at: Optional[datetime]` When coverage was terminated - `updated_at: datetime` When the enrollment was last updated ### Example ```python import os from vitable_connect import VitableConnect client = VitableConnect( api_key=os.environ.get("VITABLE_CONNECT_API_KEY"), # This is the default and can be omitted ) page = client.employees.list_enrollments( employee_id="empl_abc123def456", ) page = page.data[0] print(page.id) ``` #### Response ```json { "data": [ { "id": "enrl_abc123def456", "employee_id": "empl_xyz789ghi012", "employer_id": "empr_def456ghi789", "benefit": { "id": "bprd_medical456", "name": "MEC Plus", "product_code": "MEC_PLUS", "category": "Medical" }, "status": "enrolled", "coverage_start": "2026-04-01", "coverage_end": "2027-03-31", "employee_deduction_in_cents": 5000, "employer_contribution_in_cents": 25000, "answered_at": "2026-01-20T14:30:00Z", "terminated_at": null, "created_at": "2026-01-15T10:30:00Z", "updated_at": "2026-01-15T10:30:00Z" } ], "pagination": { "page": 1, "limit": 20, "total": 1, "total_pages": 1 } } ``` ## Domain Types ### Employee - `class Employee: …` - `id: str` Unique employee identifier with 'empl_' prefix - `created_at: datetime` Timestamp when the employee was created - `date_of_birth: date` Date of birth (YYYY-MM-DD) - `email: str` Email address - `enrollments: List[Enrollment]` Benefit enrollments for this employee - `id: str` Unique enrollment identifier with 'enrl_' prefix - `status: EnrollmentStatus` * `pending` - Pending * `enrolled` - Enrolled * `waived` - Waived * `inactive` - Inactive - `"pending"` - `"enrolled"` - `"waived"` - `"inactive"` - `answered_at: Optional[datetime]` Timestamp when the enrollment decision was made - `first_name: str` Employee's legal first name - `last_name: str` Employee's legal last name - `member_id: str` Unique member identifier with 'mbr_' prefix - `status: str` Employee status (active or terminated) - `updated_at: datetime` Timestamp when the employee was last updated - `address: Optional[Address]` Employee's residential address - `address_line_1: str` Primary street address - `city: str` City name - `state: str` Two-letter state code (e.g., CA, NY) - `zipcode: str` ZIP code (5 or 9 digit) - `address_line_2: Optional[str]` Secondary street address (apt, suite, etc.) - `employee_class: Optional[EmployeeClass]` * `Full Time` - Full Time * `Part Time` - Part Time * `Temporary` - Temporary * `Intern` - Intern * `Seasonal` - Seasonal * `Individual Contractor` - Individual Contractor - `"Full Time"` - `"Part Time"` - `"Temporary"` - `"Intern"` - `"Seasonal"` - `"Individual Contractor"` - `gender: Optional[str]` Gender identity, if provided - `hire_date: Optional[date]` Employee's hire date with the employer - `phone: Optional[str]` Phone number (10-digit US domestic string) - `reference_id: Optional[str]` Partner-assigned reference ID for the employee - `suffix: Optional[str]` Name suffix (e.g., Jr., Sr., III) - `termination_date: Optional[date]` Employee's termination date, if terminated ### Employee Class - `Literal["Full Time", "Part Time", "Temporary", 3 more]` * `Full Time` - Full Time * `Part Time` - Part Time * `Temporary` - Temporary * `Intern` - Intern * `Seasonal` - Seasonal * `Individual Contractor` - Individual Contractor - `"Full Time"` - `"Part Time"` - `"Temporary"` - `"Intern"` - `"Seasonal"` - `"Individual Contractor"` ### Pagination - `class Pagination: …` Pagination metadata for list responses. - `limit: int` Items per page - `page: int` Current page number - `total: int` Total number of items - `total_pages: int` Total number of pages