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

# Answer discovery and link old records

> Let a patient find and claim records your facility created before they were linked to their ABHA.

## 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](https://developer.eka.care/api-sdk/auth/getting-started.md).
* 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](https://developer.eka.care/docs/webhooks/webhook-signature.md). Acknowledge each event as described in [Webhooks](https://developer.eka.care/docs/hie-cm/webhooks#delivery-signature-and-acknowledgement).
* 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

```mermaid theme={null}
sequenceDiagram
  participant PHR as Patient's PHR app
  participant ABDM as ABDM gateway
  participant Eka
  participant App as Your app
  PHR->>ABDM: Discover records at your HIP
  ABDM->>Eka: Discovery request
  Eka-->>App: webhook abha.care_context_discover
  App->>Eka: POST /abdm/v1/care-contexts/on-discover
  Eka->>ABDM: Matching care contexts
  PHR->>ABDM: Link the selected care contexts
  ABDM->>Eka: Link request
  Eka-->>App: webhook abha.care_context_discover_link_init
  App-->>PHR: OTP by SMS to the patient's mobile
  App->>Eka: POST /abdm/v1/care-contexts/discover/link/on-init
  PHR->>ABDM: Patient enters the OTP
  ABDM->>Eka: Link confirmation
  Eka-->>App: webhook abha.context_discover_link_confirm
  App->>Eka: POST /abdm/v1/care-contexts/discover/link/on-confirm
  Eka->>ABDM: Linked care contexts
```

## Steps

**1. Answer the discovery request**

Eka sends the [`abha.care_context_discover`](https://developer.eka.care/docs/hie-cm/webhooks/discover-care-context) 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](https://developer.eka.care/api-sdk/hie-cm/care-contexts/discover/on_discover.md) 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](https://developer.eka.care/docs/hie-cm/workflows/link-care-context-hip.md).

**2. Send the OTP and report it**

When the patient selects records to link, Eka sends the [`abha.care_context_discover_link_init`](https://developer.eka.care/docs/hie-cm/webhooks/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](https://developer.eka.care/api-sdk/hie-cm/care-contexts/discover/link_on_init.md) 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`](https://developer.eka.care/docs/hie-cm/webhooks/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](https://developer.eka.care/api-sdk/hie-cm/care-contexts/discover/link_on_confirm.md) 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](https://developer.eka.care/docs/hie-cm/workflows/serve-data-on-fetch.md).

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `txn_id` | `abha.care_context_discover` | Until on-confirm returns | Every reply in this transaction; it ties discovery to link init |
| `request_id` | Each webhook | Until that webhook's reply returns | The reply to that webhook; each webhook has its own |
| Care contexts returned, with `ref_num` | Your on-discover reply | Until on-confirm returns | Checking what the patient selected |
| Selected `reference_number` values | `abha.care_context_discover_link_init` | Until on-confirm returns | The `patients` list in on-confirm |
| OTP and its expiry | You, in step 2 | Until the confirm webhook arrives or the OTP expires | Checking `token` |
| `abha_address` | `abha.care_context_discover` | Forever, on the patient record, if you choose to save it | Linking future records directly |
| Linked flag per care context | You, after on-confirm | Forever | Leaving it out of the next discovery answer |

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

Error responses carry `code`, `error` and `source_error`.

| Situation | Code | Do |
| - | - | - |
| Reply body malformed or `txn_id` or `request_id` missing | `ABDM-1006`, `ABDM-1010` | Check both ids are copied from the webhook and resend |
| Request id or transaction id not recognised | `ABDM-1030`, `ABDM-1052` | Use the `request_id` from the webhook you are answering, not an earlier one |
| Request id already used | `ABDM-1064` | Do not reply twice to the same webhook |
| Care context count does not match | `ABDM-1037` | Check the care contexts in on-confirm match those the patient selected |
| Link token invalid or mismatched | `ABDM-1026`, `ABDM-1038` | Not documented |
| Your system did not answer | `ABDM-1028`, `ABDM-1401`, `ABDM-1402` | Acknowledge each webhook within 5 seconds and reply promptly |
| Gateway timeout | `ABDM-1048` | Not documented |

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

* [ ] 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`


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