SANDBOX DOCUMENTATION

(ABDM_Milestone 3)
Version 2.5

Create on 03.03.2025

Contents
1 Base URL and X-CM-ID .................................................................................................................................................... 3
2 Terminology Definition:................................................................................................................................................... 3
3 Gateway flow .................................................................................................................................................................. 3
3.1 Overview.................................................................................................................................................................. 3
3.2 API Information Request & Response..................................................................................................................... 3
3.2.1 Auth token API .................................................................................................................................................. 3
3.2.2 OpenID Configuration API ................................................................................................................................. 5
3.2.3 OAuth Certificate API ........................................................................................................................................ 6
3.2.4 Update bridge URL API...................................................................................................................................... 9
3.2.5 Registration of Facility & Software Linkage..................................................................................................... 10
3.2.6 Find bridge by service id ................................................................................................................................. 12
3.2.7 Find services by bridge id................................................................................................................................ 14
4 Consent flow ................................................................................................................................................................. 17
4.1 Overview................................................................................................................................................................ 17
4.2 Sequence Diagram ................................................................................................................................................. 19
4.3 API Information Request & Response................................................................................................................... 20
4.3.1 HIE-CM - Consent request init ........................................................................................................................ 20
4.3.2 HIE-CM- Consent request init - call back ........................................................................................................ 46
4.3.3 HIE-CM- Callback API to HIU when a consent request is APPROVED/REVOKED/DENIED .............................. 48
4.3.4 HIE-CM – API for HIU to respond back to consent HIU callback ..................................................................... 50
4.3.5 HIE-CM- Consent request status ..................................................................................................................... 53
4.3.6 HIE-CM - Consent request on-status (Callback) .............................................................................................. 56
4.3.7 HIE-CM - Consent request fetch...................................................................................................................... 58
4.3.8 HIE-CM - Consent request on-fetch (callback) ................................................................................................ 61
5 Data flow ....................................................................................................................................................................... 67
5.1 Overview................................................................................................................................................................ 67
5.2 Sequence Diagram ................................................................................................................................................. 67
5.3 API Information Request & Response................................................................................................................... 68
5.3.1 Data flow – Data request invoked by HIU ....................................................................................................... 68
1
 5.3.2 Data flow – call back to HIU ............................................................................................................................ 72
5.3.3 Notify .............................................................................................................................................................. 74
6 Subscription flow .......................................................................................................................................................... 76
6.1 Overview................................................................................................................................................................ 76
6.2 Sequence Diagram ................................................................................................................................................. 76
6.3 API Information Request & Response................................................................................................................... 78
6.3.1 Users get subscription requests ...................................................................................................................... 78
6.3.2 User subscription request initiate................................................................................................................... 80
6.3.3 User Subscription request initiate – Call Back ................................................................................................ 82
6.3.4 Approve Subscription Request........................................................................................................................ 84
6.3.5 Approve Subscription – Call back.................................................................................................................... 88
6.3.6 Subscription Request Hiu – on notify ............................................................................................................. 91
6.3.7 Deny Subscription Request ............................................................................................................................. 92
6.3.8 Deny Subscription – Call Back ......................................................................................................................... 94
6.3.9 Edit Subscription ............................................................................................................................................. 95
6.3.10 Edit Subscription – call back ......................................................................................................................... 99
6.3.11 Subscription HIU –notify ............................................................................................................................. 100
6.3.12 Subscription HIU –On-notify ....................................................................................................................... 104
7 API listing..................................................................................................................................................................... 105

2
1 Base URL and X-CM-ID
Environment Base URL X-CM-ID

Sandbox https://dev.abdm.gov.in sbx

Production https://apis.abdm.gov.in abdm

2 Terminology Definition:
Bridge ID: Is client ID which provided by NHA to HIP (Its alphanumerical eg: SBX_00XXXX)

Service ID: Is Facility ID which is generated from NHPR application (Its alphanumeric eg:
IN02100000XX)

3 Gateway flow
3.1 Overview
This is the key ABDM building block that manages ABHA addresses, maintains links to
health data for each ABHA address and manages consents provided by the user for
sharing of their health data. It also supports exchange of interoperable health data
between HIPs and HIUs.

The HIE-CM enables exchange of personal health data with consent as per the Health
Data Management Policy issued by NHA.

3.2 API Information Request & Response

3.2.1 Auth token API
This API will be invoked to generate auth token.

URL: /api/hiecm/gateway/v3/sessions
Request: POST

Header Parameters:
Property Name Example Value Required Description

3
REQUEST-ID 18235d89-cb13-479d-ad71- Yes Unique UUID for tracking the end-
7a57d5f669a8 toend request transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes The actual time when the request

was initiated, ISO Date time format
represents the date and time

X-CM-ID Sbx Yes Suffix of the consent manager to

which the request was intended.

Body Parameters:
Property Name Example Value Required Description

clientId SBX_XXXXXX Yes Client id for authentication

clientSecret “XXXXXXXXXXXXX” Yes Client secret for

authentication

grantType client_credentials Yes Grant type for authentication

Request Body:
Request Body

"clientId": "SBX_XXXXX",

"clientSecret": "XXXX-XXX-XXXX-XXXX-XXXXXXX",

"grantType": "client_credentials"

Response:
Response

Code : 202 Accepted

"accessToken":
"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJBbFJiNVdDbThUbTlFSl9JZk85ejA2ajlvQ3Y1MXBLS
0ZrbkdiX1RCdkswIn0.eyJleHAiOjE3MjMyMjU3MTEsImlhdCI6MTcyMzIyNDUxMSwianRpIjoiMzE3MjVkN2Qt
NmM1Mi00OWE0LTk0M2MtZmY2ZjhkNjNhYmRlIiwiaXNzIjoiaHR0cHM6Ly9kZXYubmRobS5nb3YuaW4vYX
V0aC9yZWFsbXMvY2VudHJhbC1yZWdpc3RyeSIsImF1ZCI6ImFjY291bnQiLCJzdWIiOiJjN2NhMjk3Yi0yZTVh
LTRkN2UtOGY5YS0xYWU2NDAxYWQ0Y2YiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJTQlhfMDAwMTM1Iiwic2Vzc
2lvbl9zdGF0ZSI6IjhiYjQ4ZGM5LTJmMDUtNDA0OC05MGUxLWRjYjgxNWRmOGU5MyIsImFjciI6IjEiLCJhbGx
vd2VkLW9yaWdpbnMiOlsiaHR0cDovL2xvY2FsaG9zdDo5MDA3Il0sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6W

4
 yJIaWRJbnRlZ3JhdGVkUHJvZ3JhbSIsIkhJVV9QQVlFUiIsImhmciIsImhpdSIsIm9mZmxpbmVfYWNjZXNzIi
wiaGVhbHRoSWQiLCJwaHIiLCJPSURDIiwiaGVhbHRoX2xvY2tlciIsImhpcCIsImhwX2lkIl19LCJyZXNvdXJjZV
9hY2Nlc3MiOnsiU0JYXzAwMDEzNSI6eyJyb2xlcyI6WyJ1bWFfcHJvdGVjdGlvbiJdfSwiYWNjb3VudCI6eyJy
b2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19f
Swic2NvcGUiOiJvcGVuaWQgZW1haWwgcHJvZmlsZSIsImNsaWVudEhvc3QiOiIxMDAuNjUuMTYwLjIxNCI
sImNsaWVudElkIjoiU0JYXzAwMDEzNSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwicHJlZmVycmVkX3VzZXJ
uYW1lIjoic2VydmljZS1hY2NvdW50LXNieF8wMDAxMzUiLCJjbGllbnRBZGRyZXNzIjoiMTAwLjY1LjE2MC4yMTQi
fQ.L56AYZYfzFrO_gNedAbSwR9foEO661z2cMGEeOKsz2ZXsIpTb9oLd9fmRiixIS7ToGoW2VzzXC14qrXnwZIqknBZchTRJrmyGk
6iRJN QYR4k12hrn4tbdW-
h5e9m4NWFAvPtGbBUyKA8gotrne9fn7T0MOC7N_J8TS3JLr2gothJSgc9P3VDKm8c6zpAObQPmwEpH
qJH6j2Q07nGsoaBygxovoIeFn6G6zwIa-_mKw_a86L_CYxr8Gxw5-
5PXkh2XwYp_xLIiJ3t7vLM97UFThwSn_TmRF6W1LH145m_6NxY4hQclHi1elK3OP4LvR1SLDwtAQZSCm4Jpihd0uMw",

"expiresIn": 1200, "refreshExpiresIn": 1800,

"refreshToken":
"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIyMWU5NzA4OS00ZTcxLTQyNGEtOTAzYS1jOTAyMW
M1NmFlNWYifQ.eyJleHAiOjE3MjMyMjYzMTEsImlhdCI6MTcyMzIyNDUxMSwianRpIjoiZGY5ODdmYzQtYzdk
Ni00OGNmLTliM2EtNzRmNWVkMTljMmNmIiwiaXNzIjoiaHR0cHM6Ly9kZXYubmRobS5nb3YuaW4vYXV0a
C9yZWFsbXMvY2VudHJhbC1yZWdpc3RyeSIsImF1ZCI6Imh0dHBzOi8vZGV2Lm5kaG0uZ292LmluL2F1dGg
vcmVhbG1zL2NlbnRyYWwtcmVnaXN0cnkiLCJzdWIiOiJjN2NhMjk3Yi0yZTVhLTRkN2UtOGY5YS0xYWU2ND
AxYWQ0Y2YiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoiU0JYXzAwMDEzNSIsInNlc3Npb25fc3RhdGUiOiI4YmI0O
GRjOS0yZjA1LTQwNDgtOTBlMS1kY2I4MTVkZjhlOTMiLCJzY29wZSI6Im9wZW5pZCBlbWFpbCBwcm9maWx
lIn0._cOnTXMf2bObS1nySL-AjvM5PQxgCHJRm2oO66nrx1M",

"tokenType": "bearer"

3.2.2 OpenID Configuration API

Openid-configuration API, defined within OpenID Connect which provides
configuration information about the Identity Provider (IDP).

URL: /api/hiecm/gateway/v3/.well-known/openid-configuration Request: GET

Header Parameters:
Property Name Example Value Required Description
REQUEST-ID 18235d89-cb13-479d-ad71- Yes Unique UUID for tracking the
7a57d5f669a8 endto-end request transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes The actual time when the request

was initiated, ISO Date time format
represents the date and time

X-CM-ID Sbx Yes Suffix of the consent manager to

which the request was intended.

5
 Response:
Response

Code : 202 OK

"jwks_uri": "https://dev.abdm.gov.in/api/hiecm/gateway/v3/certs"

3.2.3 OAuth Certificate API

This API provide an OAuth certificate that can be used to validate which received gateway
session token in Header on the call back.

URL: /api/hiecm/gateway/v3/certs
Request: GET

Header Parameters:
Property Name Example Value Required Description

REQUEST-ID 18235d89-cb13-479d-ad71- Yes Unique UUID for tracking the end-

7a57d5f669a8 toend request transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes The actual time when the request

was initiated, ISO Date time format
represents the date and time

X-CM-ID Sbx Yes Suffix of the consent manager to

which the request was intended.

Response:
Response

Code : 202 OK

