Server-side integration

To set up a compliant Kota backend integration, you must authenticate to Kota, learn API request best practices, and appropriately configure your webhooks.

Want to jump straight into the API reference?

Check out our API reference.

Authenticate to Kota

The Kota API uses API keys to authenticate requests. Test mode secret keys have the prefix pk_test_ and live mode secret keys have the prefix pk_live_.

Your API keys carry many privileges so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Read more in the authentication section of our API reference.

Here’s an example API call:

1
curl https://test.api.kota.io/employees/$employee_id \
2
  -H "Authorization: Bearer <YOUR_API_SECRET_KEY>"

API request best practices

Kota recommends adding an idempotency key to all POST requests. Make sure that the key is unique, such as a universally unique identifier (UUID). These keys allow you to safely retry requests if you encounter a network error. Read more about how we treat idempotent requests here.

Here’s an example idempotent API call:

1
curl https://test.api.kota.io/ENDPOINT \
2
  -H "Authorization: Bearer YOUR_API_SECRET_KEY" \
3
  -H "Idempotency-Key: 4fe9c195-56db-4cc2-85d3-5512cf558d60" \
4
  ... rest of request here

Add the necessary APIs to your platform

Successful implementations of Kota require a few key use-cases are handled to set up the system, load our regulatory-compliant Embedded UIs and ensure your platform doesn’t accidentally step into providing regulated services.

Add Employers and their Employees

The core to any integration with Kota are Employers and their Employees - adding them allows you to load their Embedded UIs

Best practice:

For the best customer experience we recommend platforms send Kota Employer and Employees as soon as they’re available. Our systems must complete a number of checks and processes on each employer and employee inline with regulatory requirements across the world.

Add Employers

Adding Employers to Kota is easy and a single POST request - then save their employer_id to your system to add their employees and load the Employer Embedded SDK.

Read the Employer API documentation to learn more.

An example request:

1
curl -X POST https://test.api.kota.io/employers \
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
    "legal_name": "ABC Co Limited",
7
    "legal_address": {
8
      "line1": "128 Lower Baggot Street",
9
      "city": "Dublin",
10
      "postal_code": "D02 A430",
11
      "country_code": "ie"
12
    },
13
    "contact": {
14
      "name": "Jane Liu",
15
      "email": "jane.liu@kota.io"
16
    }
17
  }'

Add Employeees

Once an employer is created, you can then add their employees referencing the employer_id. Adding them is just as easy as employers and similarly you should save their employee_id to your system so you can load the Employee Embedded SDK.

Employees begin in the pending state while we run various checks and set ups on them and will progress to active once they’re eligible for insurance cover.

Read the Employee API documentation to learn more.

An example request:

1
curl -X POST https://test.api.kota.io/employees \
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
    "first_name": "Jane",
8
    "last_name": "Liu",
9
    "date_of_birth": "1995-12-01",
10
    "sex_at_birth": "female",
11
    "home_address": {
12
      "line1": "128 Lower Baggot Street",
13
      "city": "Dublin",
14
      "postal_code": "D02 A430",
15
      "country_code": "ie"
16
    },
17
    "national_tax_id": "1234567T",
18
    "start_on": "2024-12-01",
19
    "email": "jane.liu@kota.io"
20
  }'

Retrieve an Embedded SDK token & pass it to your frontend

To load the Embedded UIs, which you can learn more about in the Embedded SDK Reference, you will need to get a token from the Embed Session API. Each request will return you a token for the specific Employer or Employee you’re authenticating.

Once you have the token you should return it to your frontend so they can initalise the SDK. You can learn more about the frontend implementation on our Frontend SDK integration page.

An example employer token request:

1
curl -X POST https://test.api.kota.io/embed/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
  }'

An example employee token request:

1
curl -X POST https://test.api.kota.io/embed/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
  }'

Support Offboarding

We support both Employer and Employee offboarding. Offboarding in this context differs slightly - Employer offboarding means the Employer is leaving your service whereas Employee offboarding means the Employee has ended employment with their Employer. These endpoints should be used carefully, especially Employee offboarding as this will cause their benefits to be terminated.

Offboard Employers

Offboarding an employer will remove their access to Embedded UIs and trigger a special offboarding process their employees where their insurance policies are not cancelled as their employer is leaving your platform and they haven’t necessarily left their employment.

Kota will continue to work with the employer due to our regulatory relationship with them and help to support them with their various insurance contracts.

Example offboarding request:

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

Offboard Employees

Offboarding employees should be taken with extreme caution as it will begin the process of cancelling all insurance policies they’re receiving from their employer.

If you were to call this in error, and catch it before the offbaording date, you can cancel offboarding an employee with the cancel offboarding API. This API is primarily designed to allow for flexible changes to employee offboarding, allowing platforms to cancel an offboarding to correct the offboarding plan or to correct an error.

Example offboarding request:

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

APIs for advanced use-cases

Example platforms include Payroll platforms, Employer of Record platforms and Enterprise Employers

Integrate Contribution Reports into your platform

Many employer/employee platforms that offer benefits, e.g. payroll platforms, often struggle with benefit reporting - Kota’s API provides contribution reports per employer and per period, split between employer and employee contributions. The employer-employee split in contributions is based on a number of factors, such as:

• Employer’s choices in covering spouse and number of children
• Specific country’s requirements around cover split
• Specific insurance provider requirements

How to use our reporting:

1. Finalize your report (or let them auto-finalise at the end of each month)
2. Lookup the report using the Retrieve a contribution report API
3. Retrieve the employee breakdowns for each report either iterating through our List endpoint or with our Retrieve employee breakdown endpoint with their employee_id

Read our API documentation for more information about Contribution Reports here.

Configure webhooks to handle Events

You can use webhooks to capture events that occur on your platform. They’re helpful when handling Kota events that occur asynchronously, or for those that you want to trigger additional actions for.

We consider handling a number of events and immediately issuing messaging to their audience as critical to a success integration. These are primarily to ensure employers and their employees are informed of important and time sensitive developments (such as an update on health insurance quote, and in the future - renewal upcoming) immediately. You can find details about how best to communicate these developments with your customers in the Communicating required actions with Employers and their Employees section below.

A list of these events:

• employer.health_insurance.quote.action_required - where an employer must take an action
• employee.health_insurance.offer.action_required - where an employee must take a time sensitive action for their policy.
• Future events around employer and employee policy renewal windows

Use the following resources to set up your webhooks and validate that they’ve been configured correctly:

• Events & webhooks APIs
• Working with webhooks
• List of all Events

Communicate required actions with Employers and their Employees

Some events, typically action_required events, contain a required_action object to help you present the key information to employers and employees.

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.

Using our specific messaging can help you ensure you don’t accidentally step into a regulated activity by using your own language around the health insurance sales and renewal customer journeys and it may be beneficial to make it clear the language is from Kota’s platform, on behalf of the firm providing the regulated insurance services.