Skip to main content

​
Scheduling

Administer your organisation’s scheduling configuration with an API key instead of the admin interface. You can list and cancel scheduled appointments, manage appointment types and their reminders, and configure each doctor’s recurring availability rules. All endpoints are scoped to the organisation that owns the API key. UIDs that belong to another organisation are treated as not found.

​
Permissions

Scheduling endpoints are gated by two permissions:
  • scheduling:read — required for all read (GET) endpoints.
  • scheduling:admin — required for all write endpoints (POST, PATCH, DELETE).
A key with scheduling:admin is not automatically granted scheduling:read; add both if you need to read and write. Contact your RxScale account manager to adjust permissions. All requests authenticate with the X-API-Key header. See Authentication for details.

​
Appointments

​
List Appointments

GET /v1/management/scheduling/appointments
Returns a paginated list of scheduled appointments for the organisation. Required permission: scheduling:read
​
page
integer
default:"0"
Page number (0-indexed)
​
limit
integer
default:"50"
Number of appointments per page
​
doctor_uid
string
Filter appointments by doctor UID
​
patient_uid
string
Filter appointments by patient UID
​
status
string
Filter by appointment status. One of held, confirmed, cancelled, expired, completed, no_show, or all. When omitted, the default server-side filtering applies.
​
from
integer
Filter appointments starting at or after this Unix timestamp
​
to
integer
Filter appointments starting at or before this Unix timestamp. Must be greater than from when both are supplied.

​
Example Request

curl -X GET "https://api.rxscale.com/v1/management/scheduling/appointments?page=0&limit=25&status=confirmed" \
  -H "X-API-Key: your-api-key-here"

​
Response

{
  "data": [
    {
      "uid": "mtg-abc123",
      "status": "confirmed",
      "doctor_uid": "doc-456",
      "doctor_display_name": "Dr. Schmidt",
      "patient_uid": "pat-789",
      "patient_display_name": "Jane Doe",
      "appointment_type_uid": "apt-001",
      "appointment_type_name": "Initial consultation",
      "meeting_type": "CONSULTATION",
      "meeting_format": "DIGITAL",
      "start_date": 1712300000,
      "end_date": 1712301800,
      "created_at": 1712200000,
      "cancelled_at": null,
      "cancellation_reason": null
    }
  ],
  "totalRegistries": 42,
  "totalPages": 2
}

​
Response Fields

FieldTypeDescription
data[].uidstringScheduled meeting UID
data[].statusstringAppointment status (held, confirmed, cancelled, expired, completed, no_show)
data[].doctor_uidstringDoctor UID
data[].doctor_display_namestringDoctor display name
data[].patient_uidstringPatient UID
data[].patient_display_namestringPatient display name
data[].appointment_type_uidstring | nullAppointment type UID, if any
data[].appointment_type_namestring | nullAppointment type name, if any
data[].meeting_typestringMeeting type (e.g. CONSULTATION, FOLLOW_UP, INITIAL, REVIEW, ON_DEMAND)
data[].meeting_formatstringMeeting format (DIGITAL, IN_PERSON)
data[].start_dateintegerStart time (Unix timestamp)
data[].end_dateintegerEnd time (Unix timestamp)
data[].created_atintegerCreation timestamp (Unix)
data[].cancelled_atinteger | nullCancellation timestamp (Unix), if cancelled
data[].cancellation_reasonstring | nullReason supplied at cancellation, if cancelled
totalRegistriesintegerTotal number of appointments matching the filter
totalPagesintegerTotal number of pages

​
Cancel an Appointment

POST /v1/management/scheduling/appointments/{meeting_uid}/cancel
Cancels a scheduled appointment and records the supplied reason. Required permission: scheduling:admin
​
meeting_uid
string
required
The scheduled meeting UID
​
reason
string
required
Reason for cancelling the appointment (must not be empty)

​
Example Request

curl -X POST "https://api.rxscale.com/v1/management/scheduling/appointments/mtg-abc123/cancel" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Patient requested cancellation"
  }'

​
Response

{
  "appointment_uid": "mtg-abc123",
  "status": "cancelled",
  "cancelled_at": 1712250000,
  "cancellation_reason": "Patient requested cancellation"
}

