Leave
Leave endpoints: parameters, fields and example responses.
Developer documentation
- GET
/api/v1/leave-balances - GET
/api/v1/leave-requests - GET
/api/v1/leave-requests/{id} - GET
/api/v1/leave-types - GET
/api/v1/leave-types/{id}
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
| Field | Type | Description |
|---|---|---|
employee_ (query) | string (uuid) | Only balances of this employee. |
cursor (query) | string | The next_cursor value of the previous response. It is opaque; send it with the same key and the same filter. |
limit (query) | integer | Page size; a value above the maximum is lowered to the maximum. |
Responses
200 Successful
A list response comes in the { data, next_cursor } envelope.
| Field | Type | Description |
|---|---|---|
employee_ | string (uuid)required | |
leave_ | string (uuid)required | |
unit | stringrequired | Values: day, hour |
balance | numberrequired | Ledger total; approved future leave is already deducted. |
reserved | numberrequired | Total of the requests waiting for approval. |
available | numberrequired | Available 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_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503: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
| Field | Type | Description |
|---|---|---|
employee_ (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) | string | Only 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_ (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) | string | The next_cursor value of the previous response. It is opaque; send it with the same key and the same filter. |
limit (query) | integer | Page size; a value above the maximum is lowered to the maximum. |
Responses
200 Successful
A list response comes in the { data, next_cursor } envelope.
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | |
company_ | string (uuid)required | |
employee_ | string (uuid)required | |
type_ | booleanrequired | When 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_ | string (uuid)requirednullable | Leave type; null when the type is hidden. |
status | stringrequired | awaiting_document: waiting for a document; pending: waiting for approval; approved; rejected; cancelled. Values: awaiting_document, pending, approved, rejected, cancelled |
start_ | string (date)required | |
end_ | string (date)required | |
half_ | booleanrequirednullable | |
amount | numberrequirednullable | Duration in the unit (days or hours). |
unit | stringrequirednullable | Values: day, hour |
paid | booleanrequirednullable | |
is_ | booleanrequired | The 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_ | string (date-time)required | |
updated_ | string (date-time)required | The 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_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503: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
| Field | Type | Description |
|---|---|---|
id (path) | string (uuid)required | ID of the leave request. |
Responses
200 Successful
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | |
company_ | string (uuid)required | |
employee_ | string (uuid)required | |
type_ | booleanrequired | When 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_ | string (uuid)requirednullable | Leave type; null when the type is hidden. |
status | stringrequired | awaiting_document: waiting for a document; pending: waiting for approval; approved; rejected; cancelled. Values: awaiting_document, pending, approved, rejected, cancelled |
start_ | string (date)required | |
end_ | string (date)required | |
half_ | booleanrequirednullable | |
amount | numberrequirednullable | Duration in the unit (days or hours). |
unit | stringrequirednullable | Values: day, hour |
paid | booleanrequirednullable | |
is_ | booleanrequired | The 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_ | string (date-time)required | |
updated_ | string (date-time)required | The 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_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503: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
| Field | Type | Description |
|---|---|---|
cursor (query) | string | The next_cursor value of the previous response. It is opaque; send it with the same key and the same filter. |
limit (query) | integer | Page size; a value above the maximum is lowered to the maximum. |
Responses
200 Successful
A list response comes in the { data, next_cursor } envelope.
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | |
company_ | string (uuid)requirednullable | Company of the type; null for a built-in type. |
code | stringrequirednullable | |
name | stringrequired | |
paid | booleanrequired | |
unit | stringrequired | Values: day, hour |
requires_ | booleanrequired | |
tracks_ | booleanrequired | |
allow_ | booleanrequired | |
calendar_ | stringrequired | hidden: 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 |
active | booleanrequired | |
created_ | string (date-time)required | |
updated_ | string (date-time)required | The 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_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503: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
| Field | Type | Description |
|---|---|---|
id (path) | string (uuid)required | ID of the leave type. |
Responses
200 Successful
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | |
company_ | string (uuid)requirednullable | Company of the type; null for a built-in type. |
code | stringrequirednullable | |
name | stringrequired | |
paid | booleanrequired | |
unit | stringrequired | Values: day, hour |
requires_ | booleanrequired | |
tracks_ | booleanrequired | |
allow_ | booleanrequired | |
calendar_ | stringrequired | hidden: 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 |
active | booleanrequired | |
created_ | string (date-time)required | |
updated_ | string (date-time)required | The 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_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503:timeout