> 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 Employee Salaries

Salary records let you provide the compensation data Kota needs for salary-based benefits. Each record belongs to an employee and contains:

* `amount`: The salary amount for the selected pay frequency
* `currency`: The ISO 4217 currency code
* `pay_frequency`: `annual`, `monthly`, `bi_weekly`, or `weekly`
* `effective_from`: The date the salary takes effect, in `YYYY-MM-DD` format

Before managing salaries, [create the employee](/core-components/employer-employee-management) and save their `employee_id`.

## Create a Salary Record

Create the employee's first salary record or add a record for a salary change. The `amount` must be greater than zero.

**`POST /employees/$employeeId/salaries`**

```cURL POST /employees/$employeeId/salaries
curl -X POST https://test.api.kota.io/employees/ee_3b1333d87d9d4fd6ad83ba7f6b0e951a/salaries \
  -H "Authorization: Bearer <YOUR_API_SECRET_KEY>" \
  -H "Idempotency-Key: <UNIQUE_IDEMPOTENCY_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 65000,
    "currency": "eur",
    "pay_frequency": "annual",
    "effective_from": "2026-01-01"
  }'
```

Use a new idempotency key for each logical salary creation. Reuse that key only when retrying the exact same request. See [Authentication and idempotency](/core-components/authentication#idempotent-requests).

[View the Create salary API documentation](/api-reference/salaries/create-salary).

> **Info**
>
> Salary records are immutable. To record a salary change, create another record with the new amount and `effective_from` date.

## Retrieve Salary Records

Use the salary endpoints according to the data you need:

* [List salary records](/api-reference/salaries/list-salaries) returns a paginated page in descending `effective_from` order. Use `page` and `page_size` to navigate results. `page_size` defaults to 10 and has a maximum of 100. The response includes `items`, `page`, `page_size`, `total_count`, `has_next_page`, and `has_previous_page`.
* [Retrieve the current salary record](/api-reference/salaries/retrieve-current-salary) returns the record with the latest `effective_from` date on or before today.
* [Retrieve a salary record](/api-reference/salaries/retrieve-salary) returns a specific record by its `salary_id`.

Future-dated records appear in the list, but they do not become current until their `effective_from` date.

**`GET /employees/$employeeId/salaries/current`**

```cURL GET /employees/$employeeId/salaries/current
curl https://test.api.kota.io/employees/ee_3b1333d87d9d4fd6ad83ba7f6b0e951a/salaries/current \
  -H "Authorization: Bearer <YOUR_API_SECRET_KEY>"
```

## Correct a Salary Record

There is no update endpoint for salary records. If a record was submitted in error:

1. [Delete the incorrect salary record](/api-reference/salaries/delete-salary).
2. Create a replacement record with the correct values.

Deleting a record removes it from salary lists and from consideration as the current salary. If you delete the current record, the next most recent eligible record becomes current.

> **Warning**
>
> Deleting a salary record a second time returns a `404` response.

## Listen for Salary Events

Kota emits the following events when salary records change:

* `employee.salary_created`
* `employee.salary_deleted`

Salary events use a V2 envelope. The timestamp field is `created`. The `data` object is sparse and contains identifiers rather than the complete salary record.

```json
{
  "id": "evt_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "type": "employee.salary_created",
  "platform_id": "pt_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "data": {
    "id": "sal_3b1333d87d9d4fd6ad83ba7f6b0e951a",
    "employee_id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a"
  },
  "created": "2024-12-01T00:00:00Z"
}
```

For `employee.salary_created`, use [Retrieve a salary record](/api-reference/salaries/retrieve-salary) to hydrate the complete record. For `employee.salary_deleted`, the deleted record itself is no longer retrievable. Retain salary state locally if you need the deleted record's details, then reconcile the employee's remaining records with [List salary records](/api-reference/salaries/list-salaries) and [Retrieve the current salary record](/api-reference/salaries/retrieve-current-salary).

For shared webhook delivery and signature validation guidance only, see [Working with Events](/core-components/webhooks-and-events/working-with-events). Its V1 payload shape does not apply to salary events.