Managing Employers and Employees

Every integration with Kota requires syncing employer and employee data. This guide covers creating, managing, and offboarding these core entities.

Creating Employers and Employees

The foundation of any Kota integration is syncing employer and employee data to our platform.

Best practice: Send employer and employee data to Kota as soon as it’s available in your system. Our platform must complete regulatory checks and processes before entities become active.

Create an Employer

Creating an employer is a single POST request. Save the returned employer_id to associate employees and access employer functionality.

View Employer API documentation

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
  }'

Create an Employee

Once an employer is created, add employees by referencing the employer_id. Save the returned employee_id for future operations.

Employees begin in pending status while regulatory checks are completed, then progress to active when eligible for benefits.

View Employee API documentation

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
  }'

Offboarding

Kota supports both employer and employee offboarding, but they serve different purposes.

Offboard an Employer

Offboarding an employer means they’re leaving your platform. This triggers a special process where employee insurance policies are not automatically cancelled, since employees haven’t necessarily left their jobs.

Kota will continue working directly with the employer due to our regulatory relationship and help them manage their insurance contracts.

Example request:

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

Offboard an Employee

Offboarding an employee means they’ve ended employment with their employer. Use this API with extreme caution as it begins the process of cancelling all their insurance policies.

If you call this in error and catch it before the offboarding date, you can use the cancel offboarding API to reverse it.

Example request:

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