Server-side APIEndpointsReference data

A practitioner's slots

One practitioner's open and taken slots at one of your locations on one day.

One practitioner's slot grid at one of your clinic's locations on one day: the slots still open, and the ones that are not, with why. Use it for availability boards, front-desk screens and scheduling displays in your own system.

API-key only, gated on devapi_appointments_available_slots. The workspace is implicit: there is no workspaceId parameter.

Availability, not booking

This route is read-only. The Developer API does not book appointments. Booking runs in the widgets, on a patient's own verified session. A slot shown open here can be taken a moment later, so do not treat it as reserved.

Parameters

Path parameters

doctorIdstringrequiredExample: MDU_A1B2C3D4E5F6

The practitioner's MDU_… staff id, from GET /v1/doctors. Lower case is accepted.

Query parameters

addressIdintegerrequiredExample: 1

One of your clinic's locations, from GET /v1/addresses.

datedaterequiredExample: 2026-11-20

The day to show, in the location's own calendar.

mode"ONLINE" | "OFFLINE" | "HOME_VISIT" | "HOME_COLLECTION"enum

Only slots for this consultation mode.

durationMinsintegermin: 1

Run the grid at this consultation length. Defaults to the practitioner's own.

Headers

x-api-keystringrequiredExample: mk_…

Your Developer API key. Server-side only.

X-Acting-User-IdstringExample: MDU_A1B2C3D4E5F6

The staff member the call is attributed to, as an MDU_… id. Omit it to attribute the call to the workspace admin.

Both ids are the ones you were given at onboarding:

  • doctorId is the practitioner's public staff id, MDU_ followed by 12 of [A-Z0-9]: the id from GET /v1/doctors and the practitioner.id on every record. An internal numeric id is refused. An id your clinic does not know and another clinic's id get the same 400.
  • addressId is one of your locations, from GET /v1/addresses. The request is always answered from your own workspace's schedules, so an address that is not one of your locations finds no schedule and returns an empty grid.
  • date is a calendar day in the location's own timezone, YYYY-MM-DD.

addressId and date are required. When either is missing, errors[] names it, and a request with several problems names all of them at once.

Responses

  • slots are the windows still open. unavailable are the windows on the same grid that cannot be offered, with status saying why: BOOKED (a Medos appointment holds it), BLOCKED (busy on the practitioner's own calendar) or PAST (already over today). It never says whose appointment.
  • Times are ISO-8601 with the location's offset, and timezone names the location's IANA zone. Show them as given; do not reinterpret them in your server's zone. On a day with no slots at all, timezone is null.
  • durationMins is the length the grid runs at. availableDurations lists every length the practitioner offers, and durationMins in the query picks one.
  • nextAvailableDate is the next day with an open slot, when this one has none. An empty day is a 200 with empty lists, not an error. If every day comes back empty, check the addressId against GET /v1/addresses and that the practitioner works there.

Prices, consultation plans and session packs are not returned.

Caching

Cache-Control: no-store, because a grid changes every time anyone books. Send the ETag back as If-None-Match to get a 304 when nothing has moved. See Polling and caching.

Test request