​
Appointment Types

An appointment type defines a bookable kind of meeting (duration, hold behaviour, room and rebooking strategy).

​
List Appointment Types

GET /v1/management/scheduling/appointment-types
Required permission: scheduling:read

​
Example Request

curl -X GET "https://api.rxscale.com/v1/management/scheduling/appointment-types" \
  -H "X-API-Key: your-api-key-here"

​
Response

{
  "data": [
    {
      "uid": "apt-001",
      "organisation_uid": "org-123",
      "name": "Initial consultation",
      "meeting_type": "CONSULTATION",
      "duration_minutes": 30,
      "hold_ttl_seconds": 900,
      "booking_min_notice_minutes": 10,
      "cancellation_min_notice_minutes": 60,
      "rebooking_min_notice_minutes": 120,
      "room_strategy": "persistent_per_provider",
      "rebooking_mode": "same_doctor_only",
      "doctor_assignment_mode": "all_available_doctors",
      "allow_patient_rebooking": true,
      "active": true,
      "created_at": 1712100000,
      "updated_at": 1712100000
    }
  ]
}

​
Create an Appointment Type

POST /v1/management/scheduling/appointment-types
Required permission: scheduling:admin
​
name
string
required
Display name (1–255 characters)
​
meeting_type
string
required
Meeting type. One of CONSULTATION, FOLLOW_UP, INITIAL, REVIEW, ON_DEMAND.
​
duration_minutes
integer
required
Appointment duration in minutes (1–1440)
​
hold_ttl_seconds
integer
required
How long a tentative hold survives before expiring, in seconds (1–86400)
​
booking_min_notice_minutes
integer
default:"0"
Default minimum notice required before patients can book this appointment type, in minutes. Doctor-specific settings can override this value.
​
cancellation_min_notice_minutes
integer
default:"0"
Minimum notice required to cancel, in minutes (≥ 0)
​
rebooking_min_notice_minutes
integer
default:"0"
Minimum notice required to rebook, in minutes (≥ 0)
​
room_strategy
string
required
Room allocation strategy. One of persistent_per_provider, per_appointment.
​
rebooking_mode
string
required
Rebooking mode. One of same_doctor_only, any_doctor_same_organisation.
​
doctor_assignment_mode
string
default:"all_available_doctors"
Controls which doctors can offer this appointment type. Use all_available_doctors to include every doctor with availability, or selected_doctors_only to require an active doctor-specific setting.
​
allow_patient_rebooking
boolean
default:"false"
Whether patients may rebook their own appointments of this type
​
active
boolean
default:"true"
Whether the appointment type is bookable

​
Example Request

curl -X POST "https://api.rxscale.com/v1/management/scheduling/appointment-types" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Initial consultation",
    "meeting_type": "CONSULTATION",
    "duration_minutes": 30,
    "hold_ttl_seconds": 900,
    "booking_min_notice_minutes": 10,
    "cancellation_min_notice_minutes": 60,
    "rebooking_min_notice_minutes": 120,
    "room_strategy": "persistent_per_provider",
    "rebooking_mode": "same_doctor_only",
    "doctor_assignment_mode": "all_available_doctors",
    "allow_patient_rebooking": true,
    "active": true
  }'
Returns 201 Created with the created appointment type (same shape as a list entry).

​
Update an Appointment Type

PATCH /v1/management/scheduling/appointment-types/{appointment_type_uid}
Partial update — only the fields you send are changed. All body fields are optional and accept the same values and ranges as on create. Required permission: scheduling:admin
​
appointment_type_uid
string
required
The appointment type UID
​
name
string
Display name (1–255 characters)
​
meeting_type
string
One of CONSULTATION, FOLLOW_UP, INITIAL, REVIEW, ON_DEMAND
​
duration_minutes
integer
Appointment duration in minutes (1–1440)
​
hold_ttl_seconds
integer
Hold lifetime in seconds (1–86400)
​
booking_min_notice_minutes
integer
Default minimum booking notice in minutes (≥ 0)
​
cancellation_min_notice_minutes
integer
Minimum cancellation notice in minutes (≥ 0)
​
rebooking_min_notice_minutes
integer
Minimum rebooking notice in minutes (≥ 0)
​
room_strategy
string
One of persistent_per_provider, per_appointment
​
rebooking_mode
string
One of same_doctor_only, any_doctor_same_organisation
​
doctor_assignment_mode
string
One of all_available_doctors, selected_doctors_only
​
allow_patient_rebooking
boolean
Whether patients may rebook their own appointments of this type
​
active
boolean
Whether the appointment type is bookable

