Book an appointment

POST /v1/appointments/book-appointment

The plain scheduled booking: one visit, one charge, paid at the clinic or already settled. If the visit involves a session pack — buying one, or spending one you already own — use book-appointment-unified instead. If the patient is about to pay online, use reserve-slot.

Identifying the patient

Send one of these. The first two are lookups; the third creates the record if it does not exist.

patientPayload accepts firstName, middleName, lastName, email, countryCode, phoneNumber, dob, age, gender, bloodGroup, mrnNumber and source. Blank strings are dropped rather than forwarded, so an empty dob: "" from a form is harmless. A sibling patientAddress object (addressLine1, city, state, country, zipcode, landmark, latitude, longitude, …) is attached to the patient when creating one.

Both objects are stripped before the booking itself — Medos books by patientId only.

Body

† Or the deprecated appointmentDate + fromDateTimeTs + toDateTimeTs (HH:mm) trio. That form has no timezone and has silently misbooked visits for non-Indian clinics — send the ISO pair.

Booking a follow-up

Send followUp: true. You do not name the visit being followed up — the gateway does:

1. It runs the patient-facing eligibility check for this patient, doctor, location, mode and date — the same strict rule the clinic's Self Check-in page applies.
2. If the patient has a qualifying visit, the booking goes through as a FOLLOW_UP linked to that visit, and Medos prices it from the doctor's follow-up policy.
3. If not, nothing is booked and you get a 400:

{ "success": false, "message": "FOLLOW_UP_NOT_ELIGIBLE", "reason": "NO_PARENT" }

reason is passed through from Medos when it gives one. Offer the patient an ordinary consultation instead.

A follow-up is always a single visit. It cannot be combined with a pack bookingType on the unified route.

Try it

{
  "addressId": "1",
  "doctorId": "4",
  "mode": "OFFLINE",
  "consultationCharge": "500",
  "paymentMode": "CASH"
}

Request

curl -sX POST "https://api.medos.one/v1/appointments/book-appointment" \
  -H "x-api-key: $MEDOS_API_KEY" \
  -H "x-end-user-id: $PATIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": 1,
    "addressId": 1,
    "doctorId": 4,
    "mode": "OFFLINE",
    "fromDateTimeIso": "2026-09-20T09:00:00+05:30",
    "toDateTimeIso": "2026-09-20T09:30:00+05:30",
    "consultationCharge": 500,
    "currency": "INR",
    "paymentMode": "CASH",
    "source": "DEVELOPER_API",
    "chiefComplaint": "Persistent cough for 3 days",
    "patientPayload": {
      "firstName": "Asha",
      "lastName": "Nair",
      "countryCode": "+91",
      "phoneNumber": "9876543210",
      "gender": "FEMALE"
    }
  }'

Response

The created appointment:

{
  "workspaceId": 1,
  "addressId": 1,
  "doctorId": 4,
  "patientId": 774,
  "mode": "OFFLINE",
  "appointmentDate": "2026-09-20",
  "fromDateTimeTs": "2026-09-20T09:00:00+05:30",
  "toDateTimeTs": "2026-09-20T09:30:00+05:30",
  "appointmentTimezone": "Asia/Kolkata",
  "fromTime": "09:00",
  "toTime": "09:30",
  "bookingReference": "MED-9182-AK",
  "consultationCharge": 500,
  "currency": "INR",
  "discountAmount": 0,
  "paymentStatus": "UNPAID",
  "paymentMode": "Cash",
  "paymentMethodName": "Cash",
  "bookingChannel": null,
  "videoMeetingUrl": null
}

Common failures

Next