Skip to content

Leave

Leave endpoints: parameters, fields and example responses.

Developer documentation

Lists leave balances

GET /api/v1/leave-balances

Scope: leave:read

Balance per employee for the leave types that keep a balance. The order is by employee and type ID. The balance of a hidden leave type is returned only to a key with the field:health scope and the health field class on its role. Sample records are not listed.

Parameters

leave_balances.list: Parameters
FieldTypeDescription
employee_id (query)string (uuid)Only balances of this employee.
cursor (query)stringThe next_cursor value of the previous response. It is opaque; send it with the same key and the same filter.
limit (query)integerPage size; a value above the maximum is lowered to the maximum.

Responses

200 Successful

A list response comes in the { data, next_cursor } envelope.

leave_balances.list: Each item in the list (data[])
FieldTypeDescription
employee_idstring (uuid)required
leave_type_idstring (uuid)required
unitstringrequired Values: day, hour
balancenumberrequiredLedger total; approved future leave is already deducted.
reservednumberrequiredTotal of the requests waiting for approval.
availablenumberrequiredAvailable balance: balance minus reserved.
Example response
{
  "data": [
    {
      "employee_id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "leave_type_id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
      "unit": "day",
      "balance": 9,
      "reserved": 2,
      "available": 7
    }
  ],
  "next_cursor": null
}

Error codes

  • 400: bad_request, validation_failed, key_in_query, cookie_with_key, idempotency_key_required, idempotency_key_invalid, cursor_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: timeout

Lists leave requests

GET /api/v1/leave-requests

Scope: leave:read

Leave requests of the employees inside the key's scope. The note and the document are not returned. The order is by ID and stable; no total count is returned. Sample records are not listed.

Parameters

leave_requests.list: Parameters
FieldTypeDescription
employee_id (query)string (uuid)Only requests of this employee.
from (query)string (date)Requests that do not end before this day (YYYY-MM-DD).
status (query)stringOnly requests in this status; the filter looks at the visible status. A request with a hidden type does not match awaiting_document or rejected; it matches pending and cancelled. Values: awaiting_document, pending, approved, rejected, cancelled
to (query)string (date)Requests that do not start after this day (YYYY-MM-DD).
updated_since (query)string (date-time)Only records whose updated_at is greater than or equal to this moment (ISO 8601 with a time zone). Inclusive: send the last updated_at you saw and deduplicate by ID.
cursor (query)stringThe next_cursor value of the previous response. It is opaque; send it with the same key and the same filter.
limit (query)integerPage size; a value above the maximum is lowered to the maximum.

Responses

200 Successful

A list response comes in the { data, next_cursor } envelope.

leave_requests.list: Each item in the list (data[])
FieldTypeDescription
idstring (uuid)required
company_idstring (uuid)required
employee_idstring (uuid)required
type_hiddenbooleanrequiredWhen true the leave type is hidden from this key: leave_type_id, half_day, amount, unit and paid are null; the "awaiting document" status shows as pending and a rejection shows as cancelled (in the event feed too).
leave_type_idstring (uuid)requirednullableLeave type; null when the type is hidden.
statusstringrequiredawaiting_document: waiting for a document; pending: waiting for approval; approved; rejected; cancelled. Values: awaiting_document, pending, approved, rejected, cancelled
start_datestring (date)required
end_datestring (date)required
half_daybooleanrequirednullable
amountnumberrequirednullableDuration in the unit (days or hours).
unitstringrequirednullable Values: day, hour
paidbooleanrequirednullable
is_demobooleanrequiredThe request belongs to an employee that came with the sample data. List endpoints do not return sample records; a single-record read returns them with this field set to true.
created_atstring (date-time)required
updated_atstring (date-time)requiredThe moment the state of the request visible to this key last changed (UTC). For a request with a hidden type only creation, decision and cancellation change this value.
Example response
{
  "data": [
    {
      "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
      "employee_id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "type_hidden": false,
      "leave_type_id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
      "status": "approved",
      "start_date": "2026-07-06",
      "end_date": "2026-07-10",
      "half_day": false,
      "amount": 5,
      "unit": "day",
      "paid": true,
      "is_demo": false,
      "created_at": "2026-06-15T11:20:00.000Z",
      "updated_at": "2026-06-16T08:05:00.000Z"
    }
  ],
  "next_cursor": null
}

Error codes

  • 400: bad_request, validation_failed, key_in_query, cookie_with_key, idempotency_key_required, idempotency_key_invalid, cursor_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: timeout

Returns one leave request

GET /api/v1/leave-requests/{id}

Scope: leave:read

The note and the document are not returned. A record the key cannot see and a record that does not exist get the same 404 response.

Parameters

leave_requests.get: Parameters
FieldTypeDescription
id (path)string (uuid)requiredID of the leave request.

Responses

200 Successful

