# Employers ## List employers `employers.list(**kwargs) -> PageNumberPage` **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: Integer` Items per page (default: 20, max: 100) - `page: Integer` Page number (default: 1) ### Returns - `class Employer` Serializer for Employer entity in public API responses. - `id: String` Unique employer identifier with 'empr_' prefix - `active: bool` Whether the employer is currently active in the system - `address: { address_line_1, city, state, 2 more}` Nested address within EmployerSerializer. - `address_line_1: String` Primary street address - `city: String` City name - `state: String` Two-letter state code (e.g., CA, NY) - `zipcode: String` ZIP code (5 or 9 digit) - `address_line_2: String` Secondary street address (apt, suite, etc.) - `created_at: Time` Timestamp when the employer was created - `ein: String` Employer Identification Number (masked in responses) - `eligibility_policy_id: String` ID of the benefit eligibility policy (epol_*), if assigned - `legal_name: String` Legal business name for compliance and tax purposes - `name: String` Display name of the employer - `organization_id: String` ID of the parent organization (org_*) - `updated_at: Time` Timestamp when the employer was last updated - `email: String` Email address for billing and communications - `phone_number: String` Employer phone number (E.164 format recommended) - `reference_id: String` Partner-assigned reference ID for the employer ### Example ```ruby require "vitable_connect" vitable_connect = VitableConnect::Client.new( api_key: "My API Key", environment: "environment_1" # defaults to "production" ) page = vitable_connect.employers.list puts(page) ``` #### 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(**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_line_1, city, state, 2 more}` Employer address - `address_line_1: String` Primary street address - `city: String` City name - `state: String` Two-letter state code - `zipcode: String` ZIP code - `address_line_2: String` Secondary street address - `ein: String` Employer Identification Number (format: XX-XXXXXXX) - `email: String` Email address for billing and communications - `legal_name: String` Legal business name - `name: String` Employer display name - `phone_number: String` Employer phone number (10-digit US format, e.g. 5551234567) - `reference_id: String` 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: String` Unique employer identifier with 'empr_' prefix - `active: bool` Whether the employer is currently active in the system - `address: { address_line_1, city, state, 2 more}` Nested address within EmployerSerializer. - `address_line_1: String` Primary street address - `city: String` City name - `state: String` Two-letter state code (e.g., CA, NY) - `zipcode: String` ZIP code (5 or 9 digit) - `address_line_2: String` Secondary street address (apt, suite, etc.) - `created_at: Time` Timestamp when the employer was created - `ein: String` Employer Identification Number (masked in responses) - `eligibility_policy_id: String` ID of the benefit eligibility policy (epol_*), if assigned - `legal_name: String` Legal business name for compliance and tax purposes - `name: String` Display name of the employer - `organization_id: String` ID of the parent organization (org_*) - `updated_at: Time` Timestamp when the employer was last updated - `email: String` Email address for billing and communications - `phone_number: String` Employer phone number (E.164 format recommended) - `reference_id: String` Partner-assigned reference ID for the employer ### Example ```ruby require "vitable_connect" vitable_connect = VitableConnect::Client.new( api_key: "My API Key", environment: "environment_1" # defaults to "production" ) employer_response = vitable_connect.employers.create( address: {address_line_1: "789 Business Blvd", city: "Seattle", state: "WA", zipcode: "98101"}, ein: "12-3456789", email: "hr@newco.com", legal_name: "NewCo Industries LLC", name: "NewCo Industries" ) puts(employer_response) ``` #### 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(employer_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: String` Unique employer identifier (empr_*) ### Returns - `class EmployerResponse` Response containing a single employer resource. - `data: Employer` Serializer for Employer entity in public API responses. - `id: String` Unique employer identifier with 'empr_' prefix - `active: bool` Whether the employer is currently active in the system - `address: { address_line_1, city, state, 2 more}` Nested address within EmployerSerializer. - `address_line_1: String` Primary street address - `city: String` City name - `state: String` Two-letter state code (e.g., CA, NY) - `zipcode: String` ZIP code (5 or 9 digit) - `address_line_2: String` Secondary street address (apt, suite, etc.) - `created_at: Time` Timestamp when the employer was created - `ein: String` Employer Identification Number (masked in responses) - `eligibility_policy_id: String` ID of the benefit eligibility policy (epol_*), if assigned - `legal_name: String` Legal business name for compliance and tax purposes - `name: String` Display name of the employer - `organization_id: String` ID of the parent organization (org_*) - `updated_at: Time` Timestamp when the employer was last updated - `email: String` Email address for billing and communications - `phone_number: String` Employer phone number (E.164 format recommended) - `reference_id: String` Partner-assigned reference ID for the employer ### Example ```ruby require "vitable_connect" vitable_connect = VitableConnect::Client.new( api_key: "My API Key", environment: "environment_1" # defaults to "production" ) employer_response = vitable_connect.employers.retrieve("empr_abc123def456") puts(employer_response) ``` #### 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(employer_id, **kwargs) -> BenefitEligibilityPolicyResponse` **post** `/v1/employers/{employer_id}/benefit-eligibility-policies` Creates a benefit eligibility policy for the specified employer. ### Parameters - `employer_id: String` Unique employer identifier (empr_*) - `classification: String` Which employee classifications are eligible. One of: full_time, part_time, all - `waiting_period: String` 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: String` - `active: bool` - `classification: String` - `created_at: Time` - `employer_id: String` - `updated_at: Time` - `waiting_period: String` ### Example ```ruby require "vitable_connect" vitable_connect = VitableConnect::Client.new( api_key: "My API Key", environment: "environment_1" # defaults to "production" ) benefit_eligibility_policy_response = vitable_connect.employers.create_benefit_eligibility_policy( "empr_abc123def456", classification: "classification", waiting_period: "waiting_period" ) puts(benefit_eligibility_policy_response) ``` #### 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(employer_id, **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: String` Unique employer identifier (empr_*) - `employees: Array[{ date_of_birth, email, first_name, 7 more}]` - `date_of_birth: Date` - `email: String` - `first_name: String` - `last_name: String` - `phone: String` - `address: { address_line_1, city, state, 2 more}` - `address_line_1: String` - `city: String` - `state: :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: String` - `address_line_2: String` - `compensation_type: :Salary | :Hourly` * `Salary` - Salary * `Hourly` - Hourly - `:Salary` - `:Hourly` - `employee_class: 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: String` - `start_date: Date` ### Returns - `class EmployerSubmitCensusSyncResponse` Response containing a single census sync detail resource. - `data: { accepted_at, employer_id}` - `accepted_at: Time` - `employer_id: String` ### Example ```ruby require "vitable_connect" vitable_connect = VitableConnect::Client.new( api_key: "My API Key", environment: "environment_1" # defaults to "production" ) response = vitable_connect.employers.submit_census_sync( "empr_abc123def456", employees: [ {date_of_birth: "1990-05-15", email: "jane.doe@acme.com", first_name: "Jane", last_name: "Doe", phone: "4155550100"}, { date_of_birth: "1985-11-20", email: "john.smith@acme.com", first_name: "John", last_name: "Smith", phone: "4155550101" } ] ) puts(response) ``` #### Response ```json { "data": { "accepted_at": "2019-12-27T18:11:19.117Z", "employer_id": "employer_id" } } ``` ## List employees `employers.list_employees(employer_id, **kwargs) -> PageNumberPage` **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: String` Unique employer identifier (empr_*) - `limit: Integer` Items per page (default: 20, max: 100) - `page: Integer` Page number (default: 1) ### Returns - `class Employee` - `id: String` Unique employee identifier with 'empl_' prefix - `created_at: Time` Timestamp when the employee was created - `date_of_birth: Date` Date of birth (YYYY-MM-DD) - `email: String` Email address - `enrollments: Array[{ id, status, answered_at}]` Benefit enrollments for this employee - `id: String` Unique enrollment identifier with 'enrl_' prefix - `status: EnrollmentStatus` * `pending` - Pending * `enrolled` - Enrolled * `waived` - Waived * `inactive` - Inactive - `:pending` - `:enrolled` - `:waived` - `:inactive` - `answered_at: Time` Timestamp when the enrollment decision was made - `first_name: String` Employee's legal first name - `last_name: String` Employee's legal last name - `member_id: String` Unique member identifier with 'mbr_' prefix - `status: String` Employee status (active or terminated) - `updated_at: Time` Timestamp when the employee was last updated - `address: { address_line_1, city, state, 2 more}` Employee's residential address - `address_line_1: String` Primary street address - `city: String` City name - `state: String` Two-letter state code (e.g., CA, NY) - `zipcode: String` ZIP code (5 or 9 digit) - `address_line_2: String` Secondary street address (apt, suite, etc.) - `employee_class: 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: String` Gender identity, if provided - `hire_date: Date` Employee's hire date with the employer - `phone: String` Phone number (10-digit US domestic string) - `reference_id: String` Partner-assigned reference ID for the employee - `suffix: String` Name suffix (e.g., Jr., Sr., III) - `termination_date: Date` Employee's termination date, if terminated ### Example ```ruby require "vitable_connect" vitable_connect = VitableConnect::Client.new( api_key: "My API Key", environment: "environment_1" # defaults to "production" ) page = vitable_connect.employers.list_employees("empr_abc123def456") puts(page) ``` #### 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: String` Unique employer identifier with 'empr_' prefix - `active: bool` Whether the employer is currently active in the system - `address: { address_line_1, city, state, 2 more}` Nested address within EmployerSerializer. - `address_line_1: String` Primary street address - `city: String` City name - `state: String` Two-letter state code (e.g., CA, NY) - `zipcode: String` ZIP code (5 or 9 digit) - `address_line_2: String` Secondary street address (apt, suite, etc.) - `created_at: Time` Timestamp when the employer was created - `ein: String` Employer Identification Number (masked in responses) - `eligibility_policy_id: String` ID of the benefit eligibility policy (epol_*), if assigned - `legal_name: String` Legal business name for compliance and tax purposes - `name: String` Display name of the employer - `organization_id: String` ID of the parent organization (org_*) - `updated_at: Time` Timestamp when the employer was last updated - `email: String` Email address for billing and communications - `phone_number: String` Employer phone number (E.164 format recommended) - `reference_id: String` 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: String` Unique employer identifier with 'empr_' prefix - `active: bool` Whether the employer is currently active in the system - `address: { address_line_1, city, state, 2 more}` Nested address within EmployerSerializer. - `address_line_1: String` Primary street address - `city: String` City name - `state: String` Two-letter state code (e.g., CA, NY) - `zipcode: String` ZIP code (5 or 9 digit) - `address_line_2: String` Secondary street address (apt, suite, etc.) - `created_at: Time` Timestamp when the employer was created - `ein: String` Employer Identification Number (masked in responses) - `eligibility_policy_id: String` ID of the benefit eligibility policy (epol_*), if assigned - `legal_name: String` Legal business name for compliance and tax purposes - `name: String` Display name of the employer - `organization_id: String` ID of the parent organization (org_*) - `updated_at: Time` Timestamp when the employer was last updated - `email: String` Email address for billing and communications - `phone_number: String` Employer phone number (E.164 format recommended) - `reference_id: String` Partner-assigned reference ID for the employer