> ## 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.

# Discover and link records from a facility

> Find a facility, ask it for the patient's unlinked care contexts, and link the ones the patient picks with an OTP.

## 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](https://developer.eka.care/docs/hie-cm/workflows/hip-discovery-and-link.md) instead.

## Before you start

* A client access token, sent as a Bearer token. See [Authorization](https://developer.eka.care/api-sdk/auth/getting-started.md).
* A logged-in patient and their Eka user id (`oid`). It comes from [Create an ABHA with Aadhaar OTP](https://developer.eka.care/docs/hie-cm/workflows/create-abha-aadhaar-otp.md), [Create an ABHA address with mobile OTP](https://developer.eka.care/docs/hie-cm/workflows/create-abha-mobile-otp.md) or [Log in to an existing ABHA](https://developer.eka.care/docs/hie-cm/workflows/login-abha.md). Every call here takes it as the `X-Pt-Id` header or the `oid` query parameter. 
* A live ABHA gateway session for the patient. See [Hold an ABHA gateway session](https://developer.eka.care/docs/hie-cm/workflows/hold-gateway-session.md). 
* The patient's mobile, to receive the facility's OTP.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant HIP as Facility (HIP)
  participant Patient as Patient's phone
  alt Patient searches by name
    App->>Eka: GET /abdm/v1/providers
  else You already hold the hip_id
    App->>Eka: GET /abdm/v1/provider/{hip_id}
  end
  App->>Eka: POST /abdm/v1/care-contexts/discover
  Eka->>HIP: Discovery request through the ABDM gateway
  HIP-->>Eka: Unlinked care contexts
  App->>Eka: POST /abdm/v1/care-contexts/discover/link/init
  Eka->>HIP: Link request through the ABDM gateway
  HIP-->>Patient: OTP via SMS
  App->>Eka: POST /abdm/v1/care-contexts/discover/link/confirm
  Eka->>HIP: OTP through the ABDM gateway
  HIP-->>Eka: Care context linked
```

## Steps

**1. Find the facility**

If the patient searches by name, call [Search Providers](https://developer.eka.care/api-sdk/hie-cm/providers/search/providers.md) 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](https://developer.eka.care/api-sdk/hie-cm/providers/provider.md) 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](https://developer.eka.care/api-sdk/hie-cm/care-contexts/discover/discover.md). 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](https://developer.eka.care/api-sdk/hie-cm/care-contexts/discover/link-init.md). 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](https://developer.eka.care/api-sdk/hie-cm/care-contexts/discover/link-confirm.md). 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](https://developer.eka.care/docs/hie-cm/workflows/phr-list-records.md). 

## 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 every call |
| `hip_id` | Search Providers or Get Provider Details | On the patient record once a link succeeds | Discover again later; list records under that facility |
| `txn_id` (Discover) | Discover | Until Link Init returns | Link Init |
| `patient[].id`, `care_contexts[].id` | Discover | Until Link Confirm returns | `patient_ref_id` and `cc_ref_id` on Link Init |
| `txn_id` (Link Init) | Link Init | Until Link Confirm returns | Link Confirm |
| `cc_ref_id` | Link Confirm | On the patient record | Match the linked care context in later lists |

## 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`. The codes below are from the [errors page](https://developer.eka.care/docs/hie-cm/errors.md). 

| Situation | Code | Do |
| - | - | - |
| Search name shorter than three characters | HTTP 4XX | Ask the patient for a longer name before calling |
| Malformed request or missing field | [`ABDM-1006`](https://developer.eka.care/docs/hie-cm/errors), [`ABDM-1010`](https://developer.eka.care/docs/hie-cm/errors) | Fix the request; do not retry unchanged |
| 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 step |
| Facility found no records | [`ABDM-1012`](https://developer.eka.care/docs/hie-cm/errors), or an empty `patient` list | Retry with a `ref_id`, or try another facility |
| Wrong OTP | [`ABDM-1035`](https://developer.eka.care/docs/hie-cm/errors) (OTP does not match) | Let the patient re-enter it |
| Too many OTP attempts | [`ABDM-1100`](https://developer.eka.care/docs/hie-cm/errors) | Stop; the message says to try again in 30 minutes |
| Transaction expired or unknown | [`ABDM-1017`](https://developer.eka.care/docs/hie-cm/errors), [`ABDM-1052`](https://developer.eka.care/docs/hie-cm/errors) | Restart from Discover |
| Facility unreachable or did not acknowledge | [`ABDM-1028`](https://developer.eka.care/docs/hie-cm/errors), [`ABDM-1401`](https://developer.eka.care/docs/hie-cm/errors), [`ABDM-1402`](https://developer.eka.care/docs/hie-cm/errors), [`ABDM-1048`](https://developer.eka.care/docs/hie-cm/errors) | Tell the patient the facility is not responding |
| Rate limit | [`ABDM-1022`](https://developer.eka.care/docs/hie-cm/errors) | Back off |

## 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`. 

* [ ] 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](https://developer.eka.care/docs/hie-cm/workflows/phr-list-records.md)
* [ ] Wrong OTP once, then the correct OTP
* [ ] Link Confirm with a stale `txn_id` fails, and a fresh Discover recovers


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