​
Example Request

curl -X PATCH "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "duration_minutes": 45,
    "active": false
  }'
Returns 200 OK with the updated appointment type.

​
Delete an Appointment Type

DELETE /v1/management/scheduling/appointment-types/{appointment_type_uid}
Required permission: scheduling:admin
​
appointment_type_uid
string
required
The appointment type UID

​
Example Request

curl -X DELETE "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001" \
  -H "X-API-Key: your-api-key-here"
Returns 204 No Content on success.

​
Reminders

Reminders are configured per appointment type and notify a recipient role a fixed number of minutes before the appointment starts.

​
List Reminders

GET /v1/management/scheduling/appointment-types/{appointment_type_uid}/reminders
Required permission: scheduling:read
​
appointment_type_uid
string
required
The appointment type UID

​
Example Request

curl -X GET "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001/reminders" \
  -H "X-API-Key: your-api-key-here"

​
Response

{
  "data": [
    {
      "uid": "rem-001",
      "appointment_type_uid": "apt-001",
      "recipient_role": "patient",
      "minutes_before": 1440,
      "send_email": true,
      "send_sms": false,
      "active": true
    }
  ]
}

​
Response Fields

FieldTypeDescription
data[].uidstringReminder UID
data[].appointment_type_uidstringParent appointment type UID
data[].recipient_rolestringWho is notified (patient, doctor, admin)
data[].minutes_beforeintegerMinutes before the appointment to send
data[].send_emailbooleanWhether to send an email
data[].send_smsbooleanWhether to send an SMS
data[].activebooleanWhether the reminder is active

​
Create a Reminder

POST /v1/management/scheduling/appointment-types/{appointment_type_uid}/reminders
Required permission: scheduling:admin
​
appointment_type_uid
string
required
The appointment type UID
​
recipient_role
string
required
Who is notified. One of patient, doctor, admin.
​
minutes_before
integer
required
Minutes before the appointment to send the reminder (1–86400, i.e. up to 60 days)
​
send_email
boolean
default:"false"
Whether to send an email
​
send_sms
boolean
default:"false"
Whether to send an SMS
​
active
boolean
default:"true"
Whether the reminder is active

​
Example Request

curl -X POST "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001/reminders" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_role": "patient",
    "minutes_before": 1440,
    "send_email": true,
    "send_sms": false,
    "active": true
  }'
Returns 201 Created with the created reminder (same shape as a list entry).

​
Update a Reminder

PATCH /v1/management/scheduling/appointment-types/{appointment_type_uid}/reminders/{reminder_uid}
Partial update — only the fields you send are changed. Required permission: scheduling:admin
​
appointment_type_uid
string
required
The appointment type UID
​
reminder_uid
string
required
The reminder UID
​
recipient_role
string
One of patient, doctor, admin
​
minutes_before
integer
Minutes before the appointment to send the reminder (1–86400)
​
send_email
boolean
Whether to send an email
​
send_sms
boolean
Whether to send an SMS
​
active
boolean
Whether the reminder is active

​
Example Request

curl -X PATCH "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001/reminders/rem-001" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "minutes_before": 60,
    "send_sms": true
  }'
Returns 200 OK with the updated reminder.

​
Delete a Reminder

DELETE /v1/management/scheduling/appointment-types/{appointment_type_uid}/reminders/{reminder_uid}
Required permission: scheduling:admin
​
appointment_type_uid
string
required
The appointment type UID
​
reminder_uid
string
required
The reminder UID

​
Example Request

curl -X DELETE "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001/reminders/rem-001" \
  -H "X-API-Key: your-api-key-here"
