Skip to main content

​
In short

  • You answer three Eka webhooks in turn, each with one call back to Eka.
  • First return the patient’s unlinked records, then send an OTP by SMS.
  • When the OTP matches, call On Link Confirm and ABDM links the records.

​
When to use this

A patient searches for their records at your facility from a PHR app, such as the ABHA app. The records exist in your system but were never linked to their ABHA. You answer three webhooks in turn:
  1. You return the matching records.
  2. You send the patient an OTP.
  3. You confirm the link once the OTP checks out.

​
Before you start

  • A client access token, sent as a Bearer token. See Authorization.
  • Your facility onboarded as a Health Information Provider (HIP), with its HIP ID. ABDM routes discovery requests by HIP ID.
  • A webhook URL registered with Eka that can receive the three discovery events, and the means to verify the webhook signature. Acknowledge each event as described in Webhooks.
  • A patient search in your system by mobile number, name, gender and year of birth.
  • A way to generate an OTP and send it by SMS to the patient’s registered mobile number. You send this OTP yourself.

​
Sequence

​
Steps

1

Answer the discovery request

Eka sends the abha.care_context_discover webhook.From data, read abha_address, patient_name, gender, year_of_birth and the identifiers list (MOBILE, ABHA_NUMBER, abhaAddress). Keep request_id and txn_id.Search your system with these identifiers. Collect the care contexts for this patient that are not yet linked: visits, prescriptions, lab reports.Call On Discover with request_id and txn_id from the webhook, and patients. Each entry carries:
  • ref_num: your patient reference number
  • display: a display name
  • hi_type
  • care_contexts, each with ref_num and display
If you find no match, send error with code and message instead of patients. The call returns 204 No Content.You may save abha_address to the matched patient’s record. ABDM leaves that to you. Saving it lets you link future records directly.
2

Send the OTP and report it

When the patient selects records to link, Eka sends the abha.care_context_discover_link_init webhook.From data, read patient: each entry carries ref_num, hi_type, count and care_contexts (each with reference_number). Save these as the care contexts to link. Keep request_id and txn_id.Generate an OTP and send it to the patient’s registered mobile number. Record when it expires.Call On Link Init with request_id and txn_id from this webhook, the patient’s ref_num, and otp_expiry. If you cannot send the OTP, send error instead. The call returns 204 No Content.
3

Verify the OTP and confirm the link

When the patient enters the OTP in the PHR app, Eka sends the abha.context_discover_link_confirm webhook.From data, read token (the OTP the patient entered), linkRefNumber, request_id and hip_id. Find the pending link from step 2 and compare token with the OTP you generated. Check it has not expired.If the OTP is valid, call On Link Confirm with request_id from this webhook. Send patients: the care contexts to link, in the same shape as on-discover. ABDM then registers the link under the patient’s ABHA, against the HIP in hip_id. Mark those care contexts as linked in your system. The call returns 204 No Content.If the OTP is wrong or expired, call On Link Confirm with error instead of patients.
Once linked, if you keep their data yourself, see Serve records on a fetch request.

​
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.
Error responses carry code, error and source_error.

​
Test it

The testing page has the sandbox base URL, credentials and the happy path for every journey.
  • Create a test patient in your system with an unlinked visit. Use the same mobile, name, gender and year of birth as a sandbox ABHA
  • Discover your HIP from a sandbox PHR app; receive abha.care_context_discover and reply with the visit
  • Select the visit; receive abha.care_context_discover_link_init, send the OTP, reply with on-init
  • Enter the OTP; receive abha.context_discover_link_confirm, reply with on-confirm, and see the record linked in the PHR app
  • Discover with an ABHA that matches no patient and reply with error
  • Enter a wrong OTP and reply with error