6
{

"keys": [

"e": "AQAB",

"kid": "AlRb5WCm8Tm9EJ_IfO9z06j9oCv51pKKFknGb_TBvK0",

"kty": "RSA",

"n": "mgmW7W5ZGF_G5cJevwYi8HiPcI-6qS_psnZxa4v3bkwAkyOoOd8-6ketrOI-
ZA2PbRbGnxFfZHiI94rdFXJ4Q9ampscsz9NocTIPMPmWydJ8A50pZaYWyikYDSJiDltq7i3WspPKSOuQHrC
5h9dMcCVveX5oeg0tO68Z79gwDlpcxiqDbFaphsqDvx-
5XkfwiqvOBaybK6_BCBPuTqWMUEuUklLYXu2X7ESHdVNFMFAjxCcCXUtP7LFdvT3nnFekRmG82QbSQSVe
4N5tPH8q0MCxSWWn2c15bDnzOF-dvfRCVPRabCzw0M-utHR9diTrWtq6Koi5buxgwM1rbk0p8Q",

"use": "sig",

"x5c": [

"MIICrzCCAZcCBgFy/3WZBjANBgkqhkiG9w0BAQsFADAbMRkwFwYDVQQDDBBjZW50cmFsLXJlZ2lzdHJ5
MB4XDTIwMDYyOTA5NDEzNloXDTMwMDYyOTA5NDMxNlowGzEZMBcGA1UEAwwQY2VudHJhbC1yZWdpc
3RyeTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJoJlu1uWRhfxuXCXr8GIvB4j3CPuqkv6b
J2cWuL925MAJMjqDnfPupHraziPmQNj20Wxp8RX2R4iPeK3RVyeEPWpqbHLM/TaHEyDzD5lsnSfAOdKWW
mFsopGA0iYg5bau4t1rKTykjrkB6wuYfXTHAlb3l+aHoNLTuvGe/YMA5aXMYqg2xWqYbKg78fuV5H8Iqrzg
WsmyuvwQgT7k6ljFBLlJJS2F7tl+xEh3VTRTBQI8QnAl1LT+yxXb0955xXpEZhvNkG0kElXuDebTx/KtDAsUllp9
nNeWw58zhfnb30QlT0Wmws8NDPrrR0fXYk61rauiqIuW7sYMDNa25NKfECAwEAATANBgkqhkiG9w0BAQs

7
FAAOCAQEACkC3TijrXIgi4vn+l1uL1nfdK6vOIL5UZ6yCjSOq7zYW6b3Qe8j7NrPb9RJC+pbIERyNbB+t9hsa5
g1L7lkjCNlUuxfJprsJ9LJKlM5g7dYEA6XPCJ7C6AVlarj72vlWXQvwjnQMO2/CM9/Jp5Hnv2Qwjn7NME2OW
M0iblc/TD+DEZK5L5mlWMyuBSQo2o/AcOmfG4MoE5Gm/CaOJ47rSrf+lq83e5+dyKh7uLVAa+5WK8Im
5nEs6BLSGyo2KlaV0mW9yCkoRLLbipjH8+rJwkUU6iu7QVjz0peGZzYldya5n35gMWH7Bu4HqFneKNRww D6w8rGNC+uWtgWejDZ3yQ=="

],

"x5t": "EaMhYGUIvMkp8tvSM3QoaqaF8xM",

"x5t2": "vGer6Pt8AhZn8RlbHhAFksOCcGf3u1UWU7Qq-Doy7ro",

"alg": "RS256"

},

"e": "AQAB",

"kid": "oc-l6O1yJ7wJKYEeyeUafsz3Aecq7YnCIqbzbIfkJk8",

"kty": "RSA",

"n":
"jDOehgMzurNQT0WJCTWN6a34639uIKOLO1LnXZes_kTakWh6iRxmkExLLCD7MJjz9aijTHwIuKAtOCSbFO pwbqSfF6dMBS2c8cv0AU3pE8kSM
BuUriwr9BUYSUW8SM68QH_HCaz2mmN_Z8ynTQ4kWw_Idj-
enVpkHYtq00DriG98l6RXF1Ao9Kd16ctoNbthuQYH0RSRIXnt0Qtm4GSAY7abPCNa64mir0auldU72DJHXwDo6g5OGz6EMm86ZAV_pvh_5YzFpfk
IMxv0yMMKFZjkFGA0QKYMkMTC5ruLaE7cec-njA7dJQnQ",

"use": "sig",

"x5c": [

"MIICrzCCAZcCBgGHxvQVmDANBgkqhkiG9w0BAQsFADAbMRkwFwYDVQQDDBBjZW50cmFsLXJlZ2lzdHJ
5MB4XDTIzMDQyODA4MTk1N1oXDTMzMDQyODA4MjEzN1owGzEZMBcGA1UEAwwQY2VudHJhbC1yZWdpc
3RyeTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAIwznoYDM7qzUE9FiQk1jemt+Ot/biCjiztS
512XrP5E2pFoeokcZpBMSywg+zCY8/Woo0x8CLigLTgkmxTqcG6knxenTAUtnPHL9AFN6RPJEjKRiSg2fXYg
PgblK4sK/QVGElFvPkjOvEB/xwms9ppjf2fMp00OJFsPyHY/np1aZB2LatNA64hvfJekVxdQKPSndenLaDW7Y
bkGB9EUkSF57dELZuBkgGO2mzwjWuuJoq9PmrpXVPu9gyR18A6OoOThs+hDJvOmQFf6b4f+WMxaX5FA
PEytixVQJgt1KfiDMb9MjDChWY5BRgNECmDJDEwua7i2hO3HnPp4wO3SUJ0CAwEAATANBgkqhkiG9w0B
AQsFAAOCAQEABYAcXOSr+WgOxKVmygID9WjB4rDuAVDyU3GmjBvckdWhYJuBX8Vs04hNVNgf904gqy
+D5wZIQU985stK3PdogFGN2jVw2kO9G3hG4/7uwYKqciKApT/pSPMeHRltHGp/Mwr6e5poVwgQyrn+Be
H373U1Q6eB1QUYnElP+16y7bbvQhfDAS2X9sqdfurB9YIL5xZMPddZaf7pPX8oWOVlB0XH1JEZfsX125qq0Xn
K8z/Rd8KI8zTfJw6D2Kzrk1WvQSlM5KnTQmcSk3kwDlW5Dg657dT49Y68mI4azq34q17JgBhTx3IbTuf94QT w7QC5wmFtO+hc6zPVODX8JWu7

8
 ],

"x5t": "-HZ-fkkNBhTsPHWrhATwlZflhdU",

"x5t2": "tjVDNCTx7Fn0TfM-6uHvbwjWlIxIaFtGxiZZ6uJFxr4",

"alg": "RS512"

3.2.4 Update bridge URL API

This API will be called to update the bridge base URL.

URL: /api/hiecm/gateway/v3/bridge/url Request: PATCH

Header Parameters:
Property Name Example Value Required Description

Authorization eyJhbGciOiJSUzUxMiJ9. Yes JWT Access token which was

eyJzdWIiOiJ2YXNhbnRoY issued by ABDM session API
Wt1bWFyLmtlc2F2YW5Ac after successful validation of
2J4IiwiY2xpZW50SWQiOi client id and secret.
JzYngiLCJzeXN0ZW0iOiJ
BQkhBLUEiLCJyZXF1ZXN0Z
XJJZCI6IlBIUi1XRUIiLCJwa
HJNb2JpbGUiOm51bGws

REQUEST-ID 18235d89-cb13-479dad71- Yes Unique UUID for tracking the

7a57d5f669a8 end-to-end request
transaction

TIMESTAMP 2022-10- Yes The actual time when the

06T10:10:00.587Z request was initiated, ISO
Date time format represents
the date and time

X-CM-ID sbx Yes Suffix of the consent manager

to which the request was
intended.

Body Parameters:
Property Name Example Value Required Description

9
url https://webhook.site/b7 Yes Bridge base URL
99c0b8-4e75-4545- 8eb2-
d8c2d5f0c9f6

Request Body:
Request Body
{

"url": "https://webhook.site/b799c0b8-4e75-4545-8eb2-d8c2d5f0c9f6"

Response:
Response

Code : 202 Accepted

3.2.5 Registration of Facility & Software Linkage

Overview: The software being used by the provider must integrate with the digital
building blocks of ABDM and comply with the guidelines outlined NHA. NHA maintains
the national directory of all healthcare facilities. Any participating facility needs to sign up
in the health facility registry at (nhpr.abdm.gov.in) This ensures that they are a valid
facility which is authorized to issue health records in the ecosystem. HFR consists of
information for each healthcare facility in the country – hospitals, clinics, diagnostic
centers, pharmacies etc., across all systems of medicine and covering both public and
private health facilities. HFR offers APIs that can be used by various stakeholders in the
ecosystem. Healthcare information service provider application or healthcare repository
provider application must be upgraded to become ABDM compliant.

Registration of facility:

Through website: https://hspsbx.abdm.gov.in/home (sandbox),

https://nhpr.abdm.gov.in/home (production) Step-by-step user

manual document access:

Goto: https://hspsbx.abdm.gov.in/home (sandbox) , https://nhpr.abdm.gov.in/home (production)

>>Resource center >> User Manual
>> Select “For Health Facility” >>Download “User Manual” >>Refer Content

10
“A” (Health Professional ID (HPID) creation), “B” (Facility Registration)

Registration of bridge services (HIP/HIU) on facility:

Option 1: Linking through website: https://hspsbx.abdm.gov.in/home (sandbox) ,

https://nhpr.abdm.gov.in/home (production) Step-by-step user manual document access:

Goto: https://hspsbx.abdm.gov.in/home (sandbox) , https://nhpr.abdm.gov.in/home ( production)

>>Resource center >> User Manual
>> Select “For Health Facility” >>Download “User Manual” >>Refer Content “C” (Software
Linkage)

Option 2: Through API

This API ( https://facilitysbx.abdm.gov.in/v1/bridges/MutipleHRPAddUpdateServi

ces ) will be used to link multiple bridges against a facility. It will accept the facility
id , facility name and list of HRP i.e. bridges.
Please note:
• You must pass in all the required parameters to create the API.
• The data needs to be passed in the required format as mentioned for each field.
API can refer swagger link :
https://facilitysbx.abdm.gov.in/swaggerui.html#/Multiple_HRP_API >>>Go to Multi
HRP API >>>and Select “/v1/bridges/MutipleHRPAddUpdateServices
v1MutipleHRPAddUpdateServices”

Parameters:

Params Required Description Format if any

Data type

facilityId Yes Will be validated if present in String Starting with IN

HFR or not and of 12
characters

facilityName Yes Name of the facility to be linked String Alphanumeric

11
bridgeId Yes Valid Bridge Id to be linked. String Alphanumeric and
validity to be
checked by HIECM

hipName Yes • To provide uniqueness against String • HIP name can be

each bridges that is linked . HIP the Hospital name
name is the name of the added with suffix of
hospital which will reflect
bridge name.
example

on ABHA/PHR app Hospital and

when the patent will name=XYZ
search for the bridge name
respective hospital.
=BRIDGE TEST, so
the HIP name = XYZ

BRIDGE. • name
HIP
can not be
more
than 15
characters., No is
special
character
allowed
(%$*#@(~&!), and
it should be unique
for every bridge for
a
facility

type Yes HIP / HIU etc String Validated by

HIECM

Active Yes True/false boolean Accept Boolean

value

3.2.6 Find bridge by service id

This API will fetch the bridge details for the given service id.

12
URL: /api/hiecm/gateway/v3/bridge-service/serviceId/{serviceId} Request: GET
Header Parameters:
Property Name Example Value Required Description
Authorization eyJhbGciOiJSUzUxMiJ9. Yes JWT Access token which was
eyJzdWIiOiJ2YXNhbnRoY issued by ABDM session API
Wt1bWFyLmtlc2F2YW5Ac after successful validation of
2J4IiwiY2xpZW50SWQiOi client id and secret.
JzYngiLCJzeXN0ZW0iOiJ
BQkhBLUEiLCJyZXF1ZXN0Z
XJJZCI6IlBIUi1XRUIiLCJwa
HJNb2JpbGUiOm51bGws
ImV4cCI6MTY2NzI5ODEx
NSwiaWF0IjoxNjY3MjkwO
TE1LCJwaHJBZGRyZXNzIjo
idmFzYW50aGFrdW1hci5
rZXNhdmFuQHNieCIsInR
4bklkIjoiYjEwMGM4ZDMt
NTE1ZC00YWFiLTg1OWQtY
zNlMTUwOTE3ZGY1In0

REQUEST-ID 18235d89-cb13-479dad71- Yes Unique UUID for tracking the

7a57d5f669a8 end-to-end request
transaction

TIMESTAMP 2022-10- Yes The actual time when the

06T10:10:00.587Z request was initiated, ISO
Date time format represents
the date and time

X-CM-ID sbx Yes Suffix of the consent manager

to which the request was
intended.

Response:
Response

Code : 200 Ok

"id": 1561,

"bridgeId": "SBX_XXXX",

"serviceId": "TestClinicHIP",

"name": "TestClinicHIP",

13
 "isHip": true,

"isHiu": true,

"isPhr": false,

"endpoints": {},

"active": true,

"registerTime": "2021-03-01 11:17:35.1735",

"dateCreated": "2021-03-01 11:17:35.1735",

"dateModified": "2024-04-22 11:04:46.446"

3.2.7 Find services by bridge id

This API will fetch all the service details for the bridge id from authorization token.

URL: /api/hiecm/gateway/v3/bridge-services
Request: GET

Header Parameters:
Property Name Example Value Required Description
Authorization eyJhbGciOiJSUzUxMiJ9. Yes JWT Access token which was
eyJzdWIiOiJ2YXNhbnRoY issued by ABDM session API
Wt1bWFyLmtlc2F2YW5Ac after successful validation of
2J4IiwiY2xpZW50SWQiOi client id and secret.
JzYngiLCJzeXN0ZW0iOiJ
BQkhBLUEiLCJyZXF1ZXN0Z
XJJZCI6IlBIUi1XRUIiLCJwa
HJNb2JpbGUiOm

REQUEST-ID 18235d89-cb13-479dad71- Yes Unique UUID for tracking the

7a57d5f669a8 end-to-end request
transaction

TIMESTAMP 2022-10- Yes The actual time when the

06T10:10:00.587Z request was initiated, ISO
Date time format represents
the date and time

14
 X-CM-ID sbx Yes Suffix of the consent manager
to which the request was
intended.

Response:

Response

Code : 200 Ok

"bridge": {

"id": "SBX_XXXX",

"name": "Testing",

"url": "https://abdcb.doctor9.com",

"active": true,

"blocklisted": false

},

"services": [

15
"id": "@#$%^&*(",

"name": "hello",

"types": [

"HIP",

"HIU"

],

"endpoints": {

"hipEndpoints": [

"use": "registration",

"connectionType": "HTTPS",

"address": "https://events.hookdeck.com/e/src_3gsnEgI941mh/registration"

},

"use": "data-upload",

"connectionType": "HTTPS",

"address": "https://events.hookdeck.com/e/src_3gsnEgI941mh/data-upload"

],

"hiuEndpoints": [

"use": "registration",

"connectionType": "HTTPS",

"address": "https://events.hookdeck.com/e/src_3gsnEgI941mh/registration"

},

16
 {

"use": "data-upload",

"connectionType": "HTTPS",

"address": "https://events.hookdeck.com/e/src_3gsnEgI941mh/data-upload"

],

"healthLockerEndpoints": [

"use": "registration",

"connectionType": "HTTPS",

"address": "https://events.hookdeck.com/e/src_3gsnEgI941mh/registration"

},

"use": "data-upload",

"connectionType": "HTTPS",

"address": "https://events.hookdeck.com/e/src_3gsnEgI941mh/data-upload"

},

"active": true

4 Consent flow
4.1 Overview
The service used to handle consent management before sharing the health data between
the entities (HIP, HIU, PHIU)
17
There are a couple of essential attributes required for consent artefact like Purpose, HI
Types, Access mode, Requester, Range, and Validity.

HIE-CM will validate HIU requests for authenticity, replay attack, timestamp, ABHA address,
etc. The request will be saved into the database. The consent request id will be returned
to the called HIU for future tracking purposes.

The valid requests will be broadcasted to the priority queue and sent to all the ABDM
compliance Patient HIU (PHR application). The consent notification status will be saved into
the database.

Upon successful acknowledgment, the consent artifact will be generated and saved into
the database. HIECM will further share this consent artefact with HIP and HIU.

18
4.2 Sequence Diagram

19
4.3 API Information Request & Response
4.3.1 HIE-CM - Consent request init
This is an API that will be invoked by HIU to initiate a consent request to get data about a
patient.

While requesting and exchanging health information, there are meta codes that are
relevant to you if you are a HIU.

• Purpose of Use - defines what is the purpose of use of the health information that
a HIU is requesting for. The following are subset from
http://terminology.hl7.org/ValueSet/v3-PurposeOfUse

Code Display

CAREMGT

BTG
Care Management

Break the Glass

PUBHLTH

Public Health

HPAYMT
Healthcare Payment
DSRCH Disease Specific Healthcare Research

Self-Requested
PATRQT

URL: /api/hiecm/consent/v3/request/init Request:

POST Header Parameters:
Property Example Value Required Description
Name

20
Authorization Gateway Session Token Yes JWT Access token which was
issued by ABDM session API
after successful validation of
client id and secret

REQUEST-ID 18235d89-cb13-479d-ad71- Yes Unique UUID for track the

7a57d5f669a8 end to end request
transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request

was initiated, ISO Date time
format represents date and
time

X-CM-ID sbx Yes Suffix of the consent manager

to which the request was
intended

Body Parameters:
Property Name Example Value Required Description
Patient abc@abdm Yes A unique and valid
ABHA address suffix
with @abdm for live
and @sbx for Sandbox

Hip ABDM_HIP No Health information

provider ID

purpose – text Care Management Yes Purpose text of consent

request

Purpose-code CAREMGT Yes Purpose code of

consent request

Purpose-refUri www.test.com Yes Purpose refUri of

consent request

patientReference batman@tmh No Patient reference

Id

careContextReference Episode11 No Care context reference

Hiu Sub_HIU Yes Health information user

Id

21
Requester-name Smith yes Name of the requester

Requester-identifiertype REGN01 yes Requester identifier

type

Requester-identifiervalue MH1001 yes Requester identifier

value

Requester-identifiersystem https://www.mciindia.org yes Requester identifier

system

hiTypes ["Prescription", yes Type of document

"DiagnosticReport",
"DischargeSummary
"ImmunizationRecord",
"HealthDocumentRecord",
"WellnessRecord",
"OPConsultation"]

PermissionaccessMode VIEW yes Access mode of

consent

PermissiondateRange "from": "2023-05-09T08:58:09.738Z", yes Data range of

"to": "2023-05-10T08:58:09.738Z" permission required

PermissiondateEraseAt 2023-05-25T08:58:09.738Z yes Date of erase data

Permissionfrequency-value 0 yes Frequency value for

consent

Permissionfrequencyrepeats 0 yes Frequency repeats for

consent

Permissionfrequency-unit HOUR yes Frequency unit for

consent

hiTypes “PRESCRIPTION” yes hiTypes of the patient

details. It is a list,
there can be more
than one hitype.

Request Body:
Request Body

22
{
"consent": {
"hip": {
"id": "HIP_ID"
},
"hiu": {
"id": "HIU_ID"
},
"hiTypes": [
"Prescription",
"DiagnosticReport",
"DischargeSummary",
"ImmunizationRecord",
"HealthDocumentRecord",
"WellnessRecord",
"OPConsultation"
],
"patient": {
"id": "abhaaddress@sbx"
},
"purpose": {
"code": "CAREMGT",
"text": "Care Management",
"refUri": "www.abdm.gov.in"
},
"requester": {
"name": "Dr. Manju",
"identifier": {
"type": "REGNO",
"value": "MH1001",
"system": "https://www.mciindia.org"
}
},
"permission": {
"dateRange": {
"to": "2024-07-17T12:05:57.151Z",
"from": "1924-07-09T12:05:57.151Z"
},
"frequency": {
"unit": "DAY",
"value": 0,
"repeats": 0
},
"accessMode": "VIEW",
"dataEraseAt": "2124-11-09T00:00:00.000Z"
},
"careContexts": [

{
"patientReference": "xxxx@sbx",
"careContextReference": "COCa496bc2f-ca6c-4af5-b973-02e915fd9815"
}

23
 ]
}
}

Response Body:
Response
Code : 202 Accepted

Error scenarios:
Scenarios Request Body Response

To verify [ Access Denied

when
{ Code : 403 Forbidden
Request ID is
Blank, null or "key": "REQUEST-ID",
empty in header
"value": "",

"type": "text"

To verify when [ {
invalid RequestID
is pass in header { "code": "ABDM-1030: ",

"key": "REQUEST-ID", "message": "Invalid request ID"

"value": "{{$guid}}zxzzxs", }

"type": "text" Code: 400Bad Request

}]

When X-CM- [ Access Denied

ID is Invalid,
{ Code : 403 Forbidden
Blank, null or
empty in header. "key": "X-CM-ID",

"value": "sbxdvdfvdf",

"type": "text"

24
 ]

Verify { {
message when
"consent": { "code": "ABDM-9999",
purpose text is
empty or null "purpose": { "message": "Consent purpose text
cannot be null"
"text": "",
}
"code": " CAREMGT",

"refUri": "string"

},

"patient": {

"id": "xxxxxxxxx@abdm"

},

"hip": {

"id": "HIP_ID"

},

"careContexts": [

"patientReference": "xxxxx@tmh",

"careContextReference": "Episode11"

],

"hiu": {

"id": "HIU_ID"

},

"requester": {

"name": "Dr. xxxx",

"identifier": {

"type": "REGNO1",

"value": "MH10XX",

25
 "system": "https://www.xxxxxx.org"

},

"hiTypes": [

"OPCONSULTATION",

"WELLNESSRECORD"

],

"permission": {

"accessMode": "VIEW",

"dateRange": {

"from": "2023-05-09T08:58:09.738Z",

"to": "2023-05-10T08:58:09.738Z"

},

"dataEraseAt": "2023-05- 25T08:58:09.738Z",

"frequency": {

"unit": "HOUR",

"value": 0,

"repeats": 0

26
Verify { {
message when
"consent": { "code": "ABDM-9999: ",
purpose text is
not any of the "purpose": { "message": "Invalid purpose text, it must

following: be in Care Management,

"text": "Care Management123",
Break the Glass, Public Health,
Care
"code": "CAREMGT", Healthcare Payment, Disease
Management,
Specific Healthcare Research, Self
Break the "refUri": "string" Requested"
Glass, Public
}, }
Health,
Healthcare "patient": {
Payment, "id": "xxxxxxxxxxxxx@abdm"

27
Disease },
Specific
"hip": {
Healthcare
Research, Self "id": "SBX_HIP1"

Requested },

"careContexts": [

"patientReference": "xxxxx@tmh",

"careContextReference": "Episode11"

],

"hiu": {

"id": "HIU_ID"

},

"requester": {

"name": "Dr. xxxxx",

"identifier": {

"type": "REGNO1",

"value": "MH1001",

"system": "https://www.xxxxxx.org"

},

"hiTypes": [

"OPCONSULTATION",

"WELLNESSRECORD"

],

"permission": {

"accessMode": "VIEW",

"dateRange": {

"from": "2023-05-09T08:58:09.738Z",

"to": "2023-05-10T08:58:09.738Z"

},

28
 "dataEraseAt": "2023-05- 25T08:58:09.738Z",

"frequency": {

"unit": "HOUR",

"value": 0,

"repeats": 0

Verify { {
message when
"consent": { "code": "ABDM-9999",
purpose code is
empty or null "purpose": { "message": "Consent purpose code
cannot be null"
"text": "Care Management",
}
"code": " ",

"refUri": "string"

},

"patient": {

"id": "xxxxxx@abdm"

},

"hip": {

"id": "HIP_ID"

},

"careContexts": [

"patientReference": "xxxxx@tmh",

"careContextReference": "Episode11"

],

"hiu": {

"id": "HIU_ID"

},

29
 "requester": {

"name": "Dr. xxxxx",

"identifier": {

"type": "REGNO1",

"value": "MH1001",

"system": "https://www.mciindia.org"

},

"hiTypes": [

"OPCONSULTATION",

"WELLNESSRECORD"

],

"permission": {

"accessMode": "VIEW",

"dateRange": {

"from": "2023-05-09T08:58:09.738Z",

"to": "2023-05-10T08:58:09.738Z"

},

"dataEraseAt": "2023-05- 25T08:58:09.738Z",

"frequency": {

"unit": "HOUR",

"value": 0,

"repeats": 0

30
Verify { {
message when
"consent": { "code": "ABDM-9999",
purpose text is
not any of the "purpose": { "message": "Invalid purpose code, it
must be in CAREMGT, BTG, PUBHLTH,
following: "text": "Care Management",
HPAYMT, DSRCH, PATRQT"
CAREMGT,
"code": "CARE", }
BTG, PUBHLTH,
HPAYMT, "refUri": "www.ref.com"
DSRCH,
},
PATRQT
"patient": {

"id": "xxxxxxx@abdm"

},

"hip": {

"id": "HIP_ID "

},

"careContexts": [

"patientReference": "xxxxxx@tmh",

"careContextReference": "Episode11"

],

"hiu": {

"id": "HIU_ID "

},

"requester": {

"name": "Dr. Manjula",

"identifier": {

"type": "REGNO1",

"value": "MH1001",

"system": "https://www.mciindia.org"

},

"hiTypes": [

"OPCONSULTATION",

31
 "WELLNESSRECORD"

],

"permission": {

"accessMode": "VIEW",

"dateRange": {

"from": "2023-05-09T08:58:09.738Z",

"to": "2023-05-10T08:58:09.738Z"

},

"dataEraseAt": "2023-05- 25T08:58:09.738Z",

"frequency": {

"unit": "HOUR",

"value": 0,

"repeats": 0

32
Verify { {
message when
"consent": { "code": "ABDM-9999",
the refUri is
null, empty or "purpose": { "message": "Invalid consent purpose
invalid. refURI"
"text": "Care Management",
}
"code": "CARE",

"refUri": ""

},

"patient": {

"id": "xxxxxxx@abdm"

},

"hip": {

"id": "SBX_HIP1"

},

"careContexts": [

33
 {

"patientReference": "batman@tmh",

"careContextReference": "Episode11"

],

"hiu": {

"id": "HIU_ID "

},

"requester": {

"name": "Dr. Manjula",

"identifier": {

"type": "REGNO1",

"value": "MH1001",

"system": "https://www.mciindia.org"

},

"hiTypes": [

"OPCONSULTATION",

"WELLNESSRECORD"

],

"permission": {

"accessMode": "VIEW",

"dateRange": {

"from": "2023-05-09T08:58:09.738Z",

"to": "2023-05-10T08:58:09.738Z"

},

"dataEraseAt": "2023-05- 25T08:58:09.738Z",

"frequency": {

"unit": "HOUR",

"value": 0,

"repeats": 0

34
 }

Verify "permission": { {
message when
"accessMode": null, "code": "ABDM-9999",
the permission
access mode is "dateRange": { "message": Invalid accessMode, it must
null. be in VIEW, STORE, QUERY, STREAM"
"from": "2023-05-09T08:58:09.738Z",
}
"to": "2023-05-10T08:58:09.738Z"

},

"dataEraseAt": "2023-05- 25T08:58:09.738Z",

"frequency": {

"unit": "HOUR",

"value": 0,

"repeats": 0

Verify "permission": { {
message when
"accessMode": “VIEW”, "code": "ABDM-9999",
the permission
date range is "dateRange": null, "message": “DateRange should not be
null. null or empty"
"dataEraseAt": "2023-05- 25T08:58:09.738Z",
}
"frequency": {

"unit": "HOUR",

"value": 0,

"repeats": 0

35
Verify "permission": { {
message when
"accessMode": “VIEW”, "code": "ABDM-9999",
the permission
date range is in "message": “Invalid from/to date. Date
"dateRange": {
future.
must be a present/before date"
"from": "2026-05-09T08:58:09.738Z",
}
"to": "2028-05-10T08:58:09.738Z"

},

"dataEraseAt": "2023-05- 25T08:58:09.738Z",

"frequency": {

"unit": "HOUR",

"value": 0,

"repeats": 0

Verify "permission": { {
message when
"accessMode": “VIEW”, "code": "ABDM-9999",
the dataEraseAt
is not a future "dateRange": { "message": “Invalid data erase date.
date.
Date must be a future date"
"from": "2023-05-09T08:58:09.738Z",
}
"to": "2024-05-10T08:58:09.738Z"

},

"dataEraseAt": "2029-05- 25T08:58:09.738Z",

"frequency": {

"unit": "HOUR",

"value": 0,

"repeats": 0

36
Verify "permission": { {
message when
"accessMode": “VIEW”, "code": "ABDM-9999",
the permission
frequency is null. "message": “Frequency should not be
"dateRange": {
null or empty"
"from": "2023-05-09T08:58:09.738Z",
}
"to": "2024-05-10T08:58:09.738Z"

},

"dataEraseAt": "2029-05- 25T08:58:09.738Z",

"frequency": null

Verify "permission": { {
message when
"accessMode": “VIEW”, "code": "ABDM-9999",
the frequency
unit is null. "message": “Frequency unit should not
"dateRange": {
be null or empty"
"from": "2023-05-09T08:58:09.738Z",
}
"to": "2024-05-10T08:58:09.738Z"

},

"dataEraseAt": "2029-05- 25T08:58:09.738Z",

"frequency": {

"unit": null,

"value": 0,

"repeats": 0

37
Verify message { {
when null,
empty or invalid "consent": { "code": "ABDM-9999",
abha address.
"purpose": { "message": “Invalid ABHA
Address, it must start with Alphanumeric .
"text": "Care Management", and _ in the middle and must be ending
"code": "CARE", with @abdm or @sbx"

}
"refUri": ""

},

"patient": {

"id": "xxxxxxxx@abdm"

},

38
"hip": {

"id": "HIP_ID"

},

"careContexts": [

"patientReference": "batman@tmh",

"careContextReference": "Episode11"

],

"hiu": {

"id": "HIU_ID"

},

"requester": {

"name": "Dr. Manjula",

"identifier": {

"type": "REGNO1",

"value": "MH1001",

"system": "https://www.mciindia.org"

},

"hiTypes": [

"OPCONSULTATION",

"WELLNESSRECORD"

],

"permission": {

"accessMode": "VIEW",

"dateRange": {

"from": "2023-05-09T08:58:09.738Z",

"to": "2023-05-10T08:58:09.738Z"

},

"dataEraseAt": "2023-0525T08:58:09.738Z",

39
 "frequency": {

"unit": "HOUR",

"value": 0,

"repeats": 0

40
Verify { {
message
"consent": { "code": "ABDM-9999",
when null,
empty or "purpose": { "message": “Invalid Service ID, it must
be Alpha numeric and _ or - in middle"
invalid HIP or
"text": "Care Management",
HIU service id. }
"code": "CARE",

"refUri": ""

},

"patient": {

"id": "xxxxxxxxxxxx@abdm"

},

"hip": {

"id": "SBX_HIP1"

},

"careContexts": [

"patientReference": "batman@tmh",

"careContextReference": "Episode11"

],

"hiu": {

"id": "Sub_HIU"

},

"requester": {

"name": "Dr. Manjula",

41
 "identifier": {

"type": "REGNO1",

"value": "MH1001",

"system": "https://www.mciindia.org"

},

"hiTypes": [

"OPCONSULTATION",

"WELLNESSRECORD"

],

"permission": {

"accessMode": "VIEW",

"dateRange": {

"from": "2023-05-09T08:58:09.738Z",

"to": "2023-05-10T08:58:09.738Z"

},

"dataEraseAt": "2023-05- 25T08:58:09.738Z",

"frequency": {

"unit": "HOUR",

"value": 0,

"repeats": 0

Verify { {
message
"consent": { "code": "ABDM-1031",
when null,
empty or "purpose": { "message": “HIP is mandatory when care
contexts are specified"
invalid HIP or
"text": "Care Management",
HIU service id. }
"code": "CARE",

"refUri": "www.ref.com"

42
43
44
},

"patient": {

"id": "18443810806440@abdm"

},

"hip": null,

"careContexts": [

"patientReference": "batman@tmh",

"careContextReference": "Episode11"

],

"hiu": {

"id": "Sub_HIU"

},

"requester": {

"name": "Dr. Manjula",

"identifier": {

"type": "REGNO1",

"value": "MH1001",

"system": "https://www.mciindia.org"

},

"hiTypes": [

"OPCONSULTATION",

"WELLNESSRECORD"

],

"permission": {

"accessMode": "VIEW",

"dateRange": {

"from": "2023-05-09T08:58:09.738Z",

"to": "2023-05-10T08:58:09.738Z"

},

45
 "dataEraseAt": "2023-05- 25T08:58:09.738Z",

"frequency": {

"unit": "HOUR",

"value": 0,

"repeats": 0

4.3.2 HIE-CM- Consent request init - call back

This API initiated by HIE-CM to get the consent request call back to HIU

URL: {callback}/api/v3/hiu/consent/request/on-init Request:

POST Header Parameters:
Property Example Value Required Description
Name
Authorization Gateway Session Token Yes ABDM Gateway
Session Token

REQUEST-ID 18235d89-cb13-479d-ad71- Yes Unique UUID for track the

7a57d5f669a8 end to end request
transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request

was initiated, ISO Date
time format represents
date and time

X-CM-ID sbx Yes Suffix of the consent

manager to which the
request was intended

X-HIU-ID HIU_ID Yes Identifier of the health

information user by which
the request was initiated

Body Paramaters:

46
 Property Name Example Value Required Description
consentRequest – id f29f0e59-8388-4698-9fe605db67aeac46 No The consent request id
generated for consent
init request.

requestId 6f0b4665-a915-4c92-aa36- Yes Unique UUID from the

65afb4a2cd71 consent init request.

Error "error": { No The error code and

message if any
"code": "ABDM-1001", happened.

"message": "unable to connect database"

Request Body:
Request Body
{
"consentRequest": {
"id": "05f14b1d-4465-453a-8249-1382d79d271d"
},
"error": null,
"response": {
"requestId": "4213ebf8-5f8a-45e4-a014-7a2eb875f213"
}
}

Response Body:
Response
Code : 202 Accepted

47
4.3.3 HIE-CM- Callback API to HIU when a consent request is
APPROVED/REVOKED/DENIED
Once the patient grants consent to the HIU, the CM notifies the HIU system of the
consent grant via the gateway. If the patient grants for multiple HIPs, then multiple
consent artefacts are generated - one for each HIP. The HIU now first fetches all the
consent-artefacts that were generated for his request.
URL: {{callback}} /api/v3/hiu/consent/request/notify Request: POST
Header Parameters:
Property Name Example Value Required Description

REQUEST-ID 18235d89-cb13-479d-ad71- Yes Unique UUID for track the end to

7a57d5f669a8 end request transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request was

initiated, ISO Date time format
represents date and time

X-HIU-ID eyJhbGciOiJSUzUxMiJ9.eyJzdWIiOiIx Yes Identifier to the health

information user.
ODQ0MzgxMDgwNjQ0MEBhYmRt

Body parameters:
Property Name Example Value Required Description
status GRANTED Yes The status of the consent
artefact

48
 consentRequestId 3fa85f64-5717-4562b3fc- Yes The consent request
2c963f66afa6 id

reason Not Authorized No Reason for denying the

consent request

consentArtefacts "consentArtefacts": [ No List of consent artefact ids

that was created
{

"id": “3fa85f64-
5717-4562-b3fc-
2c963f66afa6”

Request Body:
Request Body:
{
"notification": {
"consentRequestId": "e3c74829-3f82-4f94-959e-e10f57bcd57b", "status":
"GRANTED",
"reason": null,
"consentArtefacts": [
{
"id": "<consent-artefact-id>"
}
]
}
}

Response Body:
Response
Status: 202 Accepted

49
4.3.4 HIE-CM – API for HIU to respond back to consent HIU callback
This API will be invoked by HIU to respond back to HIE-CM when they received notify call
after approve /deny / revoke.

/api/v3/hiu/consent/request/notify.

URL: /api/hiecm/consent/v3/request/hiu/on-notify
Request: POST
Header Parameters:
Property Name Example Value Required Description

REQUEST-ID 18235d89-cb13-479d-ad71- Yes Unique UUID for track the end to

7a57d5f669a8 end request transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request was

initiated, ISO Date time format
represents date and time

X-CM-ID sbx Yes Suffix of the consent manager to

which the request was intended

Body parameters:
Property Name Example Value Required Description
status OK Yes The status of the consent
notify.

50
 consentId 3fa85f64-5717-4562b3fc- Yes The consent artefact
2c963f66afa6 id

error "error": { No The error code and message

if any happened.
"code": "ABDM-1001",

"message": "unable to
connect database"

requestId 3fa85f64-5717-4562b3fc- Yes The request id from the

2c963f66afa6 /hiu/consent/request/notify

Request Body:
Request Body:
{
"acknowledgement": [
{
"status": "OK",
"consentId": "e3c74829-3f82-4f94-959e-e10f57bcd57b"
}
],
"error": {
"code": "ABDM-1001",
"message": "unable to connect database"
},
"response": {
"requestId": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
}
}

Response Body:
Response
Status: 202 Accepted

Error Scenarios:
Scenarios Headers/Body Message

51
To verify when Request ID [ Access Denied
is Blank, null or empty in
header { Code : 403 Forbidden

"key": "REQUEST-ID",
"value": "",

"type": "text"

To verify when invalid [ {

Request-ID is pass in
header { "code": "ABDM-1030: ",

"key": "REQUEST-ID", "message": "Invalid requ est

ID"
"value": "{{$guid}}zxzzxs",
}
"type": "text"

] Code - 400Bad Request

When Timestamp is [ Access Denied

Blank, null or empty in
header. { Code : 403 Forbidden

"key": "TIMESTAMP",

"value": "",

"type": "text"

When invalid Timestamp [ {

is pass in { "code": "ABDM-1016: ",
header
"key": "TIMESTAMP", "message": "Invalid Time
stamp"
"value": "{{$isoTimestamp}}jhgftytgtyu",
}
"type": "text"

}
Code - 400Bad Request
]

52
 To verify when X- CM-ID [ Access Denied
is Blank, null or empty in
header { Code : 403 Forbidden

"key": " X-CM-ID",

"value": "",

"type": "text"

4.3.5 HIE-CM- Consent request status

This API will be called to get the status of the consent request.

URL: /api/hiecm/consent/v3/request/status Request: POST

Header Parameters:
Property Name Example Value Required Description

REQUEST-ID 18235d89-cb13-479dad71- Yes Unique UUID for track the end to end
7a57d5f669a8 request transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request was

initiated, ISO Date time format
represents date and time.

Authorization Gateway Session Token Yes JWT Access token which was issued
by ABDM session API after successful
validation of client id and secret

X-HIU-ID HIU_ID Yes Identifier of the health information

user to which the request was
intended

Body Paramaters:
Property Name Example Value Required Description

consentRequestId 18235d89-cb13-479dad71- Yes Unique UUID for consent request

7a57d5f669a8

Request Body:
Request Body:

53
 {
"consentRequestId": "05f14b1d-4465-453a-8249-1382d79d271d"
}

Response Body:
Response
Code : 200 OK

Error scenarios:

Scenarios Headers/Body Message

To verify when [ Access Denied

Request ID is
{ Code : 403 Forbidden
Blank, null or
empty in header "key": "REQUEST-ID",

"value": "",

"type": "text"

]
To verify when [ {
invalid RequestID
is pass in header { "code": "ABDM-1030: ",

"key": "REQUEST-ID", "message": "Invalid request ID"

"value": "{{$guid}}zxzzxs", }
"type": "text" Code - 400Bad Request

When [ Access Denied

Timestamp
{ Code : 403 Forbidden
is Blank, null or
empty in "key": "TIMESTAMP",
header.
"value": "",

"type": "text"

54
When invalid [ {
Timestamp is
pass in header { "code": "ABDM-1016: ",

"key": "TIMESTAMP", "message": "Invalid Timestamp"

"value": "{{$isoTimestamp}}jhgftytgtyu", }

"type": "text"

} Code - 400Bad Request

]

When X-CM- [ Access Denied

ID is Invalid,
{ Code : 403 Forbidden
Blank, null or
empty in "key": "X-CM-ID",
header.
"value": "sbxdvdfvdf",

"type": "text"

When X-HIU- [ Access Denied

ID is Blank, null
{ Code : 403 Forbidden
or empty in
header. "key": "X-HIU-ID",

"value": "",

"type": "text"

55
 When passing { Callback : {
invalid
"consentRequestId": "002e14ac-13" "error": {
Consent
Request Id } "code": "ABDM-1039: ",

"message": "Invalid Consent req uest id"

},

"response": {

"requestId": "fe717659-f438- 4bda-8f7c-

0ba13e9c5f61"

code - 200 OK

When { [
passing Null
"consentRequestId":null {
Consent
Request Id } "code": "ABDM-9999: ",

"message": "Invalid Consent req uest id"

Code - 400Bad Request

When body {
missing
"code": "ABDM-1064",

"message": "Request body was mis sing"

Code - 400Bad Request

4.3.6 HIE-CM - Consent request on-status (Callback)

This API is used to send the status of consent request back to HIU through HIE-CM URL:
{callback_url}/api/v3/hiu/consent/request/on-status Request: POST Header Parameters:
56
Property Name Example Value Required Description
REQUEST-ID 18235d89-cb13-479dad71- Yes Unique UUID for track the end to end
7a57d5f669a8 request transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request was initiated, ISO
Date time format represents date and time.

X-HIU-ID HIU_ID Yes Identifier of the health information user to

which the request was intended

Authorization Gateway Session Token Yes ABDM Gateway Session Token

Body Parameters:
Property Name Example Value Required Description
consentRequest-id 18235d89-cb13-479dad71- Yes Unique UUID for consent request
7a57d5f669a8

consentRequeststatus “REQUESTED” Yes Current status of consent request

response-requestId aa9e2d8e- Yes Unique UUID for the callback request

c4f647048baba8c365f693d5

resp null
Request Body:
Request Body:
{
"consentRequest": {
"id": "7d52fcd0-a52a-4d82-b9f5-a548e5053088", "status":
"REQUESTED"
},
"error": null,
"response": {
"requestId": "e1f08798-8949-4a23-a04e-fe0054397cf5"
},
"resp": null
}

Response Body: The table below illustrates the response body

Response
Code : 200 OK

57
4.3.7 HIE-CM - Consent request fetch
This API will be called to fetch the consent artifact details.

URL: /api/hiecm/consent/v3/fetch
Request: POST
Header Parameters:
Property Name Example Value Required Description
REQUEST-ID 18235d89-cb13-479dad71- Yes Unique UUID for track the end to end
7a57d5f669a8 request transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request was initiated, ISO
Date time format represents date and time

X-CM-ID sbx Yes Suffix of the consent manager to which the

request was intended

X-HIU-ID HIU_ID Yes Health information user unique ID

Authorization Gateway Session Token Yes JWT Access token which was issued by
ABDM session API after successful
validation of client id and secret

Body parameters:
Property Name Example Value Required Description

58
 consentId 18235d89-cb13- Yes Unique UUID of the validate the consent to
479d-ad717a57d5f669a8 share the data between HIP and HIU

Request Body:
Request Body:
{
"consentId": "d6a83f24-6c96-421e-b8b8-844e5344ef69"
}

Response Body:

Code : 202 OK

Error Scenarios:
Scenarios Headers/Body Message

To verify [ Access Denied

when
{ Code : 403 Forbidden
Request ID is
Blank, null or "key": "REQUEST-ID",
empty in header
"value": "",

"type": "text"

To verify [ {
when
{ "code": "ABDM-1030: ",
invalid
Request-ID is "key": "REQUEST-ID", "message": "Invalid request ID"
pass in header
"value": "{{$guid}}zxzzxs", }

"type": "text"

} Code - 400Bad Request

]

59
When [ Access Denied
Timestamp
{ Code : 403 Forbidden
is Blank, null or
empty in "key": "TIMESTAMP",
header.
"value": "",

"type": "text"

When [ {
invalid
{ "code": "ABDM-1016: ",
Timestamp is
pass in header "key": "TIMESTAMP", "message": "Invalid Timestamp"

"value": "{{$isoTimestamp}}jhgftytgtyu", }

"type": "text"

} Code - 400Bad Request

]

When X- CM-ID [ Access Denied

is
{ Code : 403 Forbidden
Invalid,
Blank, null or "key": "X-CM-ID",
empty in
header. "value": "sbxdvdfvdf",

"type": "text"

When X- [ Access Denied

HIU-ID is Blank,
{ Code : 403 Forbidden
null or empty in
header. "key": "X-HIU-ID",

"value": "",

"type": "text"

60
 When passing { Callback : {
invalid Consent
artefact Id "consentId": "1769c167-0898-43" "error": {

} "code": "ABDM-1080: ",

"message": "Invalid Consent artefa ct id"

},

"response": {

"requestId": "7c4c31da-dfd0-
4348a907c08ea4016cbe"

code - 200 OK

When { [
passing Null
"consentId": null {
Consent
artefact Id } "code": "ABDM-9999: ",

"message": "Invalid Consent artefa ct id"

Code - 400Bad Request

When body {
missing
"code": "ABDM-1064",

"message": "Request body was missi ng"

Code - 400Bad Request

4.3.8 HIE-CM - Consent request on-fetch (callback)

This API is used to send the consent artifact details to HIU through HIE-CM URL: {callback_url}
/api/v3/hiu/consent/on-fetch Request: POST Header Parameters:

61
Property Name Example Value Required Description
REQUEST-ID 18235d89-cb13-479dad71- Yes Unique UUID for track the end to end
7a57d5f669a8 request transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request was initiated, ISO
Date time format represents date and time

X-HIU-ID HIU_ID Yes Health information user unique ID

Authorization Gateway Session Token Yes ABDM Gateway Session Token

Body parameters:
Property Name Example Value Require d Descriptio n

Status GRANTED Yes Current status

consent request

consentId 18235d89-cb13-479d-ad71-7a57d5f669a8 Yes Consent

artefact id

Hip ABDM_HIP No Health

information
provider ID

Patient-id user@abdm Yes The abha address

Purpose-text Care Management Yes Purpose text of

consent request

Purpose-code CAREMGT Yes Purpose code of

consent request

Purpose-refUri www.test.com Yes Purpose refUri of

consent request

patientReference batman@tmh No Patient reference

Id

careContextReference Episode11 No Care context

reference

hiu HIU_ID Yes Health information

user Id

62
Requester-name Smith Yes Name of the
requester

Requester-identifiertype REGN01 Yes Requester

identifier type

Requester-identifiervalue MH1001 Yes Requester

identifier value

Requester-identifiersystem https://www.mciindia.org Yes Requester

identifier system

hiTypes ["Prescription", Yes Type of document

"DiagnosticReport",
"DischargeSummary
"ImmunizationRecord",
"HealthDocumentRecord",
"WellnessRecord",
"OPConsultation"]

PermissionaccessMode VIEW Yes Access mode of

consent

PermissiondateRange "from": "2023-05-09T08:58:09.738Z", Yes Data range of

"to": "2023-05-10T08:58:09.738Z" permission
required

PermissiondateEraseAt 2023-05-25T08:58:09.738Z Yes Date of erase data

Permissionfrequency-value 0 Yes Frequency value

for consent

Permissionfrequencyrepeats 0 Yes Frequency repeats

for consent

Permissionfrequency-unit HOUR Yes Frequency unit for

consent

createdAt 2023-05-25T08:58:09.738Z Yes The date consent

artefact created

lastUpdated 2023-05-25T08:58:09.738Z Yes The date consent

artefact last
updated.

schemaVersion v3 Yes Version

63
 Signature bAJUnf7nY6Yn6A7JbR1ZFHtBmqCjXDW Yes Signature of
consent aretefact
ZaQte
F+XNgEImUchTgA4qp4i5KnUBXYsWuTK
Be
USf1cLFMUXGpQuD9OZzrMqA1PRnEWyh
0
lV9i1bsEm5VMBkeZa0ghQBc4Fj8g==

response-requestId 36de611a-c3ab-4794-b803- Yes Unique UUID for

call back request
5eff9c94ddbf

Request Body:
Request Body:
{
"consent": {
"status": "GRANTED",
"consentDetail": {
"consentId": "d6a83f24-6c96-421e-b8b8-844e5344ef69",
"hip": {
"id": "HIP_ID"
},
"hiu": {
"id": "HIU_ID"
},
"hiTypes": [
"Prescription",
"DiagnosticReport",
"DischargeSummary",
"ImmunizationRecord",
"HealthDocumentRecord",
"WellnessRecord",
"OPConsultation"
],
"patient": {
"id": "xxxxxx@sbx"

64
 },
"purpose": {
"text": "Care Management", "code":
"CAREMGT",
"refUri": "www.abdm.gov.in"
},
"createdAt": "2024-08-09T05:00:03.265Z",
"requester": {
"name": "Dr. Manju",
"identifier": {
"value": "MH1001",
"type": "REGNO",
"system": "https://www.mciindia.org"
}
},
"permission": {
"accessMode": "VIEW",
"dateRange": {
"from": "1924-07-09T12:05:57.151Z",
"to": "2024-07-17T12:05:57.151Z"
},
"dataEraseAt": "2124-12-09T00:00:00.000Z",
"frequency": {
"unit": "DAY",
"value": 1,
"repeats": 0
}
},
"lastUpdated": "2024-08-09T05:00:03.144Z",
"careContexts": [
{
"patientReference": "xxxxxxx@sbx",
"careContextReference": "COCa496bc2f-ca6c-4af5-b973-02e915fd9815"
}
],
"schemaVersion": "v3",
"consentManager": {
"id": "sbx"
}
},
"signature": "pktEFkcXuMBPSCEb7ZbiRAOigEx3i5fvIVNS9CxAfgm7rRF9CoxyhO0OdX9Fe
CzmcobBeiqNdLkiX2eYXdTI1oWvvEnSgMYBXVRi4q9rUgXexJr+04QK6vk4lL2iwu6AfKqPTB8u
3LF4v5kmCTXqdmtlfRof+ue9avukW48yIij19okHYhTw2lOZQ=="
},
"error": null,
"response": {

65
 "requestId": "c0027971-d2d3-4323-8353-881b7c8f7d2f"
},
"resp": null
}

Response Body:
Response
Code : 200 OK

66
5 Data flow
5.1 Overview
The process of Data flow starts once the HIECM has generated Consent artefact (Consent
artefact is generated only if the status of Consent request is “Granted”) and same is notified
to HIP and HIU.
HIU sends pushback URL to HIP via HIECM. HIP now bundles the care context or Health
data of the patient as per FHIR standards and share the data via pushback data URL.
HIECM is notified the status of the data shared both by HIU and HIP.

5.2 Sequence Diagram

67
5.3 API Information Request & Response
5.3.1 Data flow – Data request invoked by HIU

The HIU system initiates data request for a patient’s health information to the HIP against
the relevant consent-artefact, through the CM.

As part of the data request, the HIU’s health repository embeds three key elements within
the health information request:

The consent ID corresponding to the consent artefact against which the information
request is being made.

A data push URL, which is a callback URL that indicators where the information can be
pushed by the HIP’s health repository. This URL can be different from the HIU’s access
URL, provided at the time of registration with the gateway. The HIU can specify a different
URL for the data flow, in order to keep its identity secret to the extent possible.

68
Several parameters such as the date-time range for the requested and a set of encryption
parameters for the HIP repository to encrypt the information. The Elliptic-curve Diffie–
Hellman based encryption standard is used for encrypting health information.

Upon receipt of the data-request, CM assigns a transaction ID (txn-id) for the entire data
flow and communicates this Id to the health repositories of the HIU and the HIP.

The HIU’s health repository relays all this information to the CM through the gateway.
From the CM, the information is relayed to the HIP’s health repository (via the HIE-CM).

URL: /api/hiecm/data-flow/v3/health-information/request

Request: POST

Header Parameters: The table below illustrates the header parameters

Property Example Value Required Description
Name
Authorization Gateway Session Token Yes JWT Access token which was
issued by ABDM session API after
successful validation of client id
and secret

REQUEST-ID b22bc4a6-7894-431e-9d800e289610d0f8 Yes Unique UUID for track the end-

toend request transaction

TIMESTAMP 2024-08-09T05:07:17.151Z Yes Actual time when request was

initiated, ISO Date time format
represents date and time

X-CM-ID sbx Yes Suffix of the consent manager to

which the request was intended

X-HIU-ID HIU_ID Yes Identifier of the health

information user by which the
request was initiated

Body Parameters:

The table below illustrates the body parameters

Property Example Value Required Description
Name

69
Consent ID 18235d89-cb13-479d-ad71-7a57d5f669a8 Yes Valid consent ID, which
HIU must obtain to request
patient data from a
HIP

DateRange [ Yes Date Range against which

{ the consent granted will be
"from": "1924-07-09T12:05:57.151Z", validated.
"to": "2024-07-17T12:05:57.151Z"
}
]

DataPushUrl https://webhook.site/2cfcc184-5d29- Yes This is the URL provided

4e2c974d3e56cbaa5cc1/v3/data/push by HIU to which HIP has to
push the requested health
information record

cryptoAlg “ECDH” ECDH is a key sharing

algorithm, most
commonly used to send
encrypted messages.
ECDH works by
multiplying your private
key by another's public
key to get a shared secret,
then using that shared
secret to perform
symmetric encryption

curve “curve25519” Yes Key exchanges

authentication

expiry 2124-12-09T00:00:00.000Z Yes Actual time by when

dataPushUrl is available

parameters “Ephemeral public key” Yes Encryption and decryption

key

keyValue BFN7KTdOT0jIAExG2A8Jg+01w Yes key agreement protocol

MPWxptiGqwHRVvtiVEsUq2FR7P2 that allows two parties,
UdqZxJyPJSeR6muai21iQhasNxnhh8I5M+g=" each having an
ellipticcurve public–private
key pair, to establish a
shared secret over an
insecure channel

Request Body: The table below illustrates the request body

Request Body

70
{
"hiRequest": {
"consent": {
"id": "004ff8e6-a9d7-4963-822b-d9762179314e"
},
"dateRange": {
"from": "1924-07-09T12:05:57.151Z",
"to": "2024-07-17T12:05:57.151Z"
},
"dataPushUrl": "https://webhook.site/2cfcc184-5d29-4e2c-974d-3e56cbaa5cc1/v3/data/push",
"keyMaterial": {
"cryptoAlg": "ECDH",
"curve": "Curve25519",
"dhPublicKey": {
"expiry": "2124-11-09T00:00:00.000Z",
"parameters": "Curve25519/32byte random key",
"keyValue":
"BCpsBW37KgfLyjxJK0zHHG26hDjxzK368DEO4PapzFhQM0cghZziKuvJh5/anTnHitVHKMn0Owr1HvcH1fm0D pA="
},
"nonce": "0ka0stPfqmXWhX+ODC/iOFMO0PXFdRjBdcEGbv55qqc="
}
}
}

Response Body: The table below illustrates the response body

Response
Code : 202 Accepted

71
5.3.2 Data flow – call back to HIU
This is the callback API for acknowledgment of Health information request of HIU. CM
calls this API when it has validated the Health Information request given the consent id.
Either the hiRequest or error would need to be specified. If the health info request was
valid, then the hiRequest.transactionId specifies the transaction context against which HIP
would send over the data.

URL: {callback_url/api/v3/hiu/health-information/on-request

Request: POST

Header Parameters: The table below illustrates the header parameters

Property Name Example Value Required Description
REQUEST-ID 18235d89-cb13-479d-ad71- Yes Unique UUID for track the end to
7a57d5f669a8 end request transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request was

initiated, ISO Date time format
represents date and time

X-HIU-ID HIU_ID Yes Identifier of the health information

user by which the request was
initiated

Authorization Gateway Session Token Yes ABDM Gateway Session Token

Body Parameters: The table below illustrates the body parameters

Property Name Example Value Required Description
transactionId 18235d89-cb13- Yes Unique UUID for track the end to end request
479dad71-7a57d5f669a8 transaction

sessionStatus “REQUESTED” Yes Status of data transfer request

requestId “f29f0e59-8388-4698- Yes Unique UUID received from HIU while initiating
9fe6-05db67aeac46” the following
hiecm/api/v3/dataflow/healthinformation/request

Request Body: The table below illustrates the request body

Request Body:
72
 {
"hiRequest": {
"transactionId": "3332b62a-1cae-454f-a278-aaf80724f2b6",
"sessionStatus": "REQUESTED"
},
"error": null,
"response": {
"requestId": "b22bc4a6-7894-431e-9d80-0e289610d0f8"
}
}

Response Body: The table below illustrates the request body

Response
Code : 200 OK

Error Scenario:
{
"error": {
"code": "ABDM-1092",
"message": " Invalid or already expired consent artefact id "
},
"response": {
"requestId": "b07737a8-1c79-48cc-9fb4-1476c6bb1197"
}
}

Response
Code : 202 Accepted

73
5.3.3 Notify
This API will be called by HIU and HIP to notify the CM about the status of the data
transfer.

HIP on the transfer of data would send sessionStatus - one of [TRANSFERRED, FAILED]. HIP
would also send hiStatus for each careContextReference - on of [DELIVERED, ERRORED]

HIU on receipt of data would send sessionStatus - one of [RECEIVED, FAILED]. For
example, ERRORED when data was not sent or if invalid data was sent. HIU would also
send hiStatus for each careContextReference - one of [OK, ERRORED].

URL: /api/hiecm/data-flow/v3/health-information/notify Request: POST

Header Parameters: The table below illustrates the header parameters

Property Name Example Value Required Description
REQUEST-ID 18235d89-cb13-479dad71- Yes Unique UUID for track the end to end
7a57d5f669a8 request transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request was initiated, ISO
Date time format represents date and time

X-CM-ID sbx Yes Suffix of the consent manager to which the

request was intended

Authorization Gateway Session Token Yes JWT Access token which was issued by ABDM
session API after
successful validation of client id and secret

Body parameters: The table below illustrates the body parameters

Property Name Example Value Required Description
consentId 7497e59e-fa17-4be3b0b3- Yes Unique UUID of the validate the
5afe4f3b5136 consent to share the data between HIP
and HIU

transactionId 87624e00-21b5-43b1- Yes Unique UUID for track the end to end
8ae7-5adcb743ef7b request transaction

doneAt 024-08-09T08:06:07.883Z Yes Actual time when notification is sent

74
 Notifier [ Yes Entity who is notifying HIE-CM
{
"type": "HIU",
"id": HIU_ID”
}]

statusNotification {"sessionStatus": Yes Detail about the status of the

"TRANSFERRED", transaction will be sent in this section
by HIP/HIU.

"hipId": “HIP_ID",

"statusResponses": [{

"careContextRefer
ence": "9ec54c2f-
2f3541d6982846a93e83564e",

"hiStatus": "OK",

"description": "Care
Management"}]}

sessionStatus “TRANSFERRED” Yes HIU on receipt of data would send

sessionStatus - one of

[TRANSFERRED, FAILED]. For example,

FAILED when if data was not sent or if
invalid data was sent

hiStatus "OK", Yes HIU would also send hiStatus for each
careContextReference - one of [OK,
ERRORED]

Request Body: The table below illustrates the request body

{
"notification": {
"consentId": "97312afb-c6a4-483e-8456-5c9c96beb83f",
"transactionId": "97312afb-c6a4-483e-8456-5c9c96beb83f",
"doneAt": "2024-08-09T08:45:55.984Z",
"notifier": {
"type": " HIU",
"id": "HIU_ID"
},
"statusNotification": {
"sessionStatus": "TRANSFERRED",
"hipId": "HIP_ID",
"statusResponses": [
{
"careContextReference": "9ec54c2f-2f35-41d6-9828-46a93e83564e",
"hiStatus": "OK",

75
 "description": "Care Management"
}
]
}
}}

Response Body: The table below illustrates the response body

Response

Code : 202
Accepted

6 Subscription flow
6.1 Overview
HIU should initiate subscription requests so that it receives notifications/alerts whenever
new information is available for the following categories.

1. LINK - linking of a new Care-context from HIPs against an ABHA address

2. DATA - availability of data against an existing care-context from HIP.

While seeking subscription HIU needs to use the Gateway Subscription APIs identifying
itself as a HIU.

Once user grants subscription to HIU, the HIU will be notified against the subscribed
categories.
• If the subscription category is LINK - HIU should initiate a consent request
for the notified care context. Once the user grants the consent against the
request, HIU can initiate the data-request.
• In case subscription category is DATA - then the HIU should check if any
existing consent request is available (hiType and duration etc.) and use the
same to initiate the data-request.

6.2 Sequence Diagram

76
77
6.3 API Information Request & Response
6.3.1 Users get subscription requests
This is an API will be invoked by the patient/user from the PHR application to fetch his/her
subscribed HIU details.

URL: /api/hiecm/subscription-requests/v3/requests Method: GET

Request Headers:
Property Example Value Required Description
Name
Authorization Gateway Session Token Yes JWT Access token which
was issued by ABDM
session API after
successful validation of
client id and secret

REQUEST-ID 18235d89-cb13-479d-ad71-7a57d5f669a8 Yes Unique UUID for track

the end to end request
transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request

was initiated, ISO Date
time format represents
date and time

78
 X-AUTHTOKEN Login Token Yes JWT Authentication token
which was issued by
ABDM after successful
validation of
username and password

X-CM-ID sbx Yes Suffix of the consent

manager to which the
request was intended

Limit 5 Yes How many items to

return at one time

Offset 5 Yes How many items out

of line

Filters “GRANTED” Yes Query string parameter

restricts the data
returned from your
request

Body Parameters: Not Applicable Request Body:

Not Applicable Response:

Response:
Code: 202 OK

79
 {
"limit": 5,
"size": 0,
"offset": 5,
"requests": [
{
"requestId": "f29f0e59-8388-4698-9fe6-05db67aeac46",
"subscriptionId": "f29f0e59-8388-4698-9fe6-05db67aeac46",
"requestType": "HEALTH_LOCKER",
"status": "GRANTED",
"details": {
"patient": {
"id": "xxxx@sbx"
},
"purpose": {
"text": "abc@abdm",
"code": "string",
"refUri": "string"
},
"hiu": {
"id": "HIU"
},
"hips": [
{
"id": "HIP"
}
],
"categories": [
"LINK"
],
"period": {
"from": "2023-01-18 05:19:33.429",
"to": "2023-01-18 05:19:33.429"
}
}
}

]}

6.3.2 User subscription request initiate

This is the API which will be invoked by the HIU to initiate subscription request to the
patient/user from PHR application

URL: /api/hiecm/subscription-requests/v3/init Method:

Post Request Headers:
Property Example Value Required Description
Name

80
 REQUEST-ID 18235d89-cb13- Yes Unique UUID for track the end to end request
479d-ad717a57d5f669a8 transaction

TIMESTAMP 2022-10- Yes Actual time when request was initiated, ISO Date time
06T10:10:00.587Z format represents date and time

X-CM-ID sbx Yes Suffix of the consent manager to which the request was
intended

Authorization Gateway Session Token Yes JWT Access token which was issued by ABDM session
API after successful validation of client id and secret

Body parameters
Property Example Value Required Description
Name
subscription "purpose": { Purpose of Use - defines what is the purpose of
"text": "Care Management", use of the health information that a HIU is
"code": "CAREMGT", Yes requesting for. The following are subset from
"refUri": "www.abc.com2" http://terminology.hl7.org/ValueSet/v
} 3-PurposeOfUse

Patient "id": "xxxxxxxxx@abdm" Yes Patient ABHA address against which the health
records are linked

Hiu "id": "HIU" Yes

Hips [ NO
{
"id": "HIP_ID",
"name": "HIP_NAME",
"type": "HIP"
}
]

categories [ Yes Locker should initiate subscription request so

"LINK", that it receives notifications/alerts whenever
"DATA" new

] information is available for following

categories.

1. LINK - linking of a new Carecontext

from HIPs
2. DATA - availability against an existing
care-context from HIP

Period { Yes Period for which the subscription is valid.

"from": "2023-04-
04T09:52:39.235Z",
"to": "2023-0420T09:52:39.235Z"
}

81
Request Body
Request Body:
{
"subscription": {
"purpose": {
"text": "Care Management",
"code": "CAREMGT",
"refUri": "www.abdm.gov.in"
},
"patient": {
"id": "xxxxx@sbx"
},
"hiu": {
"id": "HIU_ID"
},
"hips": [
{
"id": "HIP_ID",
"name": "HIP_NAME",
"type": "HIP"
}
],
"categories": [
"LINK",
"DATA"
],
"period": {
"from": "2024-06-01T09:00:00.000Z",
"to": "2124-12-31T09:00:00.000Z"
}
}
}

Response
Response:
Code: 202 Accepted.

6.3.3 User Subscription request initiate – Call Back

This is the API which will be invoked by the HIU to initiate subscription request.

URL: {{call back}}/api/v3/hiu/hiecm/subscription-requests/on-init Method: Post

Request Headers:
Property Example Value Required Description
Name

82
 REQUEST-ID 18235d89-cb13- Yes Unique UUID for track the end-to-end request transaction
479d-ad717a57d5f669a8

TIMESTAMP 2022-10- Yes Actual time when request was initiated, ISO Date time
06T10:10:00.587Z format represents date and time

X-CM-ID sbx Yes

Authorization Gateway Session Token Yes ABDM JWT Token

Body parameters
Property Example Value Required Description
Name
subscription {
Request "id": "34c9b142-8a2c-4f4a-
8d98c305dbdbbcbb"
}

response {
"requestId": "c8bd00d4-58d1-
4d888b88a5f0c5817f06"
}

Response TO HIU in call back url

Response:
{
"subscriptionRequest": {
"id": "34c9b142-8a2c-4f4a-8d98-c305dbdbbcbb"
},
"response": {
"requestId": "c8bd00d4-58d1-4d88-8b88-a5f0c5817f06"
}
}

Code : 202 Accepted

83
6.3.4 Approve Subscription Request
This Api will be invoked by the patient/user from PHR application to approve the
subscription request raised by the HIU

URL: /api/hiecm/subscription-
requests/v3/{{subscription_requestid}}/approve
Method: Post

Request Headers:
Property Example Value Required Description
Name
REQUEST- 18235d89-cb13-479d-ad71-7a57d5f669a8 Yes Unique UUID for track the
ID end to end request
transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request

was initiated, ISO Date time
format represents date and
time

X-CM-ID sbx Yes Suffix of the consent

manager to which the
request was intended

84
 X- Login JWT Token JWT Authentication token
AUTHTOKEN which was issued by ABDM
after successful validation of
username and password

Authorizati on Gateway Session Token Yes JWT Access token which

was issued by ABDM
session API after successful
validation of client id and
secret

Body parameters
Property Name Example Value Required Description
isApplicableForAllHIPs false This value can be false or true. In case
of false this will be notified to all the
HIPs available in the system and in
Yes
case of false this will be notified to the
specific HIP only

includedSources [ Yes Included sources will have the list of hi

{ types
"hiTypes": [
"Prescription",
"DiagnosticReport",
"OPConsultation",
"DischargeSummary",
"ImmunizationRecord",
"HealthDocumentRecord",
"WellnessRecord"
]

Purpose { Yes Purpose for rising the consent

"text": "Care
Management",
"code": "CAREMGT",
"refUri":
"www.abc.com7"
}

Hip [{ Optional For which HIP consent has been raised

"id": "HIP_ID",
"name": "SAI
KRISHNA"
}

Categories [ Categories available

"LINK","DATA"
],

85
 Period { Period time for approving the
"from": "2023-04- subscription
04T09:52:39.235Z",
"to": "2023-
0420T09:52:39.235Z"
}

Excluded sources "excludedSources": [ Optional Depending upon the flag selected as

{ False or True, values need to be
"hiTypes": [ added
"PRESCRIPTION"
],
"purpose": {
"text": "Self
Requested",
"code": "PATRQT",
"refUri":
"www.test.com"
},
"hip": {
"id": "",
"name": "string"
},
"categories": [
"LINK"
],
"period": {
"from": "2023-06-
20T05:19:33.429Z",
"to": "2023-06-
30T05:19:33.429Z"
}
}
] }

Request Body
Request Body:

86
{
"isApplicableForAllHIPs": false,
"includedSources": [
{
"hiTypes": [
"Prescription",
"DiagnosticReport",
"OPConsultation",
"DischargeSummary",
"ImmunizationRecord",
"HealthDocumentRecord",
"WellnessRecord"
],
"purpose": {
"text": "Care Management",
"code": "CAREMGT",
"refUri": "www.abc.com7"
},
"hip": {
"id": "HIP_ID",
"name": "HIP_NAME "
},
"categories": [
"DATA",
"LINK"
],
"period": {
"from": "2023-04-27T04:03:40.079Z",
"to": "2023-04-27T04:03:40.079Z"
}
}
]
} "LINK",
"DATA"
],
"period": {
"from": "2023-04-04T09:52:39.235Z",
"to": "2023-04-20T09:52:39.235Z"
}
} ],
"excludedSources": [
{
"hiTypes": [
"PRESCRIPTION"
],

"purpose": {
"text": "Self Requested",
"code": "PATRQT",
"refUri": "www.test.com"
},
"hip": {
87
 "id": "",
"name": "string"
},
"categories": [
"LINK"
],
"period": {
"from": "2023-06-20T05:19:33.429Z",
"to": "2023-06-30T05:19:33.429Z"
}
}
]}

Response
Response:
{
"subscriptionId": "b6c88154-995b-45b0-b720-838e357c8192",
"message": "Successfully approved Subscription request"
}

Code: 202 Accepted

6.3.5 Approve Subscription – Call back

URL: {{callback}} /api/v3/hiu/subscription-requests/hiu/notify Method: Post
Request Headers:

Property Example Value Required Description

Name
REQUEST- 18235d89-cb13-479d-ad71-7a57d5f669a8 Unique UUID for track
ID the end to end
request transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Actual time when

request was initiated,
ISO Date

time format
represents date and
time

X-CM-ID sbx Suffix of the consent

manager to which the
request was intended

88
 Authorizati Gateway Session Token ABDM Gateway
on Session Token

Body parameters
Property Name Example Value Required Description
SubscriptionRequestId "57ab7ec0-ce1a-4d408cc3-
66172ac3f6ee",

Status GRANTED

Subscription {
"id": "b6c88154-995b- 45b0-
b720-838e357c8192",
"patient": {
"id": "xxxxxxx@sbx"
},

Hiu {
"id": "HIP_ID",
"name": "HIP_NAME",
"type": "HIU"
}

Sources [
{
"hip": {},
"categories": [
"DATA",
"LINK"
]

Period {
"from": "2023-04-
04T09:52:39.235Z",
"to": "2023-
0420T09:52:39.235Z"
}

Response
Response:
{
"notification": {
"subscriptionRequestId": "57ab7ec0-ce1a-4d40-8cc3-66172ac3f6ee", "status": "GRANTED",
"subscription": {
"id": "b6c88154-995b-45b0-b720-838e357c8192",
89
 "patient": {
"id": "xxxxxx@sbx"
},
"hiu": {
"id": "HIU_ID",
"name": "HIU-NAME",
"type": "HIU"
},
"sources": [
{
"hip": {},
"categories": [
"DATA",
"LINK"
],
"period": {
"from": "2024-01-09T09:00:00.000Z",
"to": "2124-12-31T09:00:00.000Z"
}
}
]
}
}
}

90
6.3.6 Subscription Request Hiu – on notify
This is the API that will be invoked by the HIU to notify HIECM that HIU has raised the
subscription request.

URL: /api/hiecm/subscription-requests/v3/hiu/on-notify Method: Post

Request Headers:
Property Example Value Required Description
Name
REQUEST-ID 18235d89-cb13-479dad71- Yes Unique UUID for track the end-to-end request
7a57d5f669a8 transaction

TIMESTAMP 2022-10- Yes Actual time when request was initiated, ISO Date
06T10:10:00.587Z time format represents date and time

X-CM-ID sbx Yes Suffix of the consent manager to which the request
was intended

Authorization Gateway Session Token Yes JWT Access token which was issued by ABDM
session API after successful validation of client id
and secret

Body parameters

91
 Property Name Example Value Required Description
acknowledgement { 1. This is the
"status": "OK", acknowledgement
"subscriptionRequestId": Yes from the HIU
"2b8ddd74-5e5e-475b8778-
21603e05a8b4"
}

response { Yes This is the response ID is used from

"requestId": "a4b51f47f70f- the initiate request ID
4291-9599-
8e39b7893cfc"
}

Request Body
Request Body:
{
"acknowledgement": {
"status": "OK",
"subscriptionRequestId": "2b8ddd74-5e5e-475b-8778-21603e05a8b4"
},
"response": {
"requestId": "a4b51f47-f70f-4291-9599-8e39b7893cfc"
}
}

Response
Response:
Code: 202 Accepted

6.3.7 Deny Subscription Request

This API will be invoke by the patient to deny the subscription request raised by the HIU

URL: /api/hiecm/subscriptionrequests/v3/{{subscription_id}}/deny

Method: Post

Request Headers:
Property Example Value Required Description
Name

92
 REQUEST- 18235d89-cb13-479d-ad71-7a57d5f669a8 Yes Unique UUID for track the
ID end to end request
transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request

was initiated, ISO Date
time format represents
date and time

X-CM-ID sbx Yes Suffix of the consent

manager to which the
request was intended

X- Login JWT Token Yes JWT Authentication token

AUTHTOKEN which was issued by
ABDM after successful
validation of username
and password

Authorizati Gateway Session Token Yes JWT Access token which

on was issued by ABDM
session API after
successful validation of
client id and secret

Body parameters
Property Name Example Value Required Description

Reason
False Yes
Request Body
Request Body:
{
"reason": "Not authorized"
}

Response
Response:
{
"message": "Successfully denied the subscription request"
}

93
 202 Accepted

6.3.8 Deny Subscription – Call Back

This is the API that will be invoked by the patient to deny the subscription request raise by
the HIU

URL: {{ call back}}/api/v3/hiu/subscription-requests/hiu/notify Method: Post

Request Headers:
Property Example Value Required Description
Name
REQUEST- 18235d89-cb13-479d-ad71-7a57d5f669a8 Yes Unique UUID for track the end to
ID end request transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request was

initiated, ISO Date time format
represents date and time

X-CM-ID sbx Yes Suffix of the consent manager to

which the request was intended

Authorizati Gateway Session Token ABDM Gateway Session Token

on

Body parameters
Property Name Example Value Required Description

94
 notification {

"subscriptionRequestId":
"5f3ed8a6-7d1f-
48cbbbb0b87313798526",

"reason": "Not required",

"status": "DENIED"

Response
Response:
{
"notification": {
"subscriptionRequestId": " 5f3ed8a6-7d1f-48cb-bbb0-b87313798526", "reason":
"Not authorized1",
"status": "DENIED"
}
}

202 Accepted

6.3.9 Edit Subscription

This is the API that will be invoked by the patient/user from PHR application to edit the
subscription.
95
 URL: /api/hiecm/subscription-
requests/v3/patients/{{approved_subscription_id}} Method: PUT
Request Headers:
Property Name Example Value Required Description
REQUEST-ID 18235d89-cb13-479dad71- Yes Unique UUID for track the end to end
7a57d5f669a8 request transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request was initiated,

ISO 8601 represents date and time by
starting with the year, followed by the
month, the day, the hour, the minutes,
seconds and milliseconds

X-AUTH-TOKEN Login Token Yes JWT Authentication token which was

issued by ABDM after
successful validation of username and
password

Authorization Gateway Session Token Yes JWT Access token which was issued by
ABDM session API after successful
validation of client id and secret

X-CM-ID sbx Yes Suffix of the consent manager to which

the request was intended

Body Parameters:
Property Name Example Value Required Description
hiuId MOHAN-HIU HIU who raised the
request.

Yes

96
subscriptionEditAndApprovalRequest "includedSources": [ Yes Hi types, purpose should
{ be mentioned while
"hiTypes": [ editing the subscription

"PRESCRIPTIONs"
],
"purpose": {
"text": "Care
Management",
"code": "",
"refUri":
"www.amazon.com"
},

Hip { Yes For which HIP requested

"id": was initiated
"HIP_ID",
"name":
"HIP-NAME"
},

“categories" LINK Yes Categories can be DATA

and LINK

Period { Yes From when the

"from": subscription should be
"2023-06- available
24T04:03:40.079Z",
"to": "2023-
06-27T04:03:40.079Z"
}

excludedSources [ optional
{
"hiTypes": [

"PRESCRIPTION"
],
"purpose": {
"text": "Self
Requested",
"code":
"PATRQT",
"refUri":
"www.amazon.com"

97
 },
"hip": {
"id": "HIP-ID",
"name":
"HIP-NAME"
},
"categories": [
"LINK"
],
"period": {
"from":
"2023-06-
23T05:19:33.429Z",
"to": "2023-
06-30T05:19:33.429Z"
}
}
]
} }

Request Body:
Request Body:
{
"hiuId": "HIU_ID",
"subscriptionEditAndApprovalRequest": {
"isApplicableForAllHIPs": true,
"includedSources": [
{
"hiTypes": [
"DiagnosticReport",
"Prescription",
"ImmunizationRecord",
"DischargeSummary",
"OPConsultation",
"HealthDocumentRecord",
"WellnessRecord"
],
"purpose": {
"text": "Care Management",
"code": "CAREMGT",
"refUri": "www.abdm.gov.in"
},
"categories": [
"DATA",
"LINK"
],
"period": {
"from": "2024-01-09T09:00:00.000Z",
"to": "2123-12-31T09:00:00.000Z"

98
 }
}
],
"excludedSources": []
}
}

Response
Response:
Code: 202 Accepted
{
"subscriptionId": "f9ca6ad7-ba8f-4257-b7ad-935a82a94480",
"message": "Successful creation of Subscriptions"
}

6.3.10 Edit Subscription – call back

This is the API that will be invoked by the patient to deny the subscription request raise by
the HIU

URL: {{ call back}}/api/v3/hiu/subscription-requests/hiu/notify Method: Post

Request Headers:

Property Example Value Required Description

Name
REQUEST- 18235d89-cb13-479d-ad71-7a57d5f669a8 Yes Unique UUID for track the end
ID to end request transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request was

initiated, ISO Date time format
represents date and time

X-CM-ID sbx Yes Suffix of the consent manager

to which the request was
intended

Authorizati Gateway Session Token ABDM Gateway Session Token

on

Body parameters
Property Name Example Value Required Description

99
 notification {

"subscriptionRequestId":
"5f3ed8a6-7d1f-
48cbbbb0b87313798526",

"reason": "Not required",

"status": "DENIED"

Response
Response:
{
"notification": {
"subscriptionRequestId": " 5f3ed8a6-7d1f-48cb-bbb0-b87313798526", "reason":
"Not authorized1",
"status": "DENIED"
}
}

202 Accepted

6.3.11 Subscription HIU –notify

This is the API that will be invoked by the HIU to notify by HIECM about the for link new
record.

URL: {{ call back}} /api/v3/hiu/subscription/notify

100
 Method: POST
Request Headers:
Property Name Example Value Required Description
REQUEST-ID 18235d89-cb13-479dad71- Yes Unique UUID for track the end to end
7a57d5f669a8 request transaction

TIMESTAMP 2022-10-06T10:10:00.587Z Yes Actual time when request was initiated,

ISO 8601 represents date and time by
starting with the year, followed by the
month, the day, the hour, the minutes,
seconds and milliseconds

Authorization Gatteway Session Token Yes ABDM Gateway Session Token

X-CM-ID sbx Yes Suffix of the consent manager to which

the request was intended

Body Parameters:
Property Name Example Value Required Description
Event - "57ab7ec0-ce1a-4d408cc3-
SubscriptionRequestId 66172ac3f6ee",

Event-id 17fb377f-8675-402f-9c1b-
3e8857ef1fc8

Event- published "2024-08-09 09:03:07.059"

Event- category "LINK"

Content- patient {
"id": "abha@sbx"
}

Content- hip {
"id": "HIP_ID"
}

Content- careContexts [
{
"patientReference":
"xxxxxx@sbx",

"careContextReference":
"db4423d5-62f7-44f887d2-
5fcb25c5a814"
}

Content- hiTypes "Prescription"

Request Body:
Request Body:
101
{
"event": {
"id": "17fb377f-8675-402f-9c1b-3e8857ef1fc8",
"published": "2024-08-09 09:03:07.059",
"subscriptionId": "b6c88154-995b-45b0-b720-838e357c8192",
"category": "LINK",
"content": {
"patient": {
"id": "abha@sbx"
},
"hip": {
"id": "HIP_ID"
},
"contexts": [
{
"careContexts": [
{
"patientReference": "abah@sbx",
"careContextReference": "db4423d5-62f7-44f8-87d2-5fcb25c5a814"
}
],
"hiType": "Prescription"
}
]
}
}

102
103
6.3.12 Subscription HIU –On-notify
This is the API that will be invoked to HIU to notify HIECM about the link new record
notification received.

URL: /api/hiecm/subscription-requests/v3/hiu/care-context/on-notify Method: Post

Request Headers:
Property Example Value Required Description
Name
REQUEST-ID 18235d89-cb13- Yes Unique UUID for track the end-to-end request
479d-ad717a57d5f669a8 transaction

TIMESTAMP 2022-10- Yes Actual time when request was initiated, ISO Date time
06T10:10:00.587Z format represents date and time

X-CM-ID sbx Yes Suffix of the consent manager to which the request
was intended

Authorization Gatteway Session Token Yes JWT Access token which was issued by ABDM
session API after successful validation of client id
and secret

Body parameters
Property Name Example Value Required Description
acknowledgement { This is the acknowledgement from the
"status": "OK", HIU
"eventId": "2b8ddd74- Yes
5e5e-475b-877821603e05a8b4"
}

Response { Yes This is the response ID is used from the

"requestId": "a4b51f47f70f- initiate request ID
4291-9599- 8e39b7893cfc"
}

Request Body
Request Body:
{

104
 "acknowledgement": {
"status": "OK",
"eventId": "2b8ddd74-5e5e-475b-8778-21603e05a8b4"
},
"response": {
"requestId": "a4b51f47-f70f-4291-9599-8e39b7893cfc"
}
}
Response
Response:
Code: 202 Accepted

7 API listing
No. Flow Serial v3 API Description
API will be invoked by the
patient/user from the PHR
application to fetch his/her
Subscripti /api/hiecm/subscriptionrequests/v3/requests?statu subscribed HIU details
on 4.1 s=ALL&limit=10&offset=0
API which will be invoked
by the HIU to initiate
subscription request to the
patient/user from PHR
4.2 /api/hiecm/subscriptionrequests/v3/init application

API which will be invoked

by the HIU to initiate
subscription request to the
patient/user from PHR
application.
In these two calls back will
be received one by the HIU
that request has been
raised with the subscription
request id and other will be
{{call received by the patient if
back}}/api/v3/hiu/hiecm/s ubscription- patient is registered in the
4.3 requests/oninit PHR app/health locker

105
 API that will be invoked by
the HIU to notify HIECM
that HIU has raised the
4.4 /api/hiecm/subscriptionrequests/v3/hiu/on-notify subscription request

Api will be invoked by the

patient/user from PHR
application to approve the
/api/hiecm/subscriptionrequests/v3/{subscription_r subscription request raised
4.5 equestid}/approve by the HIU

{{callback}} HIECM will notify to the

/api/v3/hiu/subscriptionrequests/hiu/notify HIU about subscription
request raised by the HIU
4.6 is approved

api will be invoke by the

HIU to notify HIECM about
the subscription request
has been approved or
4.7 /api/hiecm/subscriptionrequests/v3/hiu/carecontext/onnotify denied
api will be invoke by the
HIU to notify HIECM about
the subscription request
has been approved or
4.8 /api/hiecm/subscriptionrequests/v3/{subscription_i d}}/deny denied
{{ call api will be invoke by the
back}}/api/v3/hiu/subscript ion-requests/hiu/notify patient to deny the
subscription request raise
4.9 by the HIU

/api/hiecm/subscriptionrequests/v3/patients/{subs API will be invoked by the

cription_id} patient/user from PHR
application to edit the
4..10 subscription.

Consent /api/hiecm/consent/v3/req uest/init API used to raise

Flow consent request
4.11
{callback}/api/v3/hiu/cons ent/request/on-init Callback API used to
4.12 notify hiu
/api/hiecm/consent/v3/req uest/status API used to fetch the
status of consent
4.13 request
{callback_url}/api/v3/hiu/c onsent/request/on-status Callback api is used to
give the response of
4.14 status
/api/hiecm/consent/v3/fetc h API used to fetch the
consent details
4.15
{callback_url}
/api/v3/hiu/consent/onfetch Callback api used to give
4.16 a response of fetch api

106
 /api/hiecm/dataflow/v3/healthinformation/request This api indicates the
exchange of health data
request from HIU to HIP
Data flow 4.17
callback API for
acknowledgment of
Health information
request of HIU. CM calls
this API when it has
validated the Health
Information request
given the consent id. •
Either the
hiRequest or error would
need to be specified. If
the health info request
was valid, then the
hiRequest.transactionId
specifies the transaction
context against which HIP
would send over the data
4.18 {callback_url/api/v3/hiu/he alth-information/onrequest
API will be called by HIU
and HIP to notify the CM
about the status of the
data transfer.

HIP on the transfer of data

would send sessionStatus -
one of [TRANSFERRED,
FAILED]. HIP would also
send hiStatus for each
careContextReference - on
of
[DELIVERED, ERRORED]
•
HIU on receipt of data
would send sessionStatus -
one of [RECEIVED, FAILED].
For example, ERRORED
when data was not sent or
if invalid data was sent.
HIU would also send
hiStatus for each
careContextReference -
one of [OK, ERRORED].
4.19 /api/hiecm/dataflow/v3/healthinformation/notify

7 Error codes listing

Code Error

ABDM-1000 Unable to connect the database

107
ABDM-1001 No data found

ABDM-1002 Integrity violation

ABDM-1003 Email Gateway is unavailable

ABDM-1004 SMS Gateway is unavailable

ABDM-1005 Invalid receiver

ABDM-1006 Bad Request, invalid request Body

ABDM-1007 Connection failed due to timeout

ABDM-1008 SMS service currently disabled

ABDM-1009 Email service currently disabled

ABDM-1010 Validation failed

ABDM-1011 Gateway database unavailable

ABDM-1012 No records found against the ABHA Address

ABDM-1013 Invalid ABHA Number

ABDM-1014 Invalid Mobile Email

ABDM-1015 Invalid Response

ABDM-1016 Invalid TimeStamp

ABDM-1017 Invalid TransactionId

ABDM-1018 Share Profile database unavailable

ABDM-1019 Dependent Service Unavailable

ABDM-1020 Unknown database

ABDM-1021 Lack of required priviledges

ABDM-1022 Too many requests

ABDM-1023 Invalid User

ABDM-1024 Dependent service unavailable

ABDM-1025 Invalid ServiceId

ABDM-1026 Invalid Link Token

You are blocked. Please try again after 24 hours.

ABDM-1027
ABDM-1028 HIP is unavailable

ABDM-1029 Redis server is unavailable

ABDM-1030 Invalid request ID

ABDM-1031 Invalid request

ABDM-1032 Invalid header

ABDM-1033 HIU is unavailable

ABDM-1034 Notification service unavailable

ABDM-1035 Invalid HIP ID

108
ABDM-1035 OTP does not matched

ABDM-1036 Data does not matched

ABDM-1037 Counter and Care context count mismatch

ABDM-1038 ABHA address and Link token mismatch

ABDM-1039 Invalid Consent request id

ABDM-1040 Invalid HIU ID

ABDM-1041 Invalid Acknowledgement

ABDM-1042 Provider Mandatory

ABDM-1043 ABHA Address does not match with KYC details.

ABDM-1044 Broadcast Failed

ABDM-1045 Database Access is restricted

ABDM-1046 Invalid Purpose

ABDM-1047 Purpose does not exist

ABDM-1048 Timeout

ABDM-1049 Invalid Profile Share Intent Keys

ABDM-1050 Invalid Profile Share Metadata Keys

ABDM-1051 Invalid ABHA Number or ABHA Address

ABDM-1052 Invalid TransactionId or response's requestId

ABDM-1053 Data already exists

ABDM-1054 Invalid Subscription Request Id

ABDM-1401 HIP is not available

ABDM-1402 Acknowledgement is not received from HIP

ABDM-9999 Unknown exception

ABDM-1061 Consent artefact expired

ABDM-1062 Consent Not granted

ABDM-1063 Date Range given is invalid

ABDM-1064 request with this request id already exists

ABDM-1017 Invalid TransactionId

ABDM-1109 ABHA DB service unavailable

ABDM-1108 Notification DB service unavailable

ABDM-1205 Document DB Gateway is unavailable

ABDM-1034 Notification service unavailable

ABDM-1029 Redis server is unavailable

ABDM-1202 Document Gateway is unavailable

ABDM-1200 LGD Gateway is unavailable

ABDM-1201 IDP Gateway is unavailable

109
ABDM-9999 Unknown exception

This ABHA Address already exists. Please create with

ABDM-1101 unique ABHA Address

ABDM-1006 Invalid combinations of scopes

You have requested multiple OTPs Or Exceeded maximum

number of attempts for OTP match in this transaction.
ABDM-1100 Please try again in 30 minutes.

ABDM-1006 Bad Request, invalid request Body

ABDM-1110 ABHA User not found.

ABDM-1111 Mobile number not found.

ABDM-1112 Aadhaar details not found.

ABDM-1113 Login via Password is not allowed

ABDM-1114 Login via ABHA Number OTP is not allowed

ABDM-1115 Login via Aadhaar OTP is not allowed

ABDM-1102 Mobile number verification is pending.

ABDM-1203 {errors coming from DL gateway(Nepix)}

ABDM-1204 {errors coming from Aadhaar gateway(UIDAI)}

110