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

# Link a care context as a HIP

> Register a visit, test or document against the patient's ABHA so it can be discovered and shared.

## In short

* One call links a visit to the patient's ABHA address as a care context.
* Send the FHIR bundle in `data` if Eka stores the record; leave it out if you keep it.
* The call returns `202`; the result arrives on `abha.link_care_context`.
* `LINKED` means the record is shareable; on `ERRORED`, read `data.error`.

## When to use this

A patient with an ABHA has finished a visit, test or admission at your facility. You want that record linked to their ABHA address as a care context. Once linked, the care context is registered with ABDM and any Health Information User (HIU) the patient grants consent to can request it.

Before you link, decide one thing: does Eka store the clinical data, or do you? If Eka stores it, you send the FHIR bundle with the link call and Eka answers every later data request for you. If you keep it, you leave the bundle out and answer each request yourself with [Serve records on a fetch request](https://developer.eka.care/docs/hie-cm/workflows/serve-data-on-fetch.md).

For records created before the patient's ABHA was known, the patient claims them from a PHR app instead. See [Answer discovery and link old records](https://developer.eka.care/docs/hie-cm/workflows/hip-discovery-and-link.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).
* Your facility onboarded as a Health Information Provider (HIP), with its HIP ID. See [Milestone 4](https://developer.eka.care/docs/hie-cm/flows/m4).
* A webhook URL registered with Eka that can receive `abha.link_care_context`, and the means to verify the [webhook signature](https://developer.eka.care/docs/webhooks/webhook-signature.md).
* The patient's `abha_address` and Eka user id `oid`, saved on the patient record. They come from [Create an ABHA with Aadhaar OTP](https://developer.eka.care/docs/hie-cm/workflows/create-abha-aadhaar-otp.md) or [Log in to an existing ABHA](https://developer.eka.care/docs/hie-cm/workflows/login-abha.md).
* Your own id for the care context, its display name and its health information type (`hi_type`, for example `OPConsultation` or `Prescription`).
* If Eka is to store the data: the ABDM-compliant FHIR bundle for the care context.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant ABDM as ABDM gateway
  App->>Eka: POST /abdm/v1/care-contexts/link
  Eka-->>App: 202 Accepted
  Eka->>ABDM: Link care context
  ABDM-->>Eka: Linking result
  Eka-->>App: webhook abha.link_care_context
  opt Notify the patient (timing not yet confirmed)
    App->>Eka: POST /abdm/v1/care-contexts/sms/notify
  end
```

## Steps

**1. Link the care context**

Call [Care context linking](https://developer.eka.care/api-sdk/hie-cm/care-contexts/link/hip-linking.md). Send the patient's `oid` in the `X-Pt-Id` header, your patient id in `X-Partner-Pt-Id` and your HIP ID in `X-Hip-Id`. In the body, send `abha_address`, `oid`, `partner_user_id` and one entry in `care_contexts` per record, each with `care_context_id`, `display` and `hi_type`.

Decide on the data now. If Eka stores the data, put the base64-encoded FHIR bundle in each entry's `data` field and list its health information types in `hi_types`. Eka then answers data requests for you, and you never receive `abha.hip_data_fetch` for this care context. If you keep the data, leave `data` out and run [Serve records on a fetch request](https://developer.eka.care/docs/hie-cm/workflows/serve-data-on-fetch.md) whenever a request arrives.

The call returns `202 Accepted`. That means Eka has taken the request, not that the care context is linked.

**2. Wait for the linking status**

Eka sends the [`abha.link_care_context`](https://developer.eka.care/docs/hie-cm/webhooks/link-care-context) webhook with the result. Acknowledge it with HTTP `200` within 5 seconds; Eka retries on any other status.

Read `data.status`. If it is `LINKED`, mark the care context as linked on your side; it is now discoverable and shareable. If it is `ERRORED`, read `data.error` for the reason. `data.retry_count` reports how many times linking was retried.

Match the webhook to your record by `data.care_context_id`.

**3. Notify the patient (optional)**

Call [Notify unlinked care contexts](https://developer.eka.care/api-sdk/hie-cm/care-contexts/records/notify.md) with the patient's 10-digit `mobile_number`. It notifies the gateway that a new health record is ready to be shared with the patient. It returns `202 Accepted`.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `abha_address`, `oid` | ABHA creation or login | Forever, on the patient record | Every link call for this patient |
| `care_context_id` | You, sent in the link call | Forever, on the visit or document | Matching the status webhook; answering `abha.hip_data_fetch` later |
| Whether `data` was sent | Your decision in step 1 | Forever, on the care context | Knowing whether you must serve this care context on a fetch request |
| `status` | `abha.link_care_context` | Forever, on the care context | Showing the visit as linked; retrying when `ERRORED` |
| The FHIR bundle, if you keep the data | Your clinical system | As long as the care context is linked | Serving it on a fetch request |

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

| Situation | Code | Do |
| - | - | - |
| Request body malformed or a field invalid | `ABDM-1006`, `ABDM-1010` | Fix the request against the reference page and resend |
| ABHA address or number not recognised | `ABDM-1051` | Check the `abha_address` saved on the patient record |
| Wrong HIP ID | `ABDM-1035` (Invalid HIP ID) | `ABDM-1035` also means "OTP does not match" on the errors page. Tell them apart by HTTP status (`500` for Invalid HIP ID, `400` for the OTP) and `source_error.message`. For Invalid HIP ID, check the `X-Hip-Id` header against your onboarded HIP ID |
| Too many requests | `ABDM-1022` | Back off and retry |
| Gateway or a dependent service down | `ABDM-1019`, `ABDM-1024`, `ABDM-1048` | Retry later |
| Status webhook reports `ERRORED` | `data.error` in the webhook | Read the reason; correct and link again |

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

* [ ] Link one `OPConsultation` care context with `data` set, and receive `abha.link_care_context` with `status` `LINKED`
* [ ] Link one care context without `data`, receive `LINKED`, then confirm a later consent request arrives as `abha.hip_data_fetch`
* [ ] Send an invalid `abha_address` and check the error response
* [ ] Return a non-`200` from your webhook once and confirm Eka retries


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