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

# Request a patient's consent as a HIU

> Register your encryption key, raise a consent request for a patient's records, and track it until the patient grants or denies it.

## In short

* Register your keyset once, unless Eka stores the data for you.
* Create the consent request and keep `consent_init_id`.
* `abha.consent_update` reports the patient's decision, and Consent List gives the `consent_id`.

## When to use this

You are a Health Information User (HIU) and you need a patient's records from one or more Health Information Providers (HIPs). This workflow raises the consent request and follows it to a decision. Once the patient approves, Eka drives the ABDM gateway callbacks that ask each HIP for the data; you do nothing in between. Receiving the records is the next workflow, [Receive and decrypt records as a HIU](https://developer.eka.care/docs/hie-cm/workflows/hiu-receive-data.md).

A PHR app that pulls records on the patient's behalf is also a HIU and uses the same calls.

## Before you start

* A bearer token for the API. See [Authorization](https://developer.eka.care/api-sdk/auth/getting-started.md).
* Your software set up as a HIU, with the facility onboarded on Eka. 
* A webhook endpoint registered with Eka that verifies the `Eka-Webhook-Signature` header. See [Webhook signature](https://developer.eka.care/docs/webhooks/webhook-signature.md).
* The patient's ABHA address (`health_id`), and the patient's Eka user id (`oid`) if they are registered on Eka.
* Your `clinic_id` and the requesting doctor's `d_oid`. 
* The HIP ids and care context references you want, if you know them.
* A decision on where the records go. If you manage the data on your side, you need the keyset steps. If Eka stores the data for you, skip them. 

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant GW as ABDM gateway and HIPs
  participant Patient as Patient's PHR app
  App->>Eka: GET /abdm/v1/ecdh/keys
  App->>Eka: PATCH /abdm/v1/hiu/keyset
  App->>Eka: POST /abdm/v1/consents/create
  Eka->>GW: consent request
  GW-->>Patient: request appears in the inbox
  Patient-->>GW: approve or deny
  Eka-->>App: webhook abha.consent_update
  App->>Eka: POST /abdm/v1/consents/list
  App->>Eka: POST /abdm/v1/consents/details
```

## Steps

**1. Generate a key pair (once)**

Call [Ecdh keys](https://developer.eka.care/api-sdk/hie-cm/care-contexts/ecdh/keys.md) to generate a key pair. The response carries `private_key`, `public_key` and `nonce`. Store `private_key` and `nonce` securely on your side; you need both to decrypt every record you receive. You can generate the key material locally with the [abdm-ecdh library](https://developer.eka.care/docs/hie-cm/care-contexts/ecdh-encryption.md) instead of calling Eka.

Skip this step and the next if Eka stores the data for you.

**2. Register your public keyset (once, and on rotation)**

Send `public_key` and `nonce` to [Update public keyset](https://developer.eka.care/api-sdk/hie-cm/care-contexts/hiu-keys.md). Both fields are required. Eka shares them with each HIP so the HIP can encrypt the records for you. You can update the keyset at any time.

**3. Create the consent request**

Call [Consent Create](https://developer.eka.care/api-sdk/hie-cm/consents/consent-create.md). The body names:

* `patient`: the patient's `health_id` (ABHA address) and `oid`.
* `hiu`: your `clinic_id`, `d_oid` and the `requester`.
* `purpose`: one of `Self Requested`, `Care management`, `Public Health`, `Disease Specific Health Research`.
* `record_types`: the record types you want, such as `Prescription` or `DischargeSummary`.
* `period`: `from` and `to` for the records' date range, and `expiry` for when the consent ends.
* `hip_identifier` and `care_contexts`: the HIP and the care contexts (`cc_ref`, `patient_ref`) to fetch from.

Keep `consent_init_id` from the response.

**4. Wait for the patient's decision**

Wait for the [`abha.consent_update`](https://developer.eka.care/docs/hie-cm/webhooks/consent-update) webhook. Acknowledge it as described in [Webhooks](https://developer.eka.care/docs/hie-cm/webhooks#delivery-signature-and-acknowledgement). Read `data.notification.consentRequestId`, `data.notification.status` and `data.notification.consentArtefacts.id`.

The webhook fires whenever the consent is updated, so expect it more than once for the same request. Treat the latest status as current.

**5. Find the consent and its status**

Call [Consent List](https://developer.eka.care/api-sdk/hie-cm/consents/consent-list.md) with the same `hiu` (`clinic_id`, `d_oid`) and `patient` (`health_id`, `oid`) you used in Create. Each entry in `consents` carries `consent_init_id`, `consent_id`, `status`, `hi_types` and `period`. Match on `consent_init_id` and keep `consent_id`.

If `status` shows the request was denied or has expired, stop here and close the request on your side.

**6. Read what the patient approved**

Call [Consent Details](https://developer.eka.care/api-sdk/hie-cm/consents/consent-details.md) with `consent_id` and the patient's `health_id`. Each entry in `data` names one `hip` (`id`, `name`) and the `care_contexts` the patient approved from it, each with `id`, `display`, `status` and `documents`.

Keep each `care_contexts[].id`. [Receive and decrypt records as a HIU](https://developer.eka.care/docs/hie-cm/workflows/hiu-receive-data.md) uses it for either storage choice.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `private_key` | Ecdh keys, or the abdm-ecdh library | As long as any consent registered under it can still deliver records | Decrypting every record on `abha.hiu_data_push` |
| `nonce` | Ecdh keys, or the abdm-ecdh library | Same as `private_key` | Decrypting every record |
| `consent_init_id` | Consent Create | Until the consent ends | Matching the request in Consent List |
| `consent_id` | Consent List | Until the consent ends, and as long as you keep records fetched under it for audit | Consent Details, matching `abha.hiu_data_push`, acknowledging on-push |
| `consentArtefacts.id` | `abha.consent_update` | Until the consent ends | Tying a status change to a HIP's artefact |
| `care_contexts[].id` | Consent Details | As long as you keep the records | Matching pushed entries, or reading them from Eka's records product |
| `status` | `abha.consent_update`, Consent List | Until the consent ends | Whether you may still use the records |

## 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` (`code`, `message`).

| Situation | Code | Do |
| - | - | - |
| Malformed or incomplete body | `ABDM-1006`, `ABDM-1010` | Fix the request against the reference page and resend |
| Date range rejected | `ABDM-1063` | Check that `period.from` is before `period.to` |
| Purpose rejected | `ABDM-1046`, `ABDM-1047` | Send one of the four `purpose` values exactly as the spec writes them |
| HIU id not recognised | `ABDM-1040` | Check your facility's HIU onboarding |
| Consent id not recognised | `ABDM-1039` | Check you sent `consent_id` from Consent List, not `consent_init_id` |
| Consent not granted or expired | `ABDM-1062`, `ABDM-1061` | Raise a new consent request; do not retry the old one |
| Too many requests | `ABDM-1022` | Back off and retry |
| Gateway or HIP unavailable | `ABDM-1024`, `ABDM-1028`, `ABDM-1401` | Retry later |
| `abha.consent_update` never arrives | none | Check your webhook registration and signature check, then read the status from Consent List |

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

* [ ] Generate a key pair and register the keyset; the call returns `200`
* [ ] Create a consent request for a sandbox patient; keep `consent_init_id`
* [ ] Approve the request as the patient; `abha.consent_update` arrives and your endpoint replies `200` within 5 seconds
* [ ] Consent List shows the request with a `consent_id`; Consent Details lists the approved care contexts
* [ ] Deny a second request as the patient; your app closes it
* [ ] Send a `period` with `from` after `to`; confirm the error code


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