API-Only Integration Overview

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.

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 requirements API
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

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

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.

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 automatically created for eligible employees when a group policy is created or when a new employee is added to a group with an existing group policy. The intent guides the employee through enrollment, may request additional information, and ultimately creates an individual Policy for the employee.

Learn more about enrollment intents, state management, and handling requirements →

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.

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 to programmatically handle benefit contributions and streamline reconciliation.

Resources:

• API Reference - Detailed endpoint documentation and request/response schemas
• Webhooks and Events - Handle asynchronous notifications