Skip to main content

​
In short

  • Turn on auto-approval once, and your app becomes the patient’s health locker.
  • Store auto_approval_id and subscription_id from abha.locker_created.
  • abha.subscription_notify tells you each time a HIP links a new care context.
  • The notification carries no records; fetch them with a consent request.

​
When to use this

Your app is a personal health record (PHR) app, and the patient wants new records from their facilities to arrive without approving each one. An auto-approval policy lets the patient authorise a class of requests once. With it in place, your app is the patient’s health locker. Eka sets up an auto-approval and a subscription. It tells you each time a Health Information Provider (HIP) links a new care context to the patient’s ABHA address. For one request at a time, the patient approves or denies by hand: Approve, deny or revoke a consent in a PHR app.

​
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).
  • A webhook endpoint registered with Eka that verifies the Eka-Webhook-Signature header. See Webhook signature.
  • Your keyset registered, if you manage the data on your side, so records fetched for the locker can be encrypted for you. See Request a patient’s consent as a HIU.

​
Sequence

​
Steps

1

Check the current policy

Call Get Status with the patient’s oid. The response carries status, either enabled or disabled. If it is enabled, the locker is already set up; skip to handling the webhooks.
2

Turn on auto-approval

Call Update Auto Approval Policy. The body is application/x-www-form-urlencoded and carries the patient’s oid. The response carries the new status.
3

Store the locker ids

Wait for abha.locker_created. Reply 200 within 5 seconds; Eka retries on any other status. Store data.auto_approval_id and data.subscription_id against the patient (data.oid, data.abha_address). Together they identify the standing arrangement.
4

Handle new care contexts

Each time a HIP links a new care context to the patient’s ABHA address, Eka sends abha.subscription_notify. Reply 200 within 5 seconds. Read data.subscription_meta: hip_id (the HIP that created the record), event_id, and care_contexts, each with care_context_id and patient_reference.The notification carries no records. To fetch them:
  1. Raise a consent request for those care contexts with Request a patient’s consent as a HIU.
  2. Receive them with Receive and decrypt records as a HIU.
5

Handle subscription changes

When the subscription changes, Eka sends abha.subscription_modified. Reply 200 within 5 seconds. Read data.subscription_details: subscription_id, period (from, to), categories (such as DATA and LINK) and status (such as GRANTED). Update your stored subscription to match.

​
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). Codes are listed on the errors page.

​
Test it

The testing page has the sandbox base URL, credentials and the happy path for every journey. Sandbox base URL: https://api.dev.eka.care.
  • Get Status returns disabled for a new sandbox patient
  • Update Auto Approval Policy returns enabled; abha.locker_created arrives with auto_approval_id and subscription_id
  • Get Status now returns enabled
  • Link a new care context at a sandbox HIP; abha.subscription_notify arrives with its care_context_id
  • Raise a consent for that care context and confirm whether it is approved without a prompt
  • Let the session expire and confirm the 491 path