Skip to main content

​
In short

  • Find the facility, discover its unlinked care contexts, then link them with an OTP.
  • The facility sends the link OTP to the patient’s registered mobile.
  • An empty patient list means the facility found nothing; retry with a ref_id.
  • Each call takes the txn_id from the call before it.

​
When to use this

The patient uses your PHR app to claim records that a facility holds against them but never linked to their ABHA. You search for the facility and ask it for unlinked care contexts. The patient picks the ones to link and enters an OTP the facility sends. This is the PHR side of discovery. If your software is the facility answering these requests, use Answer discovery and link old records instead.

​
Before you start

​
Sequence

​
Steps

1

Find the facility

If the patient searches by name, call Search Providers with name, at least three characters. The response is a list of facilities, each with hip_id, hip_name, city and state. Show the list and keep the hip_id the patient picks.If you already hold a hip_id, for example from an earlier link, call Get Provider Details with it instead. It returns the same four fields for that one facility.
2

Discover unlinked care contexts

Send hip_id to Discover unlinked care-contexts. Add ref_id if the patient knows the identifier the facility holds for them, such as a registration number or the phone number they gave there. The facility matches the patient’s verified ABHA identifiers against its records.The response carries txn_id and a patient list. Each patient entry has an id, a display name and care_contexts, each with its own id and display. Keep txn_id and both ids. If patient is empty or null, the facility found nothing: let the patient retry with a ref_id, or pick another facility.
3

Start linking

Send txn_id from Discover, patient_ref_id and cc_ref_id to Initialise Linking. The facility sends an OTP to the patient’s registered mobile. Keep the new txn_id from the response.
4

Confirm with the OTP

Send txn_id from Link Init and the otp the patient enters to Confirm Linking. The response carries cc_ref_id, the care context now linked to the patient’s ABHA. It appears under the facility in List a patient’s linked records.

​
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.
Errors come back as HTTP 4XX or 5XX with a GenericError body: code, error and source_error. The codes below are from the errors page.

​
Test it

The testing page has the sandbox base URL, credentials and the happy path for every journey. Run against the Stage/Sandbox server, https://api.dev.eka.care.
  • Search Providers with a three-character name returns the sandbox facility
  • Discover with its hip_id returns a txn_id and at least one care context
  • Link Init with that care context returns a new txn_id
  • Link Confirm with the OTP returns cc_ref_id
  • The facility and care context appear in List a patient’s linked records
  • Wrong OTP once, then the correct OTP
  • Link Confirm with a stale txn_id fails, and a fresh Discover recovers