> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kota.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kota.io/_mcp/server.

# API Integration Overview

> Build a fully custom benefits experience through Kota's APIs

The API-Only integration gives you complete control over the user experience. Instead of using Kota's Hosted Page or Embed SDK, you'll orchestrate the entire benefits journey - quoting, setup, enrollment, and policy management - through direct API calls.

This approach offers maximum flexibility but requires implementing all user flows yourself.

> **Info**
>
> Before starting, review the foundational guides:
>
> * [Key concepts](/key-concepts) - Core entities like Employer, Employee, Group, and Policy
> * [API basics](/core-components/authentication) - Authentication and best practices
> * [Managing employers and employees](/core-components/employer-employee-management) - Creating and syncing data

---

## How API-Only Integration Works

The API-Only integration operates across two main workflows: **group-level benefit setup** (where employers configure and activate benefits) and **employee-level benefit setup** (where individual employees enroll and manage their coverage). Both workflows use a consistent intent-based pattern.

### Intent Pattern

An **intent** represents a specific action or workflow in the benefits lifecycle, such as requesting a quote, setting up a group policy, or enrolling an employee. Each intent encapsulates the data requirements, validation logic, and completion criteria for that action.

Every intent follows this structure:

1. **Create** - An intent is created (either by your platform or automatically by Kota)
2. **Fulfill data requirements** - The system returns dynamic data requirements that must be satisfied before proceeding
3. **Complete** - Once all requirements are fulfilled, the intent finalizes and creates result objects

This consistent pattern keeps integration predictable across all operations.

### Data Requirements Mechanism

Throughout all intents, Kota may request additional data to complete an operation. The API returns:

* **Required fields** - Specific data points needed to proceed
* **Field schemas** - Expected format and validation rules

Your platform must:

1. Present these requirements to users in your UI
2. Collect the necessary information
3. Submit data back through the [Adaptive Requirements Guide](/api/adaptive-requirements) and [requirements API](/api-reference/requirements/get-requirement). Answers can be submitted incrementally, and the API reports the fields still outstanding until the requirement is fulfilled
4. Complete the intent flow once requirements are satisfied

---

## Group-Level Benefit Setup

The group-level workflow establishes the employer's benefits offering. The exact flow depends on your integration scenario.

### Integration Scenarios

**Standard flow** - Full in-platform setup

For new benefits or platforms managing the entire quoting process, you'll handle all steps from data sync through policy activation.

**Simplified flow** - Pre-negotiated policies

In some cases, quoting is handled off-platform and Kota creates groups with group policies. Your platform's primary responsibility is adding employees to the appropriate groups.

**Migrations** - Transitioning existing benefits

When migrating existing benefits to Kota, groups and group policies are typically created during the migration process.

---

### Standard Flow

#### Employer and Employee Data

Before setting up benefits, ensure employer and employee data is synced to Kota. This provides the foundation for quoting and policy setup.

[Learn how to manage employers and employees](/core-components/employer-employee-management)

#### Create Group and Add Employees

Create a **Group** to represent the benefits offering and add employees who will be eligible for coverage. Groups can represent:

* **Single benefit** - One insurance plan (e.g., health insurance)
* **Bundle** - Predefined combination of benefits (e.g., health + life) that must be managed together

> **Warning**
>
> Bundles cannot be split. If a group contains multiple benefits, they must all be managed as a unit.

#### Request Quotes

Use **Quoting Intents** to request quotes for the group. You can create multiple quoting intents to compare offerings from different providers.

**Result:** One or more **Quote** objects containing pricing, coverage details, and terms.

> **Info**
>
> Each intent may request additional data before completion, such as missing company details or employee information needed for accurate quoting.

#### Activate Group Policy

Once the employer selects a quote, create a **Setup Intent** to establish the group policy with the chosen provider.

**Result:** A **Group Policy** object that defines:

* Coverage terms and conditions
* Policy start and renewal dates
* Enrolled employees
* Premium structure

**Flow diagram:**

```
Sync employer and employee data
  ↓
Create group + add employees
  ↓
Quoting Intent
  ↓
Quotes
  ↓
Setup Intent
  ↓
Group Policy
```

---

### Simplified Flow

For scenarios where groups and policies are pre-created by Kota:

**Flow diagram:**

```
Sync employer and employee data
  ↓
Retrieve existing groups
  ↓
Add employees to groups
```

---

## Employee-Level Benefit Setup

Once group policies are active, employees can enroll in coverage, add dependents/beneficiaries, or opt out.

### Enrollment

An **Enrollment Intent** is created for eligible employees when your integration starts the
enrolment flow, either automatically while [adding the employee to a group](/api/employee-flow/assign-employee-to-group)
or manually later. The intent guides the employee through enrollment, may request
additional information, and ultimately creates an individual **Policy** for the employee.

[Learn how to assign employees to groups](/api/employee-flow/assign-employee-to-group)
and [handle employee enrolment](/api/employee-flow/employee-enrolment).

### Dependents & Beneficiaries

Employees can add dependents or beneficiaries (e.g. spouse/partner, children) to the benefit during the enrollment process or the cooling-off period. Dependents/beneficiaries are included in the enrollment intent's data requirements.

**Result:** Dependents/beneficiaries linked to the employee's policy, updating coverage and premiums accordingly.

**Flow diagrams:**

During enrollment:

```
Enrollment Intent
  ↓
Update Dependants Intent
  ↓
Policy with dependents/beneficiaries included
```

During cooling-off period:

```
Individual Policy
  ↓
Update Dependants Intent
  ↓
Updated Policy (dependents/beneficiaries added)
```

### Opting Out

Employees who decline coverage use an **Opt-out Intent** within a defined cooling-off period.

**Result:** The employee is marked as opted out and does not receive coverage.

> **Info**
>
> Opt-out windows are time-limited. Ensure your UI clearly communicates deadlines to employees.

**Flow diagrams:**

During enrollment:

```
Enrollment Intent
  ↓
Employee reviews
  ↓
Opt-out Intent
  ↓
No policy issued
```

During cooling-off period:

```
Enrollment Intent
  ↓
Individual Policy
  ↓
Opt-out Intent
  ↓
Policy cancelled
```

---

## Next Steps

The API-Only integration requires building multiple user flows. Consider starting with:

1. **Group quoting and setup** - Allow employers to request quotes and activate policies
2. **Employee enrollment** - Let employees accept coverage and add dependents or beneficiaries
3. **Policy management** - Display active policies and handle changes

**Advanced topics:**

For platforms managing payroll or benefits administration, explore [Contribution Reporting](/core-components/contribution-reporting) to programmatically handle benefit contributions and streamline reconciliation.

**Resources:**

* [API Reference](/api-reference) - Detailed endpoint documentation and request/response schemas
* [Webhooks and Events](/core-components/webhooks-and-events) - Handle asynchronous notifications