Skip to main content

​
In short

  • Book an in-person visit in four calls: search doctors, search slots, Init, Confirm.
  • Each POST returns at once; its result arrives on a webhook or the matching GET.
  • Show the patient the pin from Confirm; they present it to the doctor.
  • Check, reschedule or cancel the booking later with its order_id.

​
When to use this

Your user wants to see a doctor in person and you book the visit for them over the Unified Health Interface (UHI). The workflow covers the whole booking: doctor search, slot search, initiate, confirm, then status, reschedule and cancel. Every step is asynchronous. A POST starts the request and returns identifiers at once. The result arrives on a webhook, and you can also read it with the matching GET.

​
Before you start

  • A Bearer token. Every UHI operation uses the authApiKey scheme. See Authorization.
  • The patient logged in on your app, with their Eka user id (oid) in hand to send as X-Pt-Id. See Log in to an existing ABHA.
  • A webhook endpoint registered with Eka that verifies Eka-Webhook-Signature. See Webhook signature.
  • The patient’s search criteria and the time window they are free, and their billing name, phone and address for the booking.

​
Sequence

​
Steps

Every POST in this workflow returns txn_id, provider_id and order_id. The spec describes txn_id and provider_id as the values for the next call. Every GET except Get Doctors takes the same three as query parameters; the spec gives Get Doctors none.
1

Search for doctors

Send the patient’s criteria to Search Doctors. start_time and end_time set the availability window. The reference page lists the optional filters, such as speciality, doctor, facility and location. Keep txn_id and provider_id from the response.
2

Read the doctor results

The doctor.search.results webhook carries the list. You can also read it from Get Doctors. If data is empty, widen the search and repeat step 1. The patient picks one doctor; keep that result’s hpr_id, facility_id and transaction_id.
3

Search the doctor's slots

Send hpr_id, facility_id, transaction_id, provider_id, start_time and end_time to Search Slots. All six are required. Keep txn_id, provider_id and order_id from the response.
4

Read the slots

The doctor.slot.search.results webhook carries doctor, provider_info and slots. You can also read them from Get Slots. Each slot has id, date, start_time, end_time, price and currency. If slots is empty, pick another window or doctor. The patient picks one slot.
5

Initiate the booking

Send Init these fields:
  • From the chosen slot: its id as slot_id, its start_time and end_time, and its price as price.value and price.currency.
  • The doctor’s doctor.id as doctor_id.
  • From the chosen doctor: facility_id.
  • provider_id, transaction_id, and the patient’s billing.
The spec describes transaction_id only as received in the previous API response. Keep txn_id, provider_id and order_id from the response.
6

Show the quote and terms

The booking.init webhook carries quote with total and breakup, terms, payment with status and type, and the order_id. You can also read them from Get Init. Show the total and the terms. The patient must accept the terms before you confirm.
7

Confirm the booking

Send provider_id and transaction_id from Init to Confirm. Keep txn_id, provider_id and order_id from the response.
8

Read the confirmation and PIN

The booking.confirm webhook carries order_id, pin, slot, doctor_info and state. You can also read them from Get Confirm. Show pin to the patient; they present it to the doctor before the consultation. Store order_id on the booking.
9

Check the booking status

Send order_id, provider_id and transaction_id to Order Status. The booking.status webhook carries the booking. You can also read it from Get Order Status.
10

Reschedule, if the patient asks

Send order_id, provider_id, transaction_id, facility_id and the new slot_id, start_time and end_time to Update. Get a new slot, for example by repeating steps 3 and 4.
11

Cancel, if the patient asks

Send order_id, provider_id and transaction_id to Cancel. The booking.cancel webhook carries status. You can also read it from Get Cancel. The spec gives SUCCESS, FAILED and PENDING as examples. Mark the booking cancelled only on SUCCESS.

​
State you must persist

​
When it fails

Which of these codes each call returns is not yet confirmed. The codes come from the errors page, matched by meaning. Log the code you actually receive.
Every UHI operation returns GenericError with code, error and source_error on a 4XX or 5XX. The spec lists no UHI-specific codes. See Errors.

​
Test it

The testing page has the sandbox base URL, credentials and the happy path for every journey.
  • Search doctors with a speciality and a seven-day window; receive doctor.search.results
  • Search slots for one result; receive doctor.slot.search.results with at least one slot
  • Init with that slot; receive booking.init with a quote and terms
  • Confirm; receive booking.confirm with a pin and order_id
  • Order Status; receive booking.status with the same order_id
  • Update to another slot, then check Order Status shows the new slot
  • Cancel; receive booking.cancel with SUCCESS
  • Failure: a search that matches nothing returns empty data
  • Failure: Search Slots without hpr_id returns a 4XX