API Reference

Managing Employee Salaries

Create and retrieve dated salary records for employees.

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

View the Create salary API documentation.

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 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 returns the record with the latest effective_from date on or before today.
  • Retrieve a salary record 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 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.
  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.

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. Handlers should read version, not api_version. The data object is sparse and contains identifiers rather than the complete salary record.

1{
2  "id": "evt_3b1333d87d9d4fd6ad83ba7f6b0e951a",
3  "type": "employee.salary_created",
4  "platform_id": "pt_3b1333d87d9d4fd6ad83ba7f6b0e951a",
5  "data": {
6    "id": "sal_3b1333d87d9d4fd6ad83ba7f6b0e951a",
7    "employee_id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a"
8  },
9  "created_at": "2024-12-01T00:00:00Z",
10  "object": "event",
11  "version": "V2"
12}

For employee.salary_created, use Retrieve a salary record 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 and Retrieve the current salary record.

For shared webhook delivery and signature validation guidance only, see Working with Events. Its V1 payload shape does not apply to salary events.