Skip to content

Health

Health endpoints: parameters, fields and example responses.

Developer documentation

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

health.duty_roster.list: Parameters
FieldTypeDescription
company_id (query)string (uuid)requiredCompany. If it is outside the key's scope the list is empty.
employee_id (query)string (uuid)Only this employee.
from (query)string (date)requiredFirst day (YYYY-MM-DD).
org_unit_id (query)string (uuid)Only people in this unit (their current unit).
to (query)string (date)requiredLast day (YYYY-MM-DD), at most 31 days with from.
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.

health.duty_roster.list: Each item in the list (data[])
FieldTypeDescription
idstring (uuid)required
company_idstring (uuid)required
employee_idstring (uuid)required
staff_codestringrequirednullableStaff code on the planning card (the organisation's own code); null if the role cannot see planning cards.
first_namestringrequired
last_namestringrequired
job_titlestringrequirednullable
unitstringrequirednullableThe person's current unit.
datestring (date)requiredDay the assignment starts.
shift_codestringrequired
shift_namestringrequired
shift_kindstringrequiredduty24: 24-hour duty, on_call, normal, flexible, half. Values: normal, duty24, on_call, flexible, half
start_timestringrequired
end_timestringrequiredEnd 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_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 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

health.physician_availability.list: Parameters
FieldTypeDescription
company_id (query)string (uuid)Only physicians of this company.
employee_id (query)string (uuid)Only this physician.
from (query)string (date)requiredFirst day (YYYY-MM-DD).
to (query)string (date)requiredLast day (YYYY-MM-DD), at most 31 days with from.
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.

health.physician_availability.list: Each item in the list (data[])
FieldTypeDescription
employee_idstring (uuid)required
company_idstring (uuid)required
staff_codestringrequiredStaff code on the planning card.
slotsobject[]requiredIntervals: 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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: timeout

Writes physician performance premiums

POST /api/v1/health/physician-premiums

Scope: health_premiums:write

Same rules as the HBYS premium file on Health › Duty pay: employee id or staff code, month, amount (TRY) and an optional pay item. The same employee, month and pay item is written once per company; a row for a month whose payroll is approved is an error. If any row is invalid nothing is written and errors are returned with row numbers. Idempotency-Key is required. The response is a summary of the batch; amounts and people are not in it. Transfer to payroll is done on screen.

Parameters

health.physician_premiums.create: Parameters
FieldTypeDescription
Idempotency-Key (header)stringrequiredUnique key of the request (a UUID is recommended). A repeated request with the same key and body returns the current state of the resource and Idempotent-Replayed: true; the window is 24 hours.

Request body

health.physician_premiums.create: Request body
FieldTypeDescription
company_idstring (uuid)requiredCompany. The key's write scope must cover the whole company.
rowsobject[]requiredRows (1-500).

Responses

201 Created

health.physician_premiums.create: Responses
FieldTypeDescription
idstring (uuid)required
company_idstring (uuid)required
statusstringrequiredapplied: written; undone: rolled back on screen. Values: applied, undone
rowsintegerrequiredNumber of rows written.
created_atstring (date-time)required
Example response
{
  "id": "9e8d7c6b-5a49-4382-a716-f5e4d3c2b1a0",
  "company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
  "status": "applied",
  "rows": 2,
  "created_at": "2026-12-05T09: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
  • 409: idempotency_in_progress, conflict
  • 413: payload_too_large
  • 415: unsupported_media_type
  • 422: idempotency_key_reused
  • 429: rate_limited
  • 500: internal_error
  • 503: timeout