Book an appointment
Pass `slotToken` or `holdId`, and `patientRef` (from /patients/lookup) or `patient`. **202** means the outcome is not yet known: the body carries an `operationId` — poll GET /scheduling/booking-operations/{operationId} and do NOT re-POST, which risks a second appointment. `idempotencyKey` is optional and exists for retries: reusing a key MUST repeat the identical request — a different body under a used key is refused with `SCHEDULING_IDEMPOTENCY_MISMATCH` (409) and books nothing. Booking with a `holdId` REQUIRES the same `X-Mediflo-Scheduling-Session` value you created the hold with: a hold belongs to the request that made it, so without the header this request is a different owner and the booking answers `SLOT_TAKEN` on the slot you are holding. Booking straight from a `slotToken` needs no hold and no header. Required scope: `scheduling.book`.
/scheduling/appointmentsAuthorization
ApiKeyAuth An external API key, sent as Authorization: Bearer mflo_…. Scopes are checked per route; see each operation’s description.
In: header
Header Parameters
Your own id for ONE booking flow (letters, digits and ._:-, 1–128 chars). REQUIRED to use a hold: send the SAME value on POST /scheduling/holds, on the POST /scheduling/appointments that consumes the hold, and on DELETE /scheduling/holds/{holdId}. Without this header every request is its own owner and cannot touch another request’s hold — booking a holdId then answers SLOT_TAKEN and the hold can only expire. Booking straight from a slotToken needs no hold and no header.
^[A-Za-z0-9._:-]{1,128}$Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/scheduling/appointments" \ -H "Content-Type: application/json" \ -d '{}'{ "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "start": "string", "startIso": "string", "spokenLabel": "string", "specialist": "string", "appointmentType": "string", "durationMin": 0, "price": "string", "location": { "name": "string", "address": "string" }, "instructions": "string", "status": "string", "contactId": "b5ec5d98-4bee-4da1-ad24-dde86346cb1d" }}Upcoming appointments for a phone number POST
Reads only — a POST because the phone number belongs in a body, not in a URL that logs keep. Each entry carries an `actionToken` — the handle the `scheduling.modify` endpoints require — and the patient’s masked name. Required scope: `scheduling.read`.
Ask the clinic to call the patient back POST
Filing a contact request books nothing, so it sits on the read scope: an integration that may only browse can still escalate to a human. Required scope: `scheduling.read`.