Health
Health endpoints: parameters, fields and example responses.
Developer documentation
- GET
/api/v1/health/duty-roster - GET
/api/v1/health/physician-availability - POST
/api/v1/health/physician-premiums
Returns the duty roster (who works which duty or working time on which day)
GET /api/v1/health/duty-roster
Scope: health_scheduling:read
The company's active duty and working-time assignments for the selected days; the same rows as the HBYS duty list file on Health › Reports. The matching key is the staff code on the planning card; national ID numbers are never returned. If the key's role cannot see planning cards, staff_code is null. The range is at most 31 days. Ordered by id; demo records are not listed.
Parameters
| Field | Type | Description |
|---|---|---|
company_ (query) | string (uuid)required | Company. If it is outside the key's scope the list is empty. |
employee_ (query) | string (uuid) | Only this employee. |
from (query) | string (date)required | First day (YYYY-MM-DD). |
org_ (query) | string (uuid) | Only people in this unit (their current unit). |
to (query) | string (date)required | Last day (YYYY-MM-DD), at most 31 days with from. |
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 | |
staff_ | stringrequirednullable | Staff code on the planning card (the organisation's own code); null if the role cannot see planning cards. |
first_ | stringrequired | |
last_ | stringrequired | |
job_ | stringrequirednullable | |
unit | stringrequirednullable | The person's current unit. |
date | string (date)required | Day the assignment starts. |
shift_ | stringrequired | |
shift_ | stringrequired | |
shift_ | stringrequired | duty24: 24-hour duty, on_call, normal, flexible, half. Values: normal, duty24, on_call, flexible, half |
start_ | stringrequired | |
end_ | stringrequired | End time (HH:MM); the next day if not after the start. |
Example response
{
"data": [
{
"id": "5c4b3a29-1807-4f6e-9d5c-4b3a29180706",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"employee_id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"staff_code": "DR-0042",
"first_name": "Deniz",
"last_name": "Kaya",
"job_title": "Uzman Hekim",
"unit": "Acil Servis",
"date": "2026-12-02",
"shift_code": "N24",
"shift_name": "24 saat nobet",
"shift_kind": "duty24",
"start_time": "08:00",
"end_time": "08:00"
}
],
"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 physician availability using FHIR Slot statuses
GET /api/v1/health/physician-availability
Scope: health_scheduling:read
For every physician with a staff code, splits the selected days into gapless intervals: busy-unavailable (approved leave, duty or on-call), busy-tentative (leave awaiting approval), free. Leave type, diagnosis, notes and national ID numbers are never returned. People whose planning card or leave the key's role cannot see are not listed; if it can see neither, 403. The range is at most 31 days; boundaries use the tenant's time zone.
Parameters
| Field | Type | Description |
|---|---|---|
company_ (query) | string (uuid) | Only physicians of this company. |
employee_ (query) | string (uuid) | Only this physician. |
from (query) | string (date)required | First day (YYYY-MM-DD). |
to (query) | string (date)required | Last day (YYYY-MM-DD), at most 31 days with from. |
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 | |
company_ | string (uuid)required | |
staff_ | stringrequired | Staff code on the planning card. |
slots | object[]required | Intervals: start, end (UTC) and FHIR Slot status (free, busy-unavailable, busy-tentative). |
Example response
{
"data": [
{
"employee_id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"staff_code": "DR-0042",
"slots": [
{
"start": "2026-12-01T21:00:00.000Z",
"end": "2026-12-02T05:00:00.000Z",
"status": "free"
},
{
"start": "2026-12-02T05:00:00.000Z",
"end": "2026-12-03T05:00:00.000Z",
"status": "busy-unavailable"
},
{
"start": "2026-12-03T05:00:00.000Z",
"end": "2026-12-03T21:00:00.000Z",
"status": "busy-tentative"
}
]
}
],
"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