Returns 204 No Content on success.

​
Availability Rules

Availability rules define a doctor’s recurring weekly bookable windows. Times are expressed as minutes from midnight (for example, 540 is 09:00 and 1020 is 17:00).

​
List Availability Rules

GET /v1/management/scheduling/doctors/{doctor_uid}/availability-rules
Required permission: scheduling:read
​
doctor_uid
string
required
The doctor UID

​
Example Request

curl -X GET "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-rules" \
  -H "X-API-Key: your-api-key-here"

​
Response

{
  "data": [
    {
      "uid": "rule-001",
      "doctor_uid": "doc-456",
      "weekday": 0,
      "start_time": 540,
      "end_time": 1020,
      "buffer_minutes": 10,
      "valid_from": null,
      "valid_until": null,
      "active": true
    }
  ]
}

​
Response Fields

FieldTypeDescription
data[].uidstringAvailability rule UID
data[].doctor_uidstringDoctor UID
data[].weekdayintegerDay of week (0 = Monday … 6 = Sunday)
data[].start_timeintegerStart of the window, in minutes from midnight (0–1440)
data[].end_timeintegerEnd of the window, in minutes from midnight (0–1440)
data[].buffer_minutesintegerBuffer between appointments, in minutes
data[].valid_frominteger | nullOptional start of validity (Unix timestamp)
data[].valid_untilinteger | nullOptional end of validity (Unix timestamp)
data[].activebooleanWhether the rule is active

​
Create an Availability Rule

POST /v1/management/scheduling/doctors/{doctor_uid}/availability-rules
Required permission: scheduling:admin
​
doctor_uid
string
required
The doctor UID
​
weekday
integer
required
Day of week (0 = Monday … 6 = Sunday)
​
start_time
integer
required
Start of the window, in minutes from midnight (0–1440)
​
end_time
integer
required
End of the window, in minutes from midnight (0–1440)
​
buffer_minutes
integer
default:"0"
Buffer between appointments, in minutes (≥ 0)
​
valid_from
integer
Optional start of validity (Unix timestamp)
​
valid_until
integer
Optional end of validity (Unix timestamp)
​
active
boolean
default:"true"
Whether the rule is active

​
Example Request

curl -X POST "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-rules" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "weekday": 0,
    "start_time": 540,
    "end_time": 1020,
    "buffer_minutes": 10,
    "active": true
  }'
Returns 201 Created with the created availability rule (same shape as a list entry).

​
Update an Availability Rule

PATCH /v1/management/scheduling/doctors/{doctor_uid}/availability-rules/{rule_uid}
Partial update — only the fields you send are changed. To remove an existing validity bound, send the corresponding clear_* flag rather than a value. Required permission: scheduling:admin
​
doctor_uid
string
required
The doctor UID
​
rule_uid
string
required
The availability rule UID
​
weekday
integer
Day of week (0 = Monday … 6 = Sunday)
​
start_time
integer
Start of the window, in minutes from midnight (0–1440)
​
end_time
integer
End of the window, in minutes from midnight (0–1440)
​
buffer_minutes
integer
Buffer between appointments, in minutes (≥ 0)
​
valid_from
integer
Set the start of validity (Unix timestamp)
​
valid_until
integer
Set the end of validity (Unix timestamp)
​
active
boolean
Whether the rule is active
​
clear_valid_from
boolean
default:"false"
Clear the existing valid_from bound (set it to null)
​
clear_valid_until
boolean
default:"false"
Clear the existing valid_until bound (set it to null)

​
Example Request

curl -X PATCH "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-rules/rule-001" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "end_time": 960,
    "clear_valid_until": true
  }'
Returns 200 OK with the updated availability rule.

​
Delete an Availability Rule

DELETE /v1/management/scheduling/doctors/{doctor_uid}/availability-rules/{rule_uid}
Required permission: scheduling:admin
​
doctor_uid
string
required
The doctor UID
​
rule_uid
string
required
The availability rule UID

​
Example Request

curl -X DELETE "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-rules/rule-001" \
  -H "X-API-Key: your-api-key-here"
Returns 204 No Content on success.