M3 Retrieve: consent and fetching
In Milestone 3 your organisation asks a patient for permission to read health records it did not create, then fetches them. Your organisation is the HIU, and your software is how it asks. The HIE-CM holds the consent, asks the patient on your behalf, and on a grant returns a consent artefact id. No artefact, no records.
In short
- The HIE-CM asks the patient. You never ask the patient directly.
- The patient must already be known to you by ABHA address.
- One request can produce more than one artefact. Store the request id and every artefact id.
- Records arrive encrypted on your callback URL. Decrypt them, then acknowledge to the gateway.
consentIdandconsentRequestIdare declared as UUIDs but the published examples are not. Do not validate them as UUIDs.
What M3 gives you
| Capability | What your system can do |
|---|---|
| Consent request | Ask a patient, by ABHA address, for named record types over a named date range |
| Status tracking | Check whether a request is pending, granted or denied |
| Consent artefacts | Receive the artefact ids created on a grant, and fetch each artefact |
| Health information request | Ask for the records an artefact covers |
| Data receipt | Receive encrypted records on your callback URL, decrypt them, and acknowledge them |
M3 creates no identities, which is M1 Create, and publishes no records, which is M2 Attach. A hospital that shares its own records and reads records held elsewhere builds both.
Who needs it
Whoever asks to read records they did not create. A hospital pulling a patient's history, an insurer settling a claim, a referral service, a clinical decision tool, and a citizen whose PHR app fetches their records.
Prerequisites
- A working M1 Create integration, so you hold a session token and an ABHA address for the patient.
- Registration in the HIU role, from M4 Enrol. A facility registers an HIU bridge against its facility ID. The HFR does not list insurers, so confirm which entry your organisation registers against. M4 blocks production, not your sandbox build.
- A callback URL the gateway can reach, and a key pair for decryption.
The patient must be known to you by ABHA address first. One concrete route: the patient scans the health facility QR code at registration, and a doctor raises a consent request against that address.
Do not validate consentId or consentRequestId as UUIDs. Treat both as
opaque strings.
What you build, in order
- Raise a consent request. You get a request id on a callback, not inline.
- Track its status. Pending, granted or denied.
- Collect the artefacts. A grant produces one or more artefact ids. Fetch each artefact.
- Raise a health information request against an artefact.
- Receive, decrypt and acknowledge the records on your callback URL.
Build for revocation from the start. A consent that worked yesterday can be withdrawn today, and that is the system working correctly.
Build it with an agent
Hand M3 to the agent you already use, as one file it loads once. Install it, or open it there in one click.
Certification
M3 has no certification step of its own. One exit process covers the whole integration, run once, after every milestone your role needs works end to end. See Going live for the four steps and what each one asks of you.
Test data is in the data dictionary. Support lists the channels. The cases you are certified against are in M3 testing use cases.
The journey, one diagram per flow
Milestone 3 (M3) of ABDM is one story in three parts: a doctor asks for a patient's past records, the patient says yes or no, and if yes the records travel. Each part is drawn below, so you can see the round trips before you read the API reference.
| In the diagram | What it is |
|---|---|
| Patient | The person whose records these are, acting in their PHR app |
| Your system | The software your organisation asks through |
| HIE-CM gateway | The gateway, which routes every call and callback |
| HIE-CM | The HIE-CM, which holds consent and asks the patient |
| HIP | The facility holding the records. It is the HIP when it publishes them, in journeys 2 and 3 |
Journey 1: raising a consent request
A doctor wants the patient's earlier records for a date range. Your system sends the request with the patient's ABHA address. Nothing comes back inline: you get a request id on a callback, then wait for the patient.
The request id is the handle for everything that follows. Store it against the doctor and the patient.
Journey 2: the patient grants or denies
The patient sees who is asking, what they want, why, and for how long. The HIE-CM tells both sides what they chose.
- A grant carries an expiry. The patient sets when the permission runs out.
- A grant can produce more than one consent artefact. Store every id the grant returns.
- The patient can revoke a granted consent at any time. Your access ends when they do.
Journey 3: fetching the records
With an artefact id you fetch the artefact, then ask for the data it covers. The data lands on the data push URL you supplied in that request.
The records arrive encrypted, at the data push URL you supplied. Whether that URL must differ from your other registered callback URLs is not yet published. Your side is simple: decrypt the data, then present it in a readable format.
The scheme is ECDH key exchange, specified on the HIP side. See M2.
What the patient sees
The patient's screens and expiry screens are not reproduced here. What applies to you is on the use cases page under patient rights.
Next
- The request, the decision and the fetch as diagrams: M3 journey below.
- The calls, callbacks and error codes: M3 API reference.
- The next milestone: M4 Enrol.