# Employers ## List employers `employers.list(EmployerListParams**kwargs) -> SyncPageNumberPage[Employer]` **get** `/v1/employers` Retrieves a paginated list of all employers belonging to the authenticated organization. Results are sorted by creation date (newest first) and paginated using page and limit parameters. ### Parameters - `limit: Optional[int]` Items per page (default: 20, max: 100) - `page: Optional[int]` Page number (default: 1) ### Returns - `class Employer: …` Serializer for Employer entity in public API responses. - `id: str` Unique employer identifier with 'empr_' prefix - `active: bool` Whether the employer is currently active in the system - `address: Address` Nested address within EmployerSerializer. - `address_line_1: str` Primary street address - `city: str` City name - `state: str` Two-letter state code (e.g., CA, NY) - `zipcode: str` ZIP code (5 or 9 digit) - `address_line_2: Optional[str]` Secondary street address (apt, suite, etc.) - `created_at: datetime` Timestamp when the employer was created - `ein: Optional[str]` Employer Identification Number (masked in responses) - `eligibility_policy_id: Optional[str]` ID of the benefit eligibility policy (epol_*), if assigned - `legal_name: str` Legal business name for compliance and tax purposes - `name: str` Display name of the employer - `organization_id: Optional[str]` ID of the parent organization (org_*) - `updated_at: datetime` Timestamp when the employer was last updated - `email: Optional[str]` Email address for billing and communications - `phone_number: Optional[str]` Employer phone number (E.164 format recommended) - `reference_id: Optional[str]` Partner-assigned reference ID for the employer ### 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.employers.list() page = page.data[0] print(page.id) ``` #### Response ```json { "data": [ { "id": "empr_abc123def456", "organization_id": "org_xyz789", "name": "Acme Corporation", "legal_name": "Acme Corporation Inc.", "ein": "XX-XXX1234", "reference_id": "partner-emp-001", "email": "hr@acme.com", "phone_number": "4155550100", "active": true, "address": { "address_line_1": "123 Main Street", "address_line_2": "Suite 100", "city": "San Francisco", "state": "CA", "zipcode": "94102" }, "eligibility_policy_id": "epol_policy123", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-06-20T14:45:00Z" }, { "id": "empr_def456ghi789", "organization_id": "org_xyz789", "name": "TechStart Inc", "legal_name": "TechStart Incorporated", "ein": "XX-XXX5678", "reference_id": null, "email": "contact@techstart.com", "phone_number": null, "active": true, "address": { "address_line_1": "456 Innovation Drive", "address_line_2": "", "city": "Austin", "state": "TX", "zipcode": "78701" }, "eligibility_policy_id": null, "created_at": "2024-03-01T09:00:00Z", "updated_at": "2024-03-01T09:00:00Z" } ], "pagination": { "page": 1, "limit": 20, "total": 2, "total_pages": 1 } } ``` ## Create employer `employers.create(EmployerCreateParams**kwargs) -> EmployerResponse` **post** `/v1/employers` 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. ### Parameters - `address: Address` Employer address - `address_line_1: str` Primary street address - `city: str` City name - `state: str` Two-letter state code - `zipcode: str` ZIP code - `address_line_2: Optional[str]` Secondary street address - `ein: str` Employer Identification Number (format: XX-XXXXXXX) - `email: str` Email address for billing and communications - `legal_name: str` Legal business name - `name: str` Employer display name - `phone_number: Optional[str]` Employer phone number (10-digit US format, e.g. 5551234567) - `reference_id: Optional[str]` External reference ID for this employer ### Returns - `class EmployerResponse: …` Response containing a single employer resource. - `data: Employer` Serializer for Employer entity in public API responses. - `id: str` Unique employer identifier with 'empr_' prefix - `active: bool` Whether the employer is currently active in the system - `address: Address` Nested address within EmployerSerializer. - `address_line_1: str` Primary street address - `city: str` City name - `state: str` Two-letter state code (e.g., CA, NY) - `zipcode: str` ZIP code (5 or 9 digit) - `address_line_2: Optional[str]` Secondary street address (apt, suite, etc.) - `created_at: datetime` Timestamp when the employer was created - `ein: Optional[str]` Employer Identification Number (masked in responses) - `eligibility_policy_id: Optional[str]` ID of the benefit eligibility policy (epol_*), if assigned - `legal_name: str` Legal business name for compliance and tax purposes - `name: str` Display name of the employer - `organization_id: Optional[str]` ID of the parent organization (org_*) - `updated_at: datetime` Timestamp when the employer was last updated - `email: Optional[str]` Email address for billing and communications - `phone_number: Optional[str]` Employer phone number (E.164 format recommended) - `reference_id: Optional[str]` Partner-assigned reference ID for the employer ### 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 ) employer_response = client.employers.create( address={ "address_line_1": "789 Business Blvd", "address_line_2": "Floor 5", "city": "Seattle", "state": "WA", "zipcode": "98101", }, ein="12-3456789", email="hr@newco.com", legal_name="NewCo Industries LLC", name="NewCo Industries", phone_number="2065550100", reference_id="partner-emp-001", ) print(employer_response.data) ``` #### Response ```json { "data": { "id": "empr_new123abc", "organization_id": "org_xyz789", "name": "NewCo Industries", "legal_name": "NewCo Industries LLC", "ein": "XX-XXX6789", "reference_id": null, "email": "hr@newco.com", "phone_number": "2065550100", "active": true, "address": { "address_line_1": "789 Business Blvd", "address_line_2": "Floor 5", "city": "Seattle", "state": "WA", "zipcode": "98101" }, "eligibility_policy_id": null, "created_at": "2024-11-26T10:00:00Z", "updated_at": "2024-11-26T10:00:00Z" } } ``` ## Get employer `employers.retrieve(stremployer_id) -> EmployerResponse` **get** `/v1/employers/{employer_id}` Retrieves detailed information for a specific employer by ID. The employer must belong to the authenticated organization. ### Parameters - `employer_id: str` Unique employer identifier (empr_*) ### Returns - `class EmployerResponse: …` Response containing a single employer resource. - `data: Employer` Serializer for Employer entity in public API responses. - `id: str` Unique employer identifier with 'empr_' prefix - `active: bool` Whether the employer is currently active in the system - `address: Address` Nested address within EmployerSerializer. - `address_line_1: str` Primary street address - `city: str` City name - `state: str` Two-letter state code (e.g., CA, NY) - `zipcode: str` ZIP code (5 or 9 digit) - `address_line_2: Optional[str]` Secondary street address (apt, suite, etc.) - `created_at: datetime` Timestamp when the employer was created - `ein: Optional[str]` Employer Identification Number (masked in responses) - `eligibility_policy_id: Optional[str]` ID of the benefit eligibility policy (epol_*), if assigned - `legal_name: str` Legal business name for compliance and tax purposes - `name: str` Display name of the employer - `organization_id: Optional[str]` ID of the parent organization (org_*) - `updated_at: datetime` Timestamp when the employer was last updated - `email: Optional[str]` Email address for billing and communications - `phone_number: Optional[str]` Employer phone number (E.164 format recommended) - `reference_id: Optional[str]` Partner-assigned reference ID for the employer ### 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 ) employer_response = client.employers.retrieve( "empr_abc123def456", ) print(employer_response.data) ``` #### Response ```json { "data": { "id": "empr_abc123def456", "organization_id": "org_xyz789", "name": "Acme Corporation", "legal_name": "Acme Corporation Inc.", "ein": "XX-XXX1234", "reference_id": "partner-emp-001", "email": "hr@acme.com", "phone_number": "4155550100", "active": true, "address": { "address_line_1": "123 Main Street", "address_line_2": "Suite 100", "city": "San Francisco", "state": "CA", "zipcode": "94102" }, "eligibility_policy_id": "epol_policy123", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-06-20T14:45:00Z" } } ``` ## Create eligibility policy `employers.create_benefit_eligibility_policy(stremployer_id, EmployerCreateBenefitEligibilityPolicyParams**kwargs) -> BenefitEligibilityPolicyResponse` **post** `/v1/employers/{employer_id}/benefit-eligibility-policies` Creates a benefit eligibility policy for the specified employer. ### Parameters - `employer_id: str` Unique employer identifier (empr_*) - `classification: str` Which employee classifications are eligible. One of: full_time, part_time, all - `waiting_period: str` Waiting period before eligibility. One of: first_of_following_month, 30_days, 60_days, none ### Returns - `class BenefitEligibilityPolicyResponse: …` Response containing a single benefit eligibility policy resource. - `data: BenefitEligibilityPolicy` - `id: str` - `active: bool` - `classification: str` - `created_at: datetime` - `employer_id: str` - `updated_at: datetime` - `waiting_period: str` ### 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 ) benefit_eligibility_policy_response = client.employers.create_benefit_eligibility_policy( employer_id="empr_abc123def456", classification="classification", waiting_period="waiting_period", ) print(benefit_eligibility_policy_response.data) ``` #### Response ```json { "data": { "id": "id", "active": true, "classification": "classification", "created_at": "2019-12-27T18:11:19.117Z", "employer_id": "employer_id", "updated_at": "2019-12-27T18:11:19.117Z", "waiting_period": "waiting_period" } } ``` ## Submit census sync `employers.submit_census_sync(stremployer_id, EmployerSubmitCensusSyncParams**kwargs) -> EmployerSubmitCensusSyncResponse` **post** `/v1/employers/{employer_id}/census-sync` 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. ### Parameters - `employer_id: str` Unique employer identifier (empr_*) - `employees: Iterable[Employee]` - `date_of_birth: Union[null, null]` - `email: str` - `first_name: str` - `last_name: str` - `phone: str` - `address: Optional[EmployeeAddress]` - `address_line_1: str` - `city: str` - `state: Literal["AL", "AK", "AZ", 59 more]` * `AL` - AL * `AK` - AK * `AZ` - AZ * `AR` - AR * `CA` - CA * `CO` - CO * `CT` - CT * `DC` - DC * `DE` - DE * `FL` - FL * `GA` - GA * `HI` - HI * `ID` - ID * `IL` - IL * `IN` - IN * `IA` - IA * `KS` - KS * `KY` - KY * `LA` - LA * `ME` - ME * `MD` - MD * `MA` - MA * `MI` - MI * `MN` - MN * `MS` - MS * `MO` - MO * `MT` - MT * `NE` - NE * `NV` - NV * `NH` - NH * `NJ` - NJ * `NM` - NM * `NY` - NY * `NC` - NC * `ND` - ND * `OH` - OH * `OK` - OK * `OR` - OR * `PA` - PA * `RI` - RI * `SC` - SC * `SD` - SD * `TN` - TN * `TX` - TX * `UT` - UT * `VT` - VT * `VA` - VA * `WA` - WA * `WI` - WI * `WV` - WV * `WY` - WY * `PR` - PR * `GU` - GU * `AS` - AS * `VI` - VI * `MP` - MP * `MH` - MH * `PW` - PW * `FM` - FM * `AE` - AE * `AA` - AA * `AP` - AP - `"AL"` - `"AK"` - `"AZ"` - `"AR"` - `"CA"` - `"CO"` - `"CT"` - `"DC"` - `"DE"` - `"FL"` - `"GA"` - `"HI"` - `"ID"` - `"IL"` - `"IN"` - `"IA"` - `"KS"` - `"KY"` - `"LA"` - `"ME"` - `"MD"` - `"MA"` - `"MI"` - `"MN"` - `"MS"` - `"MO"` - `"MT"` - `"NE"` - `"NV"` - `"NH"` - `"NJ"` - `"NM"` - `"NY"` - `"NC"` - `"ND"` - `"OH"` - `"OK"` - `"OR"` - `"PA"` - `"RI"` - `"SC"` - `"SD"` - `"TN"` - `"TX"` - `"UT"` - `"VT"` - `"VA"` - `"WA"` - `"WI"` - `"WV"` - `"WY"` - `"PR"` - `"GU"` - `"AS"` - `"VI"` - `"MP"` - `"MH"` - `"PW"` - `"FM"` - `"AE"` - `"AA"` - `"AP"` - `zipcode: str` - `address_line_2: Optional[str]` - `compensation_type: Optional[Literal["Salary", "Hourly"]]` * `Salary` - Salary * `Hourly` - Hourly - `"Salary"` - `"Hourly"` - `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"` - `reference_id: Optional[str]` - `start_date: Optional[Union[null, null, null]]` ### Returns - `class EmployerSubmitCensusSyncResponse: …` Response containing a single census sync detail resource. - `data: Data` - `accepted_at: datetime` - `employer_id: str` ### Example ```python import os from datetime import date from vitable_connect import VitableConnect client = VitableConnect( api_key=os.environ.get("VITABLE_CONNECT_API_KEY"), # This is the default and can be omitted ) response = client.employers.submit_census_sync( employer_id="empr_abc123def456", employees=[{ "reference_id": "EMP-001", "first_name": "Jane", "last_name": "Doe", "date_of_birth": date.fromisoformat("1990-05-15"), "email": "jane.doe@acme.com", "phone": "4155550100", "address": { "address_line_1": "123 Main Street", "address_line_2": "Apt 4B", "city": "San Francisco", "state": "CA", "zipcode": "94102", }, "start_date": date.fromisoformat("2024-01-15"), "employee_class": "Full Time", "compensation_type": "Salary", }, { "first_name": "John", "last_name": "Smith", "date_of_birth": date.fromisoformat("1985-11-20"), "email": "john.smith@acme.com", "phone": "4155550101", "start_date": date.fromisoformat("2024-03-01"), "employee_class": "Part Time", "compensation_type": "Hourly", }], ) print(response.data) ``` #### Response ```json { "data": { "accepted_at": "2019-12-27T18:11:19.117Z", "employer_id": "employer_id" } } ``` ## List employees `employers.list_employees(stremployer_id, EmployerListEmployeesParams**kwargs) -> SyncPageNumberPage[Employee]` **get** `/v1/employers/{employer_id}/employees` Retrieves a paginated list of all employees for a specific employer. Results are paginated using page and limit parameters. ### Parameters - `employer_id: str` Unique employer identifier (empr_*) - `limit: Optional[int]` Items per page (default: 20, max: 100) - `page: Optional[int]` Page number (default: 1) ### Returns - `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 ### 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.employers.list_employees( employer_id="empr_abc123def456", ) page = page.data[0] print(page.id) ``` #### 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" } ], "pagination": { "page": 1, "limit": 20, "total": 1, "total_pages": 1 } } ``` ## Domain Types ### Employer - `class Employer: …` Serializer for Employer entity in public API responses. - `id: str` Unique employer identifier with 'empr_' prefix - `active: bool` Whether the employer is currently active in the system - `address: Address` Nested address within EmployerSerializer. - `address_line_1: str` Primary street address - `city: str` City name - `state: str` Two-letter state code (e.g., CA, NY) - `zipcode: str` ZIP code (5 or 9 digit) - `address_line_2: Optional[str]` Secondary street address (apt, suite, etc.) - `created_at: datetime` Timestamp when the employer was created - `ein: Optional[str]` Employer Identification Number (masked in responses) - `eligibility_policy_id: Optional[str]` ID of the benefit eligibility policy (epol_*), if assigned - `legal_name: str` Legal business name for compliance and tax purposes - `name: str` Display name of the employer - `organization_id: Optional[str]` ID of the parent organization (org_*) - `updated_at: datetime` Timestamp when the employer was last updated - `email: Optional[str]` Email address for billing and communications - `phone_number: Optional[str]` Employer phone number (E.164 format recommended) - `reference_id: Optional[str]` Partner-assigned reference ID for the employer ### Employer Response - `class EmployerResponse: …` Response containing a single employer resource. - `data: Employer` Serializer for Employer entity in public API responses. - `id: str` Unique employer identifier with 'empr_' prefix - `active: bool` Whether the employer is currently active in the system - `address: Address` Nested address within EmployerSerializer. - `address_line_1: str` Primary street address - `city: str` City name - `state: str` Two-letter state code (e.g., CA, NY) - `zipcode: str` ZIP code (5 or 9 digit) - `address_line_2: Optional[str]` Secondary street address (apt, suite, etc.) - `created_at: datetime` Timestamp when the employer was created - `ein: Optional[str]` Employer Identification Number (masked in responses) - `eligibility_policy_id: Optional[str]` ID of the benefit eligibility policy (epol_*), if assigned - `legal_name: str` Legal business name for compliance and tax purposes - `name: str` Display name of the employer - `organization_id: Optional[str]` ID of the parent organization (org_*) - `updated_at: datetime` Timestamp when the employer was last updated - `email: Optional[str]` Email address for billing and communications - `phone_number: Optional[str]` Employer phone number (E.164 format recommended) - `reference_id: Optional[str]` Partner-assigned reference ID for the employer