Book (unified)

POST /v1/appointments/book-appointment-unified

The canonical write path. It books the same scheduled visit as book-appointment, but adds the two things that route cannot express — buying a session pack in the same transaction, and drawing a visit from a pack the patient already owns — and can route the booking into the queue system instead of the calendar.

Which booking type

bookingType is required for scheduled bookings and decides what else you must send.

packageConfigId comes from the pack catalog; patientPackageId comes from the patient's active packs on search-by-phone or from plans[] on available slots.

Body

Patient identification works exactly as on book-appointment: patientId, patientPayload.id, or a patientPayload object to find-or-create.

Try it

{
  "addressId": "1",
  "doctorId": "4",
  "bookingType": "CONSULTATION",
  "mode": "OFFLINE",
  "paymentMode": "CASH"
}

Request

A pack purchase that also books the first session:

curl -sX POST "https://api.medos.one/v1/appointments/book-appointment-unified" \
  -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,
    "patientId": 774,
    "system": "SCHEDULED",
    "bookingType": "PACKAGE_PURCHASE",
    "packageConfigId": 12,
    "packageAmount": 4500,
    "currency": "INR",
    "mode": "OFFLINE",
    "fromDateTimeIso": "2026-09-20T09:00:00+05:30",
    "toDateTimeIso": "2026-09-20T09:30:00+05:30",
    "paymentMode": "UPI",
    "paymentStatus": "PAID",
    "paymentReference": "txn_88213",
    "source": "DEVELOPER_API"
  }'

Response

A discriminated result — system says which half is populated:

{
  "system": "SCHEDULED",
  "appointment": {
    "workspaceId": 1,
    "patientId": 774,
    "bookingReference": "MED-9182-AK",
    "appointmentDate": "2026-09-20",
    "fromDateTimeTs": "2026-09-20T09:00:00+05:30",
    "toDateTimeTs": "2026-09-20T09:30:00+05:30",
    "appointmentTimezone": "Asia/Kolkata",
    "consultationCharge": 0,
    "currency": "INR",
    "paymentStatus": "PAID"
  },
  "visit": null
}

appointment is the same payload book-appointment returns. For system: "QMS" it is visit that is populated instead, carrying tokenNumber, tokenDisplay, position and publicStatusToken.

Booking into the queue

Set system: "QMS" and nest the queue booking under qms. The top-level workspaceId, addressId, doctorId and patientId are copied down for you, so the nested object carries only the queue-specific fields — qmsWorkShiftId, appointmentDate, mode and bookingChannel at minimum.

In practice, prefer the dedicated routes: they take the same fields flat, and they are what the queue documentation describes.

Common failures