Skip to main content

​
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. 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.
  • 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.
  • 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

​
Steps

1

Generate a key pair (once)

Call Ecdh keys 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 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. 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. 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 webhook. Acknowledge it as described in Webhooks. 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 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 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 uses it for either storage choice.

​
State you must persist

​
When it fails

Which of these codes each call returns is not yet confirmed. The codes come from the errors page, matched by meaning. Log the code you actually receive.
Error responses carry code, error and source_error (code, message).

​
Test it

The testing page 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