> ## Documentation Index
> Fetch the complete documentation index at: https://developer.eka.care/llms.txt
> Use this file to discover all available pages before exploring further.

# List a patient's linked records

> List the facilities a patient has linked records with, then the care contexts under each one.

## 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](https://developer.eka.care/docs/hie-cm/workflows/hiu-request-consent.md) and [Receive and decrypt records as a HIU](https://developer.eka.care/docs/hie-cm/workflows/hiu-receive-data.md).

## Before you start

* A client access token, sent as a Bearer token. See [Authorization](https://developer.eka.care/api-sdk/auth/getting-started.md).
* 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](https://developer.eka.care/docs/hie-cm/workflows/login-abha.md). 
* A live ABHA gateway session, if these calls need one. See [Hold an ABHA gateway session](https://developer.eka.care/docs/hie-cm/workflows/hold-gateway-session.md). 
* At least one linked care context, from [Discover and link records from a facility](https://developer.eka.care/docs/hie-cm/workflows/phr-discover-and-link.md) or linked by a facility.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  App->>Eka: GET /abdm/v1/care-contexts/providers
  Eka-->>App: providers with hip_id and hip_name
  App->>Eka: GET /abdm/v1/care-contexts/linked
  Eka-->>App: care_contexts for one hip_id
```

## Steps

**1. List linked facilities**

Call [Get Linked Providers](https://developer.eka.care/api-sdk/hie-cm/care-contexts/providers/providers.md). 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](https://developer.eka.care/docs/hie-cm/workflows/phr-discover-and-link.md).

**2. 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](https://developer.eka.care/api-sdk/hie-cm/care-contexts/records/records.md). 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

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](https://developer.eka.care/docs/hie-cm/errors.md), 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](https://developer.eka.care/docs/hie-cm/errors.md). 

| 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](https://developer.eka.care/docs/hie-cm/workflows/hold-gateway-session.md), then repeat the call |
| Nothing linked under the ABHA address | [`ABDM-1012`](https://developer.eka.care/docs/hie-cm/errors), or an empty list | Offer discovery and linking |
| Server or gateway error | HTTP 5XX, for example [`ABDM-1019`](https://developer.eka.care/docs/hie-cm/errors) | Show the last list you have and retry later |

## Test it

The [testing page](https://developer.eka.care/docs/hie-cm/testing.md) 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](https://developer.eka.care/docs/hie-cm/workflows/phr-discover-and-link.md)
* [ ] 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.