leave_requests.get: Responses
FieldTypeDescription
idstring (uuid)required
company_idstring (uuid)required
employee_idstring (uuid)required
type_hiddenbooleanrequiredWhen true the leave type is hidden from this key: leave_type_id, half_day, amount, unit and paid are null; the "awaiting document" status shows as pending and a rejection shows as cancelled (in the event feed too).
leave_type_idstring (uuid)requirednullableLeave type; null when the type is hidden.
statusstringrequiredawaiting_document: waiting for a document; pending: waiting for approval; approved; rejected; cancelled. Values: awaiting_document, pending, approved, rejected, cancelled
start_datestring (date)required
end_datestring (date)required
half_daybooleanrequirednullable
amountnumberrequirednullableDuration in the unit (days or hours).
unitstringrequirednullable Values: day, hour
paidbooleanrequirednullable
is_demobooleanrequiredThe request belongs to an employee that came with the sample data. List endpoints do not return sample records; a single-record read returns them with this field set to true.
created_atstring (date-time)required
updated_atstring (date-time)requiredThe moment the state of the request visible to this key last changed (UTC). For a request with a hidden type only creation, decision and cancellation change this value.
Example response
{
  "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
  "employee_id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "type_hidden": false,
  "leave_type_id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
  "status": "approved",
  "start_date": "2026-07-06",
  "end_date": "2026-07-10",
  "half_day": false,
  "amount": 5,
  "unit": "day",
  "paid": true,
  "is_demo": false,
  "created_at": "2026-06-15T11:20:00.000Z",
  "updated_at": "2026-06-16T08:05:00.000Z"
}

Error codes

  • 400: bad_request, validation_failed, key_in_query, cookie_with_key, idempotency_key_required, idempotency_key_invalid, cursor_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: timeout

Lists leave types

GET /api/v1/leave-types

Scope: leave:read

Built-in types (company_id null) and the own types of the companies inside the key's scope. The order is by ID and stable; no total count is returned.

Parameters

leave_types.list: Parameters
FieldTypeDescription
cursor (query)stringThe next_cursor value of the previous response. It is opaque; send it with the same key and the same filter.
limit (query)integerPage size; a value above the maximum is lowered to the maximum.

Responses

200 Successful

A list response comes in the { data, next_cursor } envelope.

leave_types.list: Each item in the list (data[])
FieldTypeDescription
idstring (uuid)required
company_idstring (uuid)requirednullableCompany of the type; null for a built-in type.
codestringrequirednullable
namestringrequired
paidbooleanrequired
unitstringrequired Values: day, hour
requires_documentbooleanrequired
tracks_balancebooleanrequired
allow_half_daybooleanrequired
calendar_visibilitystringrequiredhidden: the type, amount and document state of a request of this type go only to a key with the field:health scope and the health field class on its role. Values: named, hidden
activebooleanrequired
created_atstring (date-time)required
updated_atstring (date-time)requiredThe moment the record's own fields last changed (UTC).
Example response
{
  "data": [
    {
      "id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
      "company_id": null,
      "code": null,
      "name": "Mazeret izni",
      "paid": true,
      "unit": "day",
      "requires_document": false,
      "tracks_balance": true,
      "allow_half_day": true,
      "calendar_visibility": "named",
      "active": true,
      "created_at": "2026-01-05T08:00:00.000Z",
      "updated_at": "2026-01-05T08:00:00.000Z"
    }
  ],
  "next_cursor": null
}

Error codes

  • 400: bad_request, validation_failed, key_in_query, cookie_with_key, idempotency_key_required, idempotency_key_invalid, cursor_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: timeout

Returns one leave type

GET /api/v1/leave-types/{id}

Scope: leave:read

A record the key cannot see and a record that does not exist get the same 404 response.

Parameters

leave_types.get: Parameters
FieldTypeDescription
id (path)string (uuid)requiredID of the leave type.

Responses

200 Successful

leave_types.get: Responses
FieldTypeDescription
idstring (uuid)required
company_idstring (uuid)requirednullableCompany of the type; null for a built-in type.
codestringrequirednullable
namestringrequired
paidbooleanrequired
unitstringrequired Values: day, hour
requires_documentbooleanrequired
tracks_balancebooleanrequired
allow_half_daybooleanrequired
calendar_visibilitystringrequiredhidden: the type, amount and document state of a request of this type go only to a key with the field:health scope and the health field class on its role. Values: named, hidden
activebooleanrequired
created_atstring (date-time)required
updated_atstring (date-time)requiredThe moment the record's own fields last changed (UTC).
Example response
{
  "id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
  "company_id": null,
  "code": null,
  "name": "Mazeret izni",
  "paid": true,
  "unit": "day",
  "requires_document": false,
  "tracks_balance": true,
  "allow_half_day": true,
  "calendar_visibility": "named",
  "active": true,
  "created_at": "2026-01-05T08:00:00.000Z",
  "updated_at": "2026-01-05T08:00:00.000Z"
}

Error codes

  • 400: bad_request, validation_failed, key_in_query, cookie_with_key, idempotency_key_required, idempotency_key_invalid, cursor_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: timeout