Skip to main content

​
In short

  • Show the patient each pending request, then approve or deny it after their consent PIN.
  • Approval creates one consent artefact per HIP.
  • The patient can later revoke any artefact on its own.
  • Whether abha.consent_update reaches a PHR app is not confirmed; fall back to List Requests.

​
When to use this

Your app is a personal health record (PHR) app. A Health Information User (HIU) such as a doctor, hospital, insurer or another PHR app has asked for the patient’s records. This workflow shows the patient the request, records their decision, and lets them revoke a granted consent later. On approval, ABDM generates one consent artefact per Health Information Provider (HIP), and the patient can revoke each artefact on its own. To stop asking the patient for every request from a trusted source, set up auto-approval instead: Set up the patient’s health locker.

​
Before you start

  • A bearer token for the API. See Authorization.
  • A live ABHA Gateway session for the patient. Every consent operation needs one. See User Session.
  • The patient’s Eka user id (oid), sent as the X-Pt-Id header.
  • A webhook endpoint registered with Eka that verifies the Eka-Webhook-Signature header. See Webhook signature.

​
Sequence

​
Steps

1

List the patient's pending requests

Call List Requests with type set to consent and status set to requested. Both parameters are required.Show the patient who is asking (hiu, requester) and why (purpose). Keep the id of the request they open. To show granted consents they can revoke, call again with status set to granted.
2

Show the request's details

Call Requests Get Details with id and type set to consent. The response carries hi_types (the record types asked for), duration (from, to), erase_at, access_mode and providers. Each provider names a hip (id, name), its care_contexts (id, display) and, once granted, its consent_artefact_id.Let the patient choose which providers, care contexts and record types to share.
3

Check whether the patient has a consent PIN

Call Consent pin exists. If exist is true, go to the verify step. If false, set one first.
4

Set a consent PIN (first time only)

Ask the patient to choose a PIN and send it as pin to Consent pin set. Eka returns 204.
5

Verify the consent PIN

Ask the patient for their PIN and send it as pin to Consent pin verify before you approve or revoke. Eka returns 204.
6

Approve or deny

To approve, call Consent Approve. Send id (the request id) and consent_artefacts, both required. Add one consent_artefacts item per HIP the patient chose, with hip_id, the chosen care_contexts (id, display), hi_types, access_mode (view), duration and erase_at. Eka returns 204.To deny, call Consent Deny with id and, optionally, the patient’s reason in plain text. Eka returns 204.Then update the request in your inbox. Whether a PHR app receives abha.consent_update for requests the patient acts on is not yet confirmed. If it arrives, reply 200 within 5 seconds and read data.notification.status. If it does not, call List Requests with type set to consent and status set to granted, or denied after a denial. Find the request by id.
7

Revoke a granted consent (later)

When the patient wants to cut off a HIP, call Requests Get Details for the granted request and read providers[].consent_artefact_id. Verify the PIN again, then send the artefact ids to cut off as consent_artefacts to Consent Revoke. Eka returns 204. Artefacts you leave out stay granted.

​
State you must persist

The patient’s PIN is not state. Do not store it.

​
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.
  • Raise a request against a sandbox patient with Request a patient’s consent as a HIU
  • It appears in List Requests with status requested; Get Details shows its providers and care contexts
  • Pin exists returns false for a new patient; set a PIN; exists now returns true
  • Verify the PIN and approve one care context. Record whether abha.consent_update arrives (not yet confirmed); otherwise List Requests with status granted shows the request
  • Get Details now shows a consent_artefact_id; revoke it
  • Deny a second request with a reason
  • Let the session expire and confirm the 491 path