Server-side Integration

This page is a concise checklist of what your backend must do to support Kota Hosted. For step-by-step guidance, jump into the linked deep-dives below.

Want to jump straight into the API reference?

Check out our API reference documentation

Authentication & idempotency (quick reference)

Authenticate with API keys and include idempotency keys on POST requests.

Guide: Authentication & Idempotency
API docs: Authentication · Idempotent requests

What your server must do

Create employers and employees early, then store employer_id and employee_id received from Kota.
Generate single-use Hosted session links and send employees to the provided URL.
Receive and process webhooks, especially action-required events.
Support offboarding flows (with additional safeguards for employees).

Create employers and employees

Create employers first, then employees referencing the employer_id. Send these records as soon as they’re available to avoid delays while Kota completes regulatory checks.

If the employer and their employees are sent to Kota immediately before an employee accesses the Hosted UI, it’s likely that some employees will not have been processed yet, delaying the employee’s ability to proceed until processing is complete.

Detailed guide: Managing employers and employees
API references: Employer APIs · Employee APIs

Support offboarding

Employer offboarding removes Hosted UI access but does not cancel employees’ policies automatically. Employee offboarding will cancel policies and must be handled with care.

Safeguard: If triggered in error and before the effective date, you can cancel employee offboarding.

Generate a Hosted session link

Hosted sessions provide secure, time-limited access to Kota’s fully managed benefits UI:

Employee sessions - Allow employees to enroll in benefits, manage dependants, and view policy details

Each session link:

Expires after 60 minutes
Is valid for a single use only
Should be generated fresh each time an employee accesses Kota functionality

Kota Hosted currently supports employee flows only. Employer setup and management flows are coming in early 2026.

Generate Links

Use the Hosted Session API to create session links. Once generated, send the employee to the provided link URL.

Learn more about frontend implementation

Generate an employee session link:

1 curl -X POST https://test-api.kota.io/hosted/sessions \
2   -H "Authorization: Bearer <YOUR_API_SECRET_KEY>" \
3   -H "Idempotency-Key: 4fe9c195-56db-4cc2-85d3-5512cf558d60" \
4   -H "Content-Type: application/json" \
5   -d '{
6     "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a",
7     "employee_id": "ee_2c11435d87d5d4a46ad83ba7f6b0e91b"
8   }'

Handle webhooks and required actions

Configure a webhook receiver to process asynchronous events.

Deep-dive: Webhooks and events
API overview: Events & Webhooks
Examples: Working with webhooks

For action_required events, the reason and reason_description (example) properties can be sent directly as customer communications as the title and body of a message while the due_at property should be used to convey the deadline to the customer.

Advanced: Contribution reporting

Retrieve employer/period reports for accurate payroll, including employer vs employee portions, adjustments, and pro-rations.

Guide: Contribution reporting
API: Contribution Reports

Prefer to browse the API directly?

Open the API Reference