List a patient's linked records - Eka Developer Platform APIs

In short

Listing takes two calls: linked facilities first, then one facility’s care contexts.
Each care context’s status shows where it is in the consent and data flow.
This lists metadata only; reading a record needs consent and a data transfer.

When to use this

Your PHR app shows the patient what is linked to their ABHA. An ABHA address can carry thousands of care contexts across many facilities. So listing takes two calls: the facilities first, then the care contexts under the one the patient opens. This lists metadata only. Reading a record’s contents needs the patient’s consent and a data transfer. See Request a patient’s consent as a HIU and Receive and decrypt records as a HIU.

Before you start

A client access token, sent as a Bearer token. See Authorization.
The patient’s Eka user id (oid), sent as the X-Pt-Id header or the oid query parameter. It comes from ABHA creation or Log in to an existing ABHA.
A live ABHA gateway session, if these calls need one. See Hold an ABHA gateway session.
At least one linked care context, from Discover and link records from a facility or linked by a facility.

Sequence

Steps

List linked facilities

Call Get Linked Providers. The response carries providers, each with hip_id and hip_name. Show the list. If providers is empty or null, the patient has nothing linked yet; offer Discover and link records from a facility.

List care contexts for one facility

When the patient opens a facility, send its hip_id as the required hip_id query parameter to Get Linked CareContexts. The response carries care_contexts, each with care_context_id, display, created_at and status.status is one of ConsentRaised, ConsentGranted, ConsentError, DataRequested, DataReceived, DataProcessing, DataProcessed, InvalidDataReceived or NoDataAvailable. Use it to show where each record is in the consent and data flow.

State you must persist

Field	From	Keep	For
`oid`	ABHA creation or login	On the patient record, for as long as the patient uses your app	`X-Pt-Id` or `oid` on both calls
`hip_id`	Get Linked Providers	For the screen, or cached on the patient record	Get Linked CareContexts
`care_context_id`	Get Linked CareContexts	On the patient record	Matching consent requests and received data to the record

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. Codes are on the errors page.

Situation	Code	Do
`hip_id` missing from Get Linked CareContexts	HTTP 4XX	Send the `hip_id` from Get Linked Providers
Patient’s gateway session expired	HTTP `491`	Run Hold an ABHA gateway session, then repeat the call
Nothing linked under the ABHA address	`ABDM-1012`, or an empty list	Offer discovery and linking
Server or gateway error	HTTP 5XX, for example `ABDM-1019`	Show the last list you have and retry later

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.

Link one care context with Discover and link records from a facility
Get Linked Providers returns that facility’s hip_id
Get Linked CareContexts with that hip_id returns the care context with a status
Get Linked CareContexts without hip_id fails with a 4XX
A patient with nothing linked gets an empty list or ABDM-1012, and the app offers discovery. Record the code you receive; the expected code is not confirmed.

​In short

​When to use this

​Before you start

​Sequence

​Steps

​State you must persist

​When it fails

​Test it

In short

When to use this

Before you start

Sequence

Steps

State you must persist

When it fails

Test it