# Employers ## List employers `client.employers.list(EmployerListParamsquery?, RequestOptionsoptions?): 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 - `query: EmployerListParams` - `limit?: number` Items per page (default: 20, max: 100) - `page?: number` Page number (default: 1) ### Returns - `Employer` Serializer for Employer entity in public API responses. - `id: string` Unique employer identifier with 'empr_' prefix - `active: boolean` Whether the employer is currently active in the system - `address: Address` Nested address within EmployerSerializer. - `address_line_1: string` Primary street address - `city: string` City name - `state: string` Two-letter state code (e.g., CA, NY) - `zipcode: string` ZIP code (5 or 9 digit) - `address_line_2?: string | null` Secondary street address (apt, suite, etc.) - `created_at: string` Timestamp when the employer was created - `ein: string | null` Employer Identification Number (masked in responses) - `eligibility_policy_id: string | null` 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 | null` ID of the parent organization (org_*) - `updated_at: string` Timestamp when the employer was last updated - `email?: string | null` Email address for billing and communications - `phone_number?: string | null` Employer phone number (E.164 format recommended) - `reference_id?: string | null` Partner-assigned reference ID for the employer ### Example ```typescript import VitableConnect from '@vitable-inc/vitable-connect'; const client = new VitableConnect({ apiKey: process.env['VITABLE_CONNECT_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const employer of client.employers.list()) { console.log(employer.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 `client.employers.create(EmployerCreateParamsbody, RequestOptionsoptions?): 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 - `body: EmployerCreateParams` - `address: Address` 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 | null` 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 | null` Employer phone number (10-digit US format, e.g. 5551234567) - `reference_id?: string | null` External reference ID for this employer ### Returns - `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: boolean` Whether the employer is currently active in the system - `address: Address` Nested address within EmployerSerializer. - `address_line_1: string` Primary street address - `city: string` City name - `state: string` Two-letter state code (e.g., CA, NY) - `zipcode: string` ZIP code (5 or 9 digit) - `address_line_2?: string | null` Secondary street address (apt, suite, etc.) - `created_at: string` Timestamp when the employer was created - `ein: string | null` Employer Identification Number (masked in responses) - `eligibility_policy_id: string | null` 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 | null` ID of the parent organization (org_*) - `updated_at: string` Timestamp when the employer was last updated - `email?: string | null` Email address for billing and communications - `phone_number?: string | null` Employer phone number (E.164 format recommended) - `reference_id?: string | null` Partner-assigned reference ID for the employer ### Example ```typescript import VitableConnect from '@vitable-inc/vitable-connect'; const client = new VitableConnect({ apiKey: process.env['VITABLE_CONNECT_API_KEY'], // This is the default and can be omitted }); const employerResponse = await 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', }); console.log(employerResponse.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 `client.employers.retrieve(stringemployerID, RequestOptionsoptions?): EmployerResponse` **get** `/v1/employers/{employer_id}` Retrieves detailed information for a specific employer by ID. The employer must belong to the authenticated organization. ### Parameters - `employerID: string` Unique employer identifier (empr_*) ### Returns - `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: boolean` Whether the employer is currently active in the system - `address: Address` Nested address within EmployerSerializer. - `address_line_1: string` Primary street address - `city: string` City name - `state: string` Two-letter state code (e.g., CA, NY) - `zipcode: string` ZIP code (5 or 9 digit) - `address_line_2?: string | null` Secondary street address (apt, suite, etc.) - `created_at: string` Timestamp when the employer was created - `ein: string | null` Employer Identification Number (masked in responses) - `eligibility_policy_id: string | null` 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 | null` ID of the parent organization (org_*) - `updated_at: string` Timestamp when the employer was last updated - `email?: string | null` Email address for billing and communications - `phone_number?: string | null` Employer phone number (E.164 format recommended) - `reference_id?: string | null` Partner-assigned reference ID for the employer ### Example ```typescript import VitableConnect from '@vitable-inc/vitable-connect'; const client = new VitableConnect({ apiKey: process.env['VITABLE_CONNECT_API_KEY'], // This is the default and can be omitted }); const employerResponse = await client.employers.retrieve('empr_abc123def456'); console.log(employerResponse.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 `client.employers.createBenefitEligibilityPolicy(stringemployerID, EmployerCreateBenefitEligibilityPolicyParamsbody, RequestOptionsoptions?): BenefitEligibilityPolicyResponse` **post** `/v1/employers/{employer_id}/benefit-eligibility-policies` Creates a benefit eligibility policy for the specified employer. ### Parameters - `employerID: string` Unique employer identifier (empr_*) - `body: EmployerCreateBenefitEligibilityPolicyParams` - `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 - `BenefitEligibilityPolicyResponse` Response containing a single benefit eligibility policy resource. - `data: BenefitEligibilityPolicy` - `id: string` - `active: boolean` - `classification: string` - `created_at: string` - `employer_id: string` - `updated_at: string` - `waiting_period: string` ### Example ```typescript import VitableConnect from '@vitable-inc/vitable-connect'; const client = new VitableConnect({ apiKey: process.env['VITABLE_CONNECT_API_KEY'], // This is the default and can be omitted }); const benefitEligibilityPolicyResponse = await client.employers.createBenefitEligibilityPolicy( 'empr_abc123def456', { classification: 'classification', waiting_period: 'waiting_period' }, ); console.log(benefitEligibilityPolicyResponse.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 `client.employers.submitCensusSync(stringemployerID, EmployerSubmitCensusSyncParamsbody, RequestOptionsoptions?): 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 - `employerID: string` Unique employer identifier (empr_*) - `body: EmployerSubmitCensusSyncParams` - `employees: Array` - `date_of_birth: string` - `email: string` - `first_name: string` - `last_name: string` - `phone: string` - `address?: Address | null` - `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 | null` - `compensation_type?: "Salary" | "Hourly" | null` * `Salary` - Salary * `Hourly` - Hourly - `"Salary"` - `"Hourly"` - `employee_class?: EmployeeClass | null` * `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 | null` - `start_date?: string | null` ### Returns - `EmployerSubmitCensusSyncResponse` Response containing a single census sync detail resource. - `data: Data` - `accepted_at: string` - `employer_id: string` ### Example ```typescript import VitableConnect from '@vitable-inc/vitable-connect'; const client = new VitableConnect({ apiKey: process.env['VITABLE_CONNECT_API_KEY'], // This is the default and can be omitted }); const response = await client.employers.submitCensusSync('empr_abc123def456', { employees: [ { reference_id: 'EMP-001', first_name: 'Jane', last_name: 'Doe', date_of_birth: '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: '2024-01-15', employee_class: 'Full Time', compensation_type: 'Salary', }, { first_name: 'John', last_name: 'Smith', date_of_birth: '1985-11-20', email: 'john.smith@acme.com', phone: '4155550101', start_date: '2024-03-01', employee_class: 'Part Time', compensation_type: 'Hourly', }, ], }); console.log(response.data); ``` #### Response ```json { "data": { "accepted_at": "2019-12-27T18:11:19.117Z", "employer_id": "employer_id" } } ``` ## List employees `client.employers.listEmployees(stringemployerID, EmployerListEmployeesParamsquery?, RequestOptionsoptions?): 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 - `employerID: string` Unique employer identifier (empr_*) - `query: EmployerListEmployeesParams` - `limit?: number` Items per page (default: 20, max: 100) - `page?: number` Page number (default: 1) ### Returns - `Employee` - `id: string` Unique employee identifier with 'empl_' prefix - `created_at: string` Timestamp when the employee was created - `date_of_birth: string` Date of birth (YYYY-MM-DD) - `email: string` Email address - `enrollments: Array` 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?: string | null` 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: string` Timestamp when the employee was last updated - `address?: Address | null` 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 | null` Secondary street address (apt, suite, etc.) - `employee_class?: EmployeeClass | null` * `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 | null` Gender identity, if provided - `hire_date?: string | null` Employee's hire date with the employer - `phone?: string | null` Phone number (10-digit US domestic string) - `reference_id?: string | null` Partner-assigned reference ID for the employee - `suffix?: string | null` Name suffix (e.g., Jr., Sr., III) - `termination_date?: string | null` Employee's termination date, if terminated ### Example ```typescript import VitableConnect from '@vitable-inc/vitable-connect'; const client = new VitableConnect({ apiKey: process.env['VITABLE_CONNECT_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const employee of client.employers.listEmployees('empr_abc123def456')) { console.log(employee.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 - `Employer` Serializer for Employer entity in public API responses. - `id: string` Unique employer identifier with 'empr_' prefix - `active: boolean` Whether the employer is currently active in the system - `address: Address` Nested address within EmployerSerializer. - `address_line_1: string` Primary street address - `city: string` City name - `state: string` Two-letter state code (e.g., CA, NY) - `zipcode: string` ZIP code (5 or 9 digit) - `address_line_2?: string | null` Secondary street address (apt, suite, etc.) - `created_at: string` Timestamp when the employer was created - `ein: string | null` Employer Identification Number (masked in responses) - `eligibility_policy_id: string | null` 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 | null` ID of the parent organization (org_*) - `updated_at: string` Timestamp when the employer was last updated - `email?: string | null` Email address for billing and communications - `phone_number?: string | null` Employer phone number (E.164 format recommended) - `reference_id?: string | null` Partner-assigned reference ID for the employer ### Employer Response - `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: boolean` Whether the employer is currently active in the system - `address: Address` Nested address within EmployerSerializer. - `address_line_1: string` Primary street address - `city: string` City name - `state: string` Two-letter state code (e.g., CA, NY) - `zipcode: string` ZIP code (5 or 9 digit) - `address_line_2?: string | null` Secondary street address (apt, suite, etc.) - `created_at: string` Timestamp when the employer was created - `ein: string | null` Employer Identification Number (masked in responses) - `eligibility_policy_id: string | null` 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 | null` ID of the parent organization (org_*) - `updated_at: string` Timestamp when the employer was last updated - `email?: string | null` Email address for billing and communications - `phone_number?: string | null` Employer phone number (E.164 format recommended) - `reference_id?: string | null` Partner-assigned reference ID for the employer