Kota Embed

https://docs.kota.io
Admin
Kota Embed enables platforms to seamlessly integrate Kota's compliant, cutting-edge health...
Tokens:81,611
Snippets:142
Trust Score:7.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### 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 <token>"
```

--------------------------------

### 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 <token>"
```

--------------------------------

### 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"
}
```

--------------------------------

### 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"
}
```

--------------------------------

### 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;
}
```

--------------------------------

### 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 <YOUR_API_SECRET_KEY>"
```

--------------------------------

### 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
<script>
      const themeConfig = {
        primaryColor: '#00ffa6',
        backgroundColor: '#04110c',
        radius: '0rem',
        ringColor: '#00ffa6'
      };

      const employerEmbed = Kota.Health.employer();

      employerEmbed.init('<your_employer_access_token_here>', 
        {theme: themeConfig} //pass the theme 
      );
</script>
```

--------------------------------

### 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 <token>"
```

--------------------------------

### 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 <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "offboard_on": "2024-01-15T09:30:00Z",
    "offboard_reason": "string"
}'
```

--------------------------------

### Example Request to Retrieve Employee Offer

Source: https://docs.kota.io/api/health-insurance/retrieve-employee-health-insurance-offer

Demonstrates how to make a curl request to retrieve an employee health insurance offer, including the endpoint and authorization header.

```curl
curl https://test.api.kota.io/employees/ee_3b1333d87d9d4fd6ad83ba7f6b0e951a/health_insurance/offers/eeho_3b1333d87d9d4fd6ad83ba7f6b0e951a \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Create Embedded SDK Session Response

Source: https://docs.kota.io/api/embed-sessions/create-embed-session

Example of a successful 200 OK response from the create embed session endpoint. It returns a JSON object containing the authentication token and its expiry time.

```json
{
  "token": "string",
  "expiry": "2024-01-15T09:30:00Z"
}
```

--------------------------------

### Webhook Event Payload Structure

Source: https://docs.kota.io/api/events-and-webhooks/working-with-webhooks

This is an example of a typical webhook event payload. It includes essential fields like event ID, API version, event type, platform ID, object type, creation timestamp, and the data payload. The `api_version` field ensures compatibility with specific API versions.

```json
{
  "id": "evt_cd7dc78d47374cf6af676d95256c0153",
  "api_version": "1.0",
  "type": "employee.created",
  "platform_id": "pt_fe914e5b13564f26ad715821e8e3dfaa",
  "object": "event",
  "created_at": "2023-01-01T00:00:00Z",
  "data": { ... }
}
```

--------------------------------

### Kota API Authentication and Request Format

Source: https://docs.kota.io/api

Details how to authenticate requests to the Kota API using API keys and Bearer Auth. Includes requirements for HTTPS and key security, along with an example authenticated request.

```APIDOC
The Kota API uses API keys for authentication.
Test mode secret keys have the prefix `pk_test_` and live mode secret keys have the prefix `pk_live_`.

Authentication is performed via Bearer Auth. Provide your API key as the bearer token value in the Authorization header.
Use `-H "Authorization: Bearer YOUR_API_SECRET_KEY"` in your request.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
API keys are tied to an individual platform and are restricted to that platform’s type, such as `employer_of_record` and `payroll_provider`.
```

```bash
curl https://api.kota.io/ENDPOINT \
  -H "Authorization: Bearer YOUR_API_SECRET_KEY"
```

--------------------------------

### Update Employer using cURL

Source: https://docs.kota.io/api/employers/update-employer

Example command to update an employer using cURL, demonstrating how to set the authorization token, content type, and provide an empty JSON payload.

```bash
curl -X PUT https://test.api.kota.io/employers/er_3b1333d87d9d4fd6ad83ba7f6b0e951a \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

--------------------------------

### Add Employee API

Source: https://docs.kota.io/get-started/plan-your-integration/server-side-integration

This API endpoint allows you to add employees associated with a specific employer. It requires the employer ID and employee personal details. Employees are initially in a 'pending' state for regulatory checks.

```APIDOC
POST /employees
  Description: Adds a new employee to a specific employer.
  Headers:
    Authorization: Bearer <YOUR_API_SECRET_KEY>
    Idempotency-Key: string (Unique key for idempotency)
    Content-Type: application/json
  Request Body:
    type: object
    properties:
      employer_id: { type: string, description: The ID of the employer this employee belongs to. }
      first_name: { type: string, description: The employee's first name. }
      last_name: { type: string, description: The employee's last name. }
      date_of_birth: { type: string, format: date, description: The employee's date of birth (YYYY-MM-DD). }
      sex_at_birth: { type: string, enum: ["male", "female", "other"], description: The employee's sex at birth. }
      home_address: { type: object, properties: { line1: { type: string }, city: { type: string }, postal_code: { type: string }, country_code: { type: string } } }
      national_tax_id: { type: string, description: The employee's national tax identification number. }
      start_on: { type: string, format: date, description: The date the employee's coverage starts (YYYY-MM-DD). }
      email: { type: string, format: email, description: The employee's email address. }
  Responses:
    201 Created: Returns the created employee object with its unique ID.
    400 Bad Request: Invalid input data or missing employer_id.
    401 Unauthorized: Missing or invalid API key.
    404 Not Found: Employer ID not found.
```

```bash
curl -X POST https://test.api.kota.io/employees \
  -H "Authorization: Bearer <YOUR_API_SECRET_KEY>" \
  -H "Idempotency-Key: 4fe9c195-56db-4cc2-85d3-5512cf558d60" \
  -H "Content-Type: application/json" \
  -d '{
    "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a",
    "first_name": "Jane",
    "last_name": "Liu",
    "date_of_birth": "1995-12-01",
    "sex_at_birth": "female",
    "home_address": {
      "line1": "128 Lower Baggot Street",
      "city": "Dublin",
      "postal_code": "D02 A430",
      "country_code": "ie"
    },
    "national_tax_id": "1234567T",
    "start_on": "2024-12-01",
    "email": "jane.liu@kota.io"
  }'
```

--------------------------------

### Add Employer API

Source: https://docs.kota.io/get-started/plan-your-integration/server-side-integration

This API endpoint allows you to add new employers to the Kota platform. It requires company details and contact information. Successful creation returns an employer ID, which should be stored for future reference.

```APIDOC
POST /employers
  Description: Adds a new employer to the Kota platform.
  Headers:
    Authorization: Bearer <YOUR_API_SECRET_KEY>
    Idempotency-Key: string (Unique key for idempotency)
    Content-Type: application/json
  Request Body:
    type: object
    properties:
      legal_name: { type: string, description: The legal name of the employer. }
      legal_address: { type: object, properties: { line1: { type: string }, city: { type: string }, postal_code: { type: string }, country_code: { type: string } } }
      contact: { type: object, properties: { name: { type: string }, email: { type: string } } }
  Responses:
    201 Created: Returns the created employer object with its unique ID.
    400 Bad Request: Invalid input data.
    401 Unauthorized: Missing or invalid API key.
    409 Conflict: Employer with same identifier already exists.
```

```bash
curl -X POST https://test.api.kota.io/employers \
  -H "Authorization: Bearer <YOUR_API_SECRET_KEY>" \
  -H "Idempotency-Key: 4fe9c195-56db-4cc2-85d3-5512cf558d60" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "ABC Co Limited",
    "legal_address": {
      "line1": "128 Lower Baggot Street",
      "city": "Dublin",
      "postal_code": "D02 A430",
      "country_code": "ie"
    },
    "contact": {
      "name": "Jane Liu",
      "email": "jane.liu@kota.io"
    }
  }'
```

--------------------------------

### Idempotent API Request Example

Source: https://docs.kota.io/api

Demonstrates how to make idempotent API requests by including the `Idempotency-Key` header. This allows for safe retries of POST requests. The key should be a unique identifier, like a V4 UUID. The API checks parameters on retry; mismatches result in a 409 Conflict error. Idempotency keys expire after 1 hour.

```APIDOC
curl https://api.kota.io/ENDPOINT \
  -H "Authorization: Bearer YOUR_API_SECRET_KEY" \
  -H "Idempotency-Key: KG5LxwFBepaKHyUD"
```

--------------------------------

### Example JSON Response

Source: https://docs.kota.io/api/health-insurance/list-employer-health-insurance-policies

This snippet shows a sample JSON response when successfully retrieving employer health insurance policies from the Kota API. It includes pagination details and the structure of a single policy item.

```json
{
  "items": [
    {
      "id": "erhp_3b1333d87d9d4fd6ad83ba7f6b0e951a",
      "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a",
      "start_date": "2024-12-01",
      "end_date": "2024-12-01",
      "status": "scheduled",
      "enrolment_type": "opt_out",
      "renewal": {
        "status": "upcoming",
        "renewal_date": "2024-12-01",
        "window_start_date": "2024-12-01",
        "window_end_date": "2024-12-01",
        "decision_confirmed": true,
        "renewed_health_insurance_id": "erhp_3b1333d87d9d4fd6ad83ba7f6b0e951a"
      },
      "employer_cancellation_period_length": 1,
      "coverage_levels": [
        {
          "plan_id": "pl_3b1333d87d9d4fd6ad83ba7f6b0e951a",
          "plan_name": "string",
          "plan_currency": "eur",
          "provider_name": "string",
          "provider_logo_url": "string",
          "documents": [
            {
              "title": "string",
              "link": "string"
            }
          ],
          "provider_employer_platform_url": "string",
          "provider_support_phone": "string"
        }
      ],
      "object": "string",
      "cancellation_date": "2024-12-01",
      "group_policy_number": "string"
    }
  ],
  "page": 1,
  "page_size": 1,
  "total_count": 1,
  "has_next_page": true,
  "has_previous_page": true
}
```

--------------------------------

### Example cURL Request

Source: https://docs.kota.io/api/health-insurance/list-employer-health-insurance-policies

This snippet demonstrates how to make a cURL request to the Kota API to list employer health insurance policies. It includes the endpoint, authorization header, and a sample employer ID.

```curl
curl https://test.api.kota.io/employers/er_3b1333d87d9d4fd6ad83ba7f6b0e951a/health_insurance/policies \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Offboard Employee API

Source: https://docs.kota.io/get-started/plan-your-integration/server-side-integration

API endpoint to offboard an employee. This action is critical as it begins the cancellation of all insurance policies for the employee. It includes parameters for specifying the offboarding date and reason. A related API exists to cancel an offboarding if needed.

```APIDOC
POST /employees/$employeeId/offboard

Description:
  Initiates the offboarding process for a specific employee, leading to the termination of their insurance policies.

Parameters:
  - employeeId (string, required): The unique identifier for the employee to be offboarded.
  - offboard_on (string, optional): The date and time when the offboarding should take effect, in ISO 8601 format.
  - offboard_reason (string, optional): A description of the reason for offboarding.

Request Example:
  curl -X POST https://test.api.kota.io/employees/ee_3b1333d87d9d4fd6ad83ba7f6b0e951a/offboard \
    -H "Authorization: Bearer <apiKey>" \
    -H "Content-Type: application/json" \
    -d '{
      "offboard_on": "2024-01-15T09:30:00Z",
      "offboard_reason": "offboard_reason"
    }'

Related API:
  - Cancel Offboarding Employee: Allows cancellation of an ongoing offboarding process.
```

--------------------------------

### Offboard Employer API

Source: https://docs.kota.io/get-started/plan-your-integration/server-side-integration

API endpoint to offboard an employer. This action removes the employer's access to Embedded UIs and initiates a specific offboarding process for their employees, ensuring their insurance policies are not cancelled due to the employer's departure.

```APIDOC
POST /employers/$employerId/offboard

Description:
  Initiates the offboarding process for a specific employer.

Parameters:
  - employerId (string, required): The unique identifier for the employer to be offboarded.

Request Example:
  curl -X POST https://test.api.kota.io/employers/er_3b1333d87d9d4fd6ad83ba7f6b0e951a/offboard \
    -H "Authorization: Bearer <YOUR_API_SECRET_KEY>"
```

--------------------------------

### Contribution Reports API

Source: https://docs.kota.io/get-started/plan-your-integration/server-side-integration

Provides endpoints for managing and retrieving contribution reports, essential for platforms like payroll or EOR. This includes finalizing reports, retrieving specific reports, and accessing detailed employee contribution breakdowns. Reports can be finalized manually or automatically at month-end.

```APIDOC
Contribution Reports API

Overview:
  APIs for integrating contribution reports into your platform, providing per-employer and per-period contribution data, split between employer and employee contributions.

Key Endpoints:

1. Finalize Contribution Report:
   - Method: POST
   - Endpoint: /contribution-reports/finalize-contribution-report
   - Description: Finalizes the current contribution report. Can also be set to auto-finalize at the end of each month.

2. Retrieve a Contribution Report:
   - Method: GET
   - Endpoint: /contribution-reports/{report_id}
   - Description: Retrieves details of a specific contribution report using its ID.
   - Parameters:
     - report_id (string, required): The unique identifier for the contribution report.

3. List Employee Breakdowns for Contribution Report:
   - Method: GET
   - Endpoint: /contribution-reports/{report_id}/employee-breakdowns
   - Description: Retrieves a list of employee contribution breakdowns for a given report.
   - Parameters:
     - report_id (string, required): The unique identifier for the contribution report.

4. Retrieve Employee Breakdown for Contribution Report:
   - Method: GET
   - Endpoint: /contribution-reports/employee-breakdowns/{employee_breakdown_id}
   - Description: Retrieves the contribution breakdown for a specific employee within a report.
   - Parameters:
     - employee_breakdown_id (string, required): The unique identifier for the employee breakdown.

Further Information:
  Detailed API documentation available at: https://docs.kota.io/api/contribution-reports/retrieve-contribution-report
```

--------------------------------

### Kota API Error Responses

Source: https://docs.kota.io/api/errors

Details common API error responses, their causes, and example JSON structures. Errors conform to RFC 9457, providing type, title, status, error_code, and often specific details or a trace_id.

```APIDOC
API Error Handling Overview:
Errors conform to the [Problem Details for HTTP APIs specification](https://www.rfc-editor.org/rfc/rfc9457.html).
Each error object includes:
- type: A URI identifying the error type.
- title: A short, human-readable summary of the error.
- status: The HTTP status code.
- error_code: A specific application-defined error code.
- trace_id: A unique identifier for tracing the request.

Common API Errors:

1. Unauthorized (401)
   - Cause: Missing or invalid Authorization header.
   - Resolution: Ensure an appropriate token is sent in the headers.
   - Example:
     ```json
     {
       "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
       "title": "Unauthorized",
       "status": 401,
       "error_code": "unauthorized",
       "trace_id": "3643f86ed46106566fc9ffac4f811800"
     }
     ```

2. Forbidden (403)
   - Cause: Provided token lacks permission for the operation.
   - Resolution: Verify the token's permissions.
   - Example:
     ```json
     {
       "type": "https://tools.ietf.org/html/rfc9110#section-15.5.4",
       "title": "Forbidden",
       "status": 403,
       "error_code": "forbidden",
       "trace_id": "d9f784ea4dad04d019ae38d86c237fb5"
     }
     ```

3. Invalid Request (400)
   - Cause: Issues with request body or headers, including validation errors or malformed JSON.

   a. Validation Errors:
      - Cause: One or more fields in the request body or headers are invalid.
      - Resolution: Correct the specified fields.
      - Example:
        ```json
        {
          "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
          "title": "Invalid request",
          "status": 400,
          "error_code": "invalid_request",
          "errors": {
            "legal_name": [
              "The legal_name field is required"
            ]
          },
          "trace_id": "ae3c4bd470e1d843e25d93201a501073"
        }
        ```

   b. Malformed JSON:
      - Cause: Request body contains malformed JSON or cannot be deserialized (e.g., incorrect type).
      - Resolution: Ensure the JSON is correctly formatted.
      - Example:
        ```json
        {
          "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
          "title": "Invalid request",
          "status": 400,
          "error_code": "invalid_request",
          "detail": "Invalid parameter $.legal_name at line 1",
          "trace_id": "91b9d777cf66a0c20a25ae59d24d4ce4"
        }
        ```

4. Invalid State (400)
   - Cause: Requested operation is invalid given the resource's current state.
   - Resolution: Ensure the operation is valid for the resource's current status.
   - Example:
     ```json
     {
       "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
       "title": "Invalid state",
       "status": 400,
       "error_code": "invalid_state",
       "detail": "The employer offboarding cannot be cancelled, as it was not requested",
       "trace_id": "ce817fda982145459fda00334f2b8e90"
     }
     ```

Other potential errors include:
- Not Found (404)
- Idempotency Error
- Too Many Requests (429)
- Third Party Error
- Internal Error (500)
```

--------------------------------

### 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
<script src="https://test.js.kota.io/v1"></script>
```

--------------------------------

### 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
<script src="https://test.js.kota.io/v1"></script>
```

--------------------------------

### Initialize Kota Health Employee UI

Source: https://docs.kota.io/sdk/embed-sdk-reference

Initializes the Kota Health Employee embedded UI. Requires an employee access token and allows for optional configuration of the container and theme.

```javascript
const employeeEmbed = Kota.Health.employee();

const themeConfig = {
  primaryColor: '#0875E1',
  backgroundColor: '#fff',
  radius: '12px',
  ringColor: '#0875E1'
};

employeeEmbed.init(
  employeeAccessToken,
  { container: 'employee', theme: themeConfig }
);
```

--------------------------------

### Initialize Kota Health Employee UI

Source: https://docs.kota.io/sdk

Initializes the Kota Health Employee embedded UI. Requires an employee access token and allows for optional configuration of the container and theme.

```javascript
const employeeEmbed = Kota.Health.employee();

const themeConfig = {
  primaryColor: '#0875E1',
  backgroundColor: '#fff',
  radius: '12px',
  ringColor: '#0875E1'
};

employeeEmbed.init(
  employeeAccessToken,
  { container: 'employee', theme: themeConfig }
);
```

--------------------------------

### Initialize Kota Health Employer UI

Source: https://docs.kota.io/sdk/embed-sdk-reference

Initializes the Kota Health Employer embedded UI. Requires an employer access token and allows for optional configuration of the container and theme.

```javascript
const employerEmbed = Kota.Health.employer();

const themeConfig = {
  primaryColor: '#0875E1',
  backgroundColor: '#fff',
  radius: '12px',
  ringColor: '#0875E1'
};

employerEmbed.init(
  employerAccessToken,
  { container: 'employer', theme: themeConfig }
);
```

--------------------------------

### Initialize Kota Health Employer UI

Source: https://docs.kota.io/sdk

Initializes the Kota Health Employer embedded UI. Requires an employer access token and allows for optional configuration of the container and theme.

```javascript
const employerEmbed = Kota.Health.employer();

const themeConfig = {
  primaryColor: '#0875E1',
  backgroundColor: '#fff',
  radius: '12px',
  ringColor: '#0875E1'
};

employerEmbed.init(
  employerAccessToken,
  { container: 'employer', theme: themeConfig }
);
```

--------------------------------

### Include Kota Embed SDK Script

Source: https://docs.kota.io/get-started/plan-your-integration/frontend-sdk-integration

Include the Kota.js script on each page where the Embed SDK is needed. Use the provided CDN URLs for test or production environments to ensure compliance and access to future updates.

```HTML
<script src="https://test.js.kota.io/v1"></script>
```

--------------------------------

### Initialize Employer and Employee UIs

Source: https://docs.kota.io/get-started/plan-your-integration/frontend-sdk-integration

Initializes the Kota Health Employer and Employee embedded UIs using an access token obtained from your backend. The UI can be configured with a specific container element and theme settings.

```JavaScript
const employerEmbed = Kota.Health.employer();
const themeConfig = {
  primaryColor: '#0875E1',
  backgroundColor: '#fff',
  radius: '12px',
  ringColor: '#0875E1'
};

employerEmbed.init(
  employerAccessToken,
  { container: 'employer', theme: themeConfig }
);
```

```JavaScript
const employeeEmbed = Kota.Health.employee();
const themeConfig = {
  primaryColor: '#0875E1',
  backgroundColor: '#fff',
  radius: '12px',
  ringColor: '#0875E1'
};

employeeEmbed.init(
  employeeAccessToken,
  { container: 'employee', theme: themeConfig }
);
```

--------------------------------

### Include Kota.js for Production

Source: https://docs.kota.io/sdk

Include this script tag to load the Kota.js SDK for production environments. This ensures compliance and access to the latest updates.

```html
<script src="https://js.kota.io/v1"></script>
```

--------------------------------

### Include Kota.js for Production

Source: https://docs.kota.io/sdk/embed-sdk-reference

Include this script tag to load the Kota.js SDK for production environments. This ensures compliance and access to the latest updates.

```html
<script src="https://js.kota.io/v1"></script>
```

--------------------------------

### Retrieve Contribution Report using cURL

Source: https://docs.kota.io/api/contribution-reports/retrieve-contribution-report

This snippet demonstrates how to fetch a specific contribution report using the cURL command-line tool. It includes the GET request to the API endpoint and the necessary Authorization header for authentication.

```bash
curl https://test.api.kota.io/contribution_reports/ctr_3b1333d87d9d4fd6ad83ba7f6b0e951a \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Handle Employer Page Loaded Event

Source: https://docs.kota.io/sdk

Sets up a listener for the 'pageLoaded' event specifically for the employer embedded UI. The handler function receives an event object containing the page title.

```javascript
employerEmbed.on('pageLoaded', function(event) {
  // Handle employer pageLoaded event
  console.log('Employer page loaded:', event.pageTitle);
})
```

--------------------------------

### Handle Employee Page Loaded Event

Source: https://docs.kota.io/sdk

Sets up a listener for the 'pageLoaded' event specifically for the employee embedded UI. The handler function receives an event object containing the page title.

```javascript
const employeeEmbed = Kota.Health.employee();
employeeEmbed.init(employeeAccessToken);

employeeEmbed.on('pageLoaded', function(event) {
  // Handle employee pageLoaded event
  console.log('Employee page loaded:', event.pageTitle);
})
```

--------------------------------

### Handle Employer Page Loaded Event

Source: https://docs.kota.io/sdk/embed-sdk-reference

Sets up a listener for the 'pageLoaded' event specifically for the employer embedded UI. The handler function receives an event object containing the page title.

```javascript
employerEmbed.on('pageLoaded', function(event) {
  // Handle employer pageLoaded event
  console.log('Employer page loaded:', event.pageTitle);
})
```
Tokens:
Raw