> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.kota.io/api/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kota.io/_mcp/server. # API ## Docs - [Insurance Disclosures](https://docs.kota.io/api/insurance-disclosures.md): Retrieve and display insurance disclosure text in Kota-powered journeys - [Employer Health Insurance Setup](https://docs.kota.io/api/employer-health-insurance.md): Complete guide for building the employer experience for group health insurance using Kota's API - [Adaptive Requirements Guide](https://docs.kota.io/api/adaptive-requirements.md): Resolve action-required intents by retrieving dynamic requirement schemas, rendering them with @kotaio/adaptive-form, and submitting answers - [Assign Employee to a Group](https://docs.kota.io/api/employee-flow/assign-employee-to-group.md): Add an employee to a benefit group and start the enrolment flow when needed - [Employee Enrolment](https://docs.kota.io/api/employee-flow/employee-enrolment.md): Enrol an employee into a group's health insurance policy using Kota's Enrolment Intent API - [Dependent Management](https://docs.kota.io/api/employee-flow/dependent-management.md): Add, remove, and confirm dependents during enrolment or after policy issuance using Kota's Dependents Management Intent API > **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.kota.io/api/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