> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kota.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kota.io/_mcp/server.

# Managing Employers and Employees

Every integration with Kota requires syncing employer and employee data. This guide covers creating, managing, and offboarding these core entities. Before you are able to create employers and employees, you need to be able to [authenticate with the Kota API](/core-components/authentication).

## Creating Employers and Employees

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

> **Warning**
>
> If you send employers and employees to Kota immediately before they need to access benefits, some may not be processed yet, causing delays. Send data as early as possible.

**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.

> **Info**
>
> While you can create an employer with minimal data, we recommend providing optional parameters to reduce friction during the insurance journey.

[View Employer API documentation](/api-reference/employers/list-employers)

**Example request:**

**`POST /employers`**

```cURL POST /employers
curl -X POST https://test.api.kota.io/employers \
  -H "Authorization: Bearer <YOUR_API_SECRET_KEY>" \
  -H "Idempotency-Key: 4fe9c195-56db-4cc2-85d3-5512cf558d60" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "ABC Co Limited",
    "legal_address": {
      "line1": "128 Lower Baggot Street",
      "city": "Dublin",
      "postal_code": "D02 A430",
      "country_code": "ie"
    },
    "contact": {
      "name": "Jane Liu",
      "email": "jane.liu@kota.io"
    }
  }'
```

### 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.

> **Info**
>
> While you can create an employee with minimal data, we recommend providing optional parameters to reduce friction during the insurance journey.

[View Employee API documentation](/api-reference/employees/list-employees)

**Example request:**

**`POST /employees`**

```cURL POST /employees
curl -X POST https://test.api.kota.io/employees \
  -H "Authorization: Bearer <YOUR_API_SECRET_KEY>" \
  -H "Idempotency-Key: 4fe9c195-56db-4cc2-85d3-5512cf558d60" \
  -H "Content-Type: application/json" \
  -d '{
    "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a",
    "first_name": "Jane",
    "last_name": "Liu",
    "date_of_birth": "1995-12-01",
    "sex_at_birth": "female",
    "home_address": {
      "line1": "128 Lower Baggot Street",
      "city": "Dublin",
      "postal_code": "D02 A430",
      "country_code": "ie"
    },
    "national_tax_id": "1234567T",
    "start_on": "2024-12-01",
    "email": "jane.liu@kota.io"
  }'
```

### Add Employee Salary Data

Some benefits use employee salary data for quoting and pricing. After creating an employee, add their current salary and any future salary changes as dated, immutable records.

[Learn how to manage employee salaries](/core-components/salary-management).

---

## 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:**

**`POST /employers/$employerId/offboard`**

```cURL POST /employers/$employerId/offboard
curl -X POST https://test.api.kota.io/employers/er_3b1333d87d9d4fd6ad83ba7f6b0e951a/offboard \
  -H "Authorization: Bearer <YOUR_API_SECRET_KEY>"
```

### Offboard an Employee

> **Error**
>
> This API will cancel the employee's insurance policies.

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:**

**`POST /employees/$employeeId/offboard`**

```cURL POST /employees/$employeeId/offboard
curl -X POST https://test.api.kota.io/employees/ee_3b1333d87d9d4fd6ad83ba7f6b0e951a/offboard \
  -H "Authorization: Bearer <YOUR_API_SECRET_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "offboard_on": "2024-01-15T09:30:00Z",
    "offboard_reason": "offboard_reason"
  }'
```

---