### Node.js Webhook Handler Setup Source: https://docs.kota.io/api/events-and-webhooks/working-with-webhooks Example of setting up a basic webhook handler in Node.js using Express to receive POST requests. It includes middleware for parsing JSON payloads and a placeholder for processing logic. The endpoint must respond with a 2xx status code for successful processing to avoid retries. ```javascript const express = require('express'); const app = express(); // Middleware to parse JSON payloads app.use(express.json()); // Endpoint to receive webhook events app.post('/webhooks/receive', (req, res) => { const payload = req.body; // TODO: Add your processing logic here // Validate the payload, process the event data, etc. // Respond with a 2xx status code for successful processing // Non-2xx status codes will prevent retry res.status(200).send(); }); // Start the server app.listen(3000, () => { console.log('Webhook handler is running on port 3000'); }); ``` -------------------------------- ### Handle Employee Health Setup Loaded Event Source: https://docs.kota.io/sdk/embed-sdk-reference Sets up a listener for the 'healthSetupLoaded' event for the employee embedded UI. The handler function is called when the health insurance setup flow loads. ```javascript const employeeEmbed = Kota.Health.employee(); employeeEmbed.init(employeeAccessToken); employeeEmbed.on('healthSetupLoaded', function(event) { // Handle employee healthSetupLoaded event console.log('Employee health setup loaded.'); }) ``` -------------------------------- ### Idempotent API Request Example Source: https://docs.kota.io/get-started/plan-your-integration/server-side-integration Illustrates making an idempotent API request to Kota by including an 'Idempotency-Key' header. This ensures safe retries for POST requests. ```bash curl https://test.api.kota.io/ENDPOINT \ -H "Authorization: Bearer YOUR_API_SECRET_KEY" \ -H "Idempotency-Key: 4fe9c195-56db-4cc2-85d3-5512cf558d60" \ ... rest of request here ``` -------------------------------- ### Handle Employee Health Setup Loaded Event Source: https://docs.kota.io/sdk Sets up a listener for the 'healthSetupLoaded' event for the employee embedded UI. The handler function is called when the health insurance setup flow loads. ```javascript const employeeEmbed = Kota.Health.employee(); employeeEmbed.init(employeeAccessToken); employeeEmbed.on('healthSetupLoaded', function(event) { // Handle employee healthSetupLoaded event console.log('Employee health setup loaded.'); }) ``` -------------------------------- ### Handle Employer Health Setup Loaded Event Source: https://docs.kota.io/sdk Sets up a listener for the 'healthSetupLoaded' event for the employer embedded UI. The handler function is called when the health insurance setup flow loads. ```javascript employerEmbed.on('healthSetupLoaded', function(event) { // Handle employer healthSetupLoaded event console.log('Employer health setup loaded.'); }) ``` -------------------------------- ### Handle Employer Health Setup Loaded Event Source: https://docs.kota.io/sdk/embed-sdk-reference Sets up a listener for the 'healthSetupLoaded' event for the employer embedded UI. The handler function is called when the health insurance setup flow loads. ```javascript employerEmbed.on('healthSetupLoaded', function(event) { // Handle employer healthSetupLoaded event console.log('Employer health setup loaded.'); }) ``` -------------------------------- ### Frontend Integration Steps Source: https://docs.kota.io/get-started/plan-your-integration Steps required for integrating Kota on the frontend. This includes adding the SDK, obtaining session tokens, initializing user interfaces, and optional theming. ```APIDOC Frontend Implementation: 1. Include Kota’s Embed SDK in your project - Add the SDK script or package to your frontend application. 2. Get your Embed SDK session token - Obtain a token, typically from your backend, to authenticate the SDK session. 3. Initialize the Employer and Employee UIs - Render the necessary Kota components for user interaction. 4. (Optional) Theme your integration - Customize the appearance of Kota components to match your brand. ``` -------------------------------- ### Server-side Integration Steps Source: https://docs.kota.io/get-started/plan-your-integration Steps required for integrating Kota on the server-side. This involves authentication, making API calls, configuring webhooks, and communicating actions with employers and employees. ```APIDOC Server-side Implementation: 1. Authenticate with Kota - Establish a secure connection to the Kota API. 2. Integrate necessary API calls to your platform - Implement calls for core functionalities like user management, data retrieval, etc. 3. Configure webhooks to handle Events - Set up endpoints to receive real-time notifications from Kota. 4. Communicate required actions with Employers and their Employees - Design workflows to inform users about necessary steps or updates. ``` -------------------------------- ### Frontend Integration Steps Source: https://docs.kota.io/get-started/plan-your-integration/build-guide Steps required for integrating Kota on the frontend. This includes adding the SDK, obtaining session tokens, initializing user interfaces, and optional theming. ```APIDOC Frontend Implementation: 1. Include Kota’s Embed SDK in your project - Add the SDK script or package to your frontend application. 2. Get your Embed SDK session token - Obtain a token, typically from your backend, to authenticate the SDK session. 3. Initialize the Employer and Employee UIs - Render the necessary Kota components for user interaction. 4. (Optional) Theme your integration - Customize the appearance of Kota components to match your brand. ``` -------------------------------- ### Server-side Integration Steps Source: https://docs.kota.io/get-started/plan-your-integration/build-guide Steps required for integrating Kota on the server-side. This involves authentication, making API calls, configuring webhooks, and communicating actions with employers and employees. ```APIDOC Server-side Implementation: 1. Authenticate with Kota - Establish a secure connection to the Kota API. 2. Integrate necessary API calls to your platform - Implement calls for core functionalities like user management, data retrieval, etc. 3. Configure webhooks to handle Events - Set up endpoints to receive real-time notifications from Kota. 4. Communicate required actions with Employers and their Employees - Design workflows to inform users about necessary steps or updates. ``` -------------------------------- ### Curl Request Example for Offboarding Employer Source: https://docs.kota.io/api/employers/offboard-employer Example of how to call the offboard employer API endpoint using curl, including the HTTP method, URL, and authorization header. ```shell curl -X POST https://test.api.kota.io/employers/er_3b1333d87d9d4fd6ad83ba7f6b0e951a/offboard \ -H "Authorization: Bearer " ``` -------------------------------- ### Employee Created Webhook Payload Example Source: https://docs.kota.io/api/events-and-webhooks/working-with-webhooks This JSON structure represents an example `employee.created` event payload received via webhook. It includes event metadata like ID, type, platform ID, and a detailed `data` object mirroring the employee's information. This serves as a reference for parsing incoming webhook data. ```json { "id": "evt_d3491808363d4dc79d15f5ced0035cc4", "type": "employee.created", "platform_id": "pt_f57c25e3d975453cabeb9be650f2254c", "data": { "id": "ee_af6601bea10d4bcba95e4a2f40f2ae14", "platform_id": "pt_f57c25e3d975453cabeb9be650f2254c", "employer_id": "er_r879d5e3d975453cabeb9be650f22345", "status": "pending", "external_customer_id": "cust_001", "first_name": "John", "last_name": "Doe", "date_of_birth": "1985-01-01", "sex_at_birth": "male", "home_address": { "line1": "123 Main St", "city": "Anytown", "state": "NY", "postal_code": "12345", "country_code": "US" }, "nationality": "US", "start_on": "2023-01-01", "phone_number": "+1234567890", "email": "john.doe@example.com", "offboard_on": "2024-01-01", "object": "employee" }, "created_at": "2023-01-01T00:00:00Z", "api_version": "1.0", "object": "event" } ``` -------------------------------- ### Contribution Reports API Integration Source: https://docs.kota.io/get-started/plan-your-integration Guidance for integrating with Kota's Contribution Reports API to programmatically handle complex contributions and reporting, especially for large organizations with global payroll considerations. ```APIDOC Contribution Reports API: - Purpose: Programmatically handle complex contributions across tens of countries, enable scalable payroll systems, improve reporting, and simplify end-of-year benefit reconciliations. - Target Users: Large platforms or employers interested in consuming benefit contribution reports. - Estimated implementation time: 1-2 weeks, depending on payroll system complexity and handling of adjustments/pro-rated amounts. - Related Documentation: [Contribution Reports documentation](https://docs.kota.io/get-started/plan-your-integration/contribution-reporting), [API reference](https://docs.kota.io/api/contribution-reports/retrieve-contribution-report) ``` -------------------------------- ### Authenticate to Kota API Source: https://docs.kota.io/get-started/plan-your-integration/server-side-integration Demonstrates how to authenticate API requests to Kota using an API key. It shows the necessary header for authorization. ```bash curl https://test.api.kota.io/employees/$employee_id \ -H "Authorization: Bearer " ``` -------------------------------- ### Employee Contribution Breakdown Report Example Source: https://docs.kota.io/get-started/plan-your-integration/contribution-reporting An example JSON object representing a breakdown of employee contributions for a specific period. It details employer contributions for health insurance, including pro-rated amounts for partial coverage periods and notes on adjustments. ```json { "object": "contribution_report_employee_breakdown", "employee_id": "ee_c245fde199004eee845b2c26a5732ce2", "contribution_report_id": "ctr_7d37c383d2bf49c4beea3ebdbe4de787", "employer_id": "er_01227f212421474cbe687cde68568d37", "external_customer_id": null, "period": { "from_date": "2025-05-01", "to_date": "2025-05-31" }, "currency": "eur", "status": "finalized", "finalized_at": "2025-06-01T00:00:10.311966Z", "created_at": "2025-05-10T20:53:14.196315Z", "last_updated_at": "2025-06-01T00:00:10.323195Z", "health_insurance": { "employer_contributions": [ { "id": "ct_0447692a1bf74400965b1c1b00f33610", "category": "gross_premium", "member_type": "policyholder", "adjustment": false, "adjustment_for": null, "amount": 83.33, "type": "recurring", "note": "Pro-rated for employee joining April 20th", "cover_period": { "from_date": "2025-04-20", "to_date": "2025-04-30" }, "employee_policy_id": "eehp_fa505f9505d3464cbf7cabd5d763722a", "reporting_month": "2025-04-01" }, { "id": "ct_8db2eb4b9d9446a0b9fef29a7f3c36c9", "category": "gross_premium", "member_type": "policyholder", "adjustment": false, "adjustment_for": null, "amount": 250.00, "type": "recurring", "note": "", "cover_period": { "from_date": "2025-05-01", "to_date": "2025-05-31" }, "employee_policy_id": "eehp_fa505f9505d3464cbf7cabd5d763722a", "reporting_month": "2025-05-01" } ] } } ``` -------------------------------- ### Contribution Reports API Integration Source: https://docs.kota.io/get-started/plan-your-integration/build-guide Guidance for integrating with Kota's Contribution Reports API to programmatically handle complex contributions and reporting, especially for large organizations with global payroll considerations. ```APIDOC Contribution Reports API: - Purpose: Programmatically handle complex contributions across tens of countries, enable scalable payroll systems, improve reporting, and simplify end-of-year benefit reconciliations. - Target Users: Large platforms or employers interested in consuming benefit contribution reports. - Estimated implementation time: 1-2 weeks, depending on payroll system complexity and handling of adjustments/pro-rated amounts. - Related Documentation: [Contribution Reports documentation](https://docs.kota.io/get-started/plan-your-integration/contribution-reporting), [API reference](https://docs.kota.io/api/contribution-reports/retrieve-contribution-report) ``` -------------------------------- ### Initialize Embedded SDK with Custom Theme Source: https://docs.kota.io/embedded-sdk/theming Example of how to initialize the Kota Embedded SDK for employers or employees, passing a custom theme configuration object to match application branding. ```javascript ``` -------------------------------- ### Curl command to list events Source: https://docs.kota.io/api/events-and-webhooks/list-events Example command to list events using curl, including the necessary Authorization header. ```bash curl https://test.api.kota.io/events \ -H "Authorization: Bearer " ``` -------------------------------- ### Example Request for Retrieving Employer Policy Source: https://docs.kota.io/api/health-insurance/retrieve-employer-health-insurance-policy Example using curl to make a GET request to retrieve an employer's health insurance policy, including authorization header. ```bash curl https://test.api.kota.io/employers/er_3b1333d87d9d4fd6ad83ba7f6b0e951a/health_insurance/policies/erhp_3b1333d87d9d4fd6ad83ba7f6b0e951a \ -H "Authorization: Bearer " ``` -------------------------------- ### Retrieve Contribution Report (Node.js) Source: https://docs.kota.io/get-started/plan-your-integration/contribution-reporting Example of how to retrieve a finalized contribution report using the Kota API client with Node.js and Axios. It demonstrates setting up the API client with base URL and authentication headers, and making a GET request to fetch report data. ```javascript const axios = require('axios'); // Configure API client const kotaClient = axios.create({ baseURL: 'https://api.kota.io', headers: { 'Authorization': `Bearer ${process.env.KOTA_API_KEY}`, 'Content-Type': 'application/json' } }); // Retrieve a contribution report async function getContributionReport(reportId) { const response = await kotaClient.get(`/contribution_reports/${reportId}`); return response.data; } ``` -------------------------------- ### Offboard Employee Response Example (JSON) Source: https://docs.kota.io/api/employees/offboard-employee Example JSON response received upon successfully scheduling an employee for offboarding. ```json { "first_name": "string", "last_name": "string", "date_of_birth": "2024-12-01", "sex_at_birth": "male", "national_tax_id": "string", "phone_number": "string", "email": "string", "platform_id": "pt_3b1333d87d9d4fd6ad83ba7f6b0e951a", "id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a", "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a", "status": "pending", "external_customer_id": "string", "home_address": { "line1": "string", "city": "string", "postal_code": "string", "country_code": "af", "line2": "string", "line3": "string", "state": "string" }, "nationality": "af", "start_on": "2024-12-01", "earliest_benefits_start_date": "2024-12-01", "offboard_on": "2024-01-15T09:30:00Z", "bank_account": { "account_number_last4": "string" }, "object": "string" } ``` -------------------------------- ### Offboard Employee Request Example (cURL) Source: https://docs.kota.io/api/employees/offboard-employee Example cURL command to offboard an employee, including the endpoint, headers, and JSON payload. ```curl curl -X POST https://test.api.kota.io/employees/ee_3b1333d87d9d4fd6ad83ba7f6b0e951a/offboard \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "offboard_on": "2024-01-15T09:30:00Z", "offboard_reason": "string" }' ``` -------------------------------- ### Initialize and Listen to Embedded UI Events Source: https://docs.kota.io/sdk/embed-sdk-reference Demonstrates how to initialize an embedded UI object and set up a generic event listener for custom events. This pattern is used for both employer and employee contexts. ```javascript const employerEmbed = Kota.Health.employer(); employerEmbed.init(employeeAccessToken); function handler(event) { // Handle any metrics or actions here } employerEmbed.on('eventName', handler); ``` -------------------------------- ### Initialize and Listen to Embedded UI Events Source: https://docs.kota.io/sdk Demonstrates how to initialize an embedded UI object and set up a generic event listener for custom events. This pattern is used for both employer and employee contexts. ```javascript const employerEmbed = Kota.Health.employer(); employerEmbed.init(employeeAccessToken); function handler(event) { // Handle any metrics or actions here } employerEmbed.on('eventName', handler); ``` -------------------------------- ### Include Kota.js for Testing Source: https://docs.kota.io/sdk/embed-sdk-reference Include this script tag to load the Kota.js SDK for testing purposes. Ensure your production environment uses the production SDK. ```html ``` -------------------------------- ### Retrieve Employee Breakdowns (Node.js) Source: https://docs.kota.io/get-started/plan-your-integration/contribution-reporting Fetches all employee breakdowns for a given contribution report ID. This function makes a GET request to the Kota API and returns the employee data. ```javascript async function getEmployeeBreakdowns(reportId) { const response = await kotaClient.get(`/contribution_reports/${reportId}/employee_breakdowns`); return response.data.data; } ``` -------------------------------- ### Include Kota.js for Testing Source: https://docs.kota.io/sdk Include this script tag to load the Kota.js SDK for testing purposes. Ensure your production environment uses the production SDK. ```html ```