Skip to main content

Patient record share

Receive health records that a patient chooses to push to you from their PHR app. This use case belongs to M3 Health Information User: your system is the HIU, but the patient starts the share, so there is no consent request and no consent artefact.

Your facility prints a QR code at each counter. It carries your HIU id and a counter id. The patient scans it in their PHR app, picks the care contexts to share, and the HIE-CM tells your bridge a share is coming. You answer with a data push URL and an encryption key, the records arrive on that URL, and both sides report what was delivered.

Try the Patient record share APIs
Every call in Patient record share, one page each: the headers it needs, the payload it takes, the callback it triggers, and a request builder you can fire at the sandbox.
Error codes
What each code Patient record share returns actually means, and the first thing to check when you see one.

In short​

  • The patient starts it. You never raise a consent request.
  • Two callbacks land on your bridge: the share, then the transfer status.
  • You reply once, with a data push URL and an ECDH key, the same key material M3 uses for a consented fetch.
  • Records arrive encrypted on your data push URL. Decrypt, store, then notify.
  • consent.dataEraseAt is the date the patient set. Erase the records by then.

The calls​

Every call carries REQUEST-ID, TIMESTAMP, the gateway Authorization token, X-CM-ID and X-HIU-ID. The base URL is https://dev.abdm.gov.in in sandbox and https://apis.abdm.gov.in in production.

StepWho callsPathCarries
1PHR app to HIE-CMPOST /api/hiecm/patient-record/v3/sharemetaData.hiuId, metaData.counterId, profile.patient, sharedRecordCount, consent
2HIE-CM to your bridgePOST /api/v3/patient-record/shareThe same body plus transactionId
3You to HIE-CMPOST /api/hiecm/patient-record/v3/on-sharehiRequest.transactionId, hiRequest.dataPushUrl, hiRequest.keyMaterial, response.requestId
4PHR app to your dataPushUrlPOSTThe encrypted records
5Both sides to HIE-CMPOST /api/hiecm/patient-record/v3/notifynotification.transactionId, sessionStatus, one hiStatus per care context
6HIE-CM to both callbacksPOST /api/v3/patient-record/on-notifyThe other side's status
Any timePHR app to HIE-CMGET /api/hiecm/patient-record/v3/audit-historyEvery share for the signed-in address, with limit, offset, startDate and endDate

Step 2 is a callback on the URL registered for your bridge, not a call you make. Answer it with a 202 at once, then send step 3. The response.requestId in step 3 is the REQUEST-ID header you received in step 2.

keyMaterial is ECDH on curve25519, with your ephemeral public key, its expiry and a nonce. It is the same shape M3 sends in a health information request, so reuse that code. The key exchange is explained under ECDH.

What each status means​

The PHR app reports the send, and you report the receipt. Send your notify once, after the transfer is complete.

SendersessionStatushiStatus per care context
PHR app or health lockerTRANSFERRED, PARTIAL_TRANSFERRED, FAILEDDELIVERED, ERRORED
You, the HIURECEIVED, PARTIAL_RECEIVED, FAILEDVALID, CORRUPTED, BLANK, ERRORED

Report FAILED when nothing arrived or what arrived did not decrypt.

What you see when it works​

Your bridge receives step 2 with a transactionId, your step 3 returns 202, records arrive on your dataPushUrl, and step 6 brings the app's TRANSFERRED status against the same transactionId.

When it goes wrong​

  • No records after step 3: check that dataPushUrl is reachable from the internet and that keyMaterial.dhPublicKey.expiry is in the future.
  • Records that do not decrypt: report CORRUPTED for that care context in step 5, so the patient sees it in their app.
  • The share arrives for a counter you do not know: metaData.counterId is the value printed in your QR code. Reject with FAILED rather than guess.

The request and response bodies, with every field, are on the Patient scan and record share API reference. NHA has published no swagger for these calls: the reference is built from the API document and Postman collection NHA issued, and no call has been run against sandbox.

Next​

Last updated on