This document outlines a technical architecture for the consented sharing of personal health information through health data consent managers (CMS) and addresses health information flows between health information providers (HIPs) and health information users (HIUs). It emphasizes principles such as privacy by design, scalability, and user centricity, aiming to facilitate a system applicable globally despite being developed as part of India's national health stack initiative. The architecture includes layers for discovery, consent, and data flow, driven by the need to improve user control and interoperability in health information exchange.

1. Health Information Flows
Technical Standards
Sequence #:
Version:​ 0.5
Author: ​iSPIRT
Track: ​Standard
Maturity Level:​ Draft
Type:​ Technical Specifications
Status:​ Draft
Jul 4, 2020
Abstract​: This document presents the architecture for consented sharing of Health Information between
Health Information Providers and Health Information Users via a new type of entity called Health Data
Consent Managers (CMs)​. It describes the architecture at a high level and outlines the flows that are
covered by the architecture. The current version is focused on ​personal health information flows ​which
involve exchange of individual health data only and to the creation of ​personal health records (PHRs)​.

2. Version History
Version Date Comments
0.5 04/07/2020 Preliminary Draft

3. Table of Contents
Table of Contents 3
1 Introduction 5
1.1 Guiding Principles of our Architecture 6
2 High-level architecture 7
2.1 Terms and Definitions 7
2.2 Architecture 9
2.3 Roles of different entities 11
2.4 User Interactions 13
2.4.1 User interactions with HIPs and HIUs 13
2.4.2 Registration with CMs 15
2.4.2.1 Structure of a PHR ID 15
2.4.2.2 Multiplicity of PHR IDs 15
2.4.2.2 PHR ID retrieval and lookup 16
2.4.3 Discovery and Linking 16
2.4.3.1 CM-initiated discovery and linking 16
2.4.3.2 HIP-initiated linking 17
2.4.4 Consent 17
2.5 Health information (HI) types 17
3 APIs and Flows 18
3.1 Registries and related functionalities 18
3.1.1 Onboarding HIPs and HIUs using registries 18
3.1.2 Onboarding CMs and health repositories 19
3.1.2.1 CM registration 19
3.1.2.1 Repository registration 20
3.1.3 Gateway peering 21
3.1.4 Profile updation of different entities 21
3.2 APIs 21
3.2.1 gateway APIs 22
3.2.1.1 registry APIs 22
3.2.1.2 gateway-cm APIs 22
3.2.1.3 gateway-repository APIs 24
3.2.1.4 monitoring APIs 26
3.2.2 repository APIs 26
3.2.2.1 HIP-targeted APIs 26

4. 3.2.2.2 HIU-targeted APIs 27
3.2.3 cm APIs 27
3.3 Flows 29
In presenting the various flows, we use the following conventions: 29
3.3.1 PHR ID retrieval and lookup 29
3.3.2 Discovery flow 31
3.3.3 CM-initiated linking flow 31
3.3.4 HIP-initiated linking flow 32
3.3.5 Consent flow 33
3.3.5.1 Consent request from an HIU to a CM 33
3.3.5.2 Consent notification from a CM to an HIU 34
3.3.5.3 Fetching a consent artefact from a CM 35
3.3.5.4 Consent notification from a CM to an HIP 36
3.3.6 Data flow 37
4 Non-functional Requirements 38

5. 1 Introduction
A ​Health Information Flow ​(HIF)​ ​is a mechanism of transferring digital health information about users
from one organizational entity to another. An entity that generates or collects health information about
users and stores it in digital form is referred to as a ​Health Information Provider​ (HIP). HIPs could be
hospitals, diagnostic labs, pharmacies or other organizations which run software systems to collect,
process and store health information of individuals. An entity that seeks health information about users
from HIPs is referred to as a ​Health Information User​ (HIU). HIUs could be hospitals, insurers, medical
research companies and a host of other organizations who are interested in processing health-related
information gathered from different sources. A health information flow is a mechanism of moving health
information from an HIP to an HIU.
Some health information flows involve the transfer of ​personal ​information i.e. information which
contains personally identifiable information of users or can easily be linked to a single user. We refer to
such flows as ​personal health information flows (personal HIFs). ​When an HIU aggregates information
about a single user from multiple different HIPs using personal HIFs, it leads to the creation of a ​personal
health record (PHR)​ ​of the user: a dynamically-generated collection of digital health documents about
the user sourced from multiple HIPs. A doctor seeking to treat a patient may ask for health information
of that user generated at different diagnostic labs or hospitals in the past and as such, needs access to a
PHR of the user. Many applications require processing aggregate health information about their users
and as such, have the need to access the PHR of their users.
HIFs may involve transfer of information that is not personally-identifiable as well. Such information may
be non-personal by its very nature (e.g., profile details of a hospital that collects health information of
users) or that has been made non-personal by applying anonymization techniques on personal health
information. Such HIFs are referred to as ​non-personal HIFs​.
This document outlines a technical architecture for implementing HIFs at national scale, keeping in mind
evolving laws around personal data and data privacy and evolving technology frameworks for sharing
and gathering data across multiple software systems. Although our architecture has been developed in
India as part of the National Health Stack initiative, the design is general enough to be applicable
anywhere in the world. We outline the different components and flows in our architecture and lay down
the technical standard to be used by health IT systems to participate in a real-world implementation of
the architecture. The document is mainly focused on personal HIFs although our architecture and
approach can also be applied to non-personal HIFs.
Project EKA is a community initiative that is creating an open-source implementation of different
components of our architecture and reference solutions. Project EKA also hosts detailed API
specifications for the APIs that are defined in our technical standard. More information about project
EKA is here: ​https://projecteka.github.io/

6. 1.1 Guiding Principles of our Architecture
Before we describe our architecture, we present the core guiding principles upon which the architecture
is based.
1.​ ​Diversity:​ We aim to design a framework that will enable ecosystem innovation around health
information flows, rather than provide a point solution for health information sharing. Our design should
allow a diverse set of existing or new health IT systems, with diverse definitions of and approaches to
manage health information, to participate in HIFs and to do this with ease.
2.​ ​Evolvability: ​We want our design to be simple and easily evolvable: it should be possible for
capabilities to be built incrementally while allowing for rapid adoption in today’s world. It should also be
possible to monitor systems at scale, so that policy corrections can be suitably informed. The design
should be adaptable to future policies around health data and future technology frameworks for data
exchange.
3.​ ​Privacy By Design​: ​User information needs to be protected from abuse and compromise and privacy
must be built into the architecture by design. Storage of and control on user information should be
d​ecentralised as far as possible and principles of transparency and choice should be applied in processes
surrounding collection and sharing of personal information. In defining new software systems and
processes, personal data collection should be kept to the minimum possible levels.
4.​ ​Scalability​: ​Health information flows enabled by our architecture should be able to handle data of
billions of users. ​Not only the technology architecture but even the processes around implementing the
architecture (registering new entities, maintaining existing ones, conducting audits, handling grievances)
should be implementable at the scale of a large country like India.
5.​ ​User Centricity​: ​The design should enable simple and powerful user interfaces to develop around it
and address the needs of a diverse set of users, including those who may not be literate, technologically
or textually. Users should have significant control on how their information is shared in personal health
information flows, in line with evolving laws around data privacy and security.
6. Transparency and Accountability​: We attempt to ensure ​Public Open Data​ is available via APIs. Access
to open data will ensure high-quality analytics, accurate fraud detection, shorter cycles for system
improvement and high responsiveness to user needs. We also attempt to enable strong data-driven
governance practices to be put in place for various actors that the architecture incorporates.

7. 2 High-level architecture
2.1 Terms and Definitions
Health Information
Flow (HIF)
A health information flow (HIF) refers to any interaction in which digital health
data about one or more users is shared by one entity with another entity. This
includes both personal health information flows, in which the said data
includes personal identifiable information and non-personal health information
flows, which includes all other types of information flows, including the release
of anonymized data and open data by health information systems.
Health Information
Provider (HIP)
A health information provider (HIP) is an entity that collects or generates digital
health information and stores it in a software system. These could be clinical
establishments like hospitals, primary or secondary health care centres, nursing
homes, diagnostic centres, pharmacies, Government health programs and may
also include healthcare technology companies which provide services to
healthcare providers or end-users.
Health Information
User (HIU)
A health information user (HIU) is an entity that seeks digital health
information from HIPs, in order to provide services to the user. These include
hospitals, clinics, healthcare technology companies, organizations working on
health analytics, insurers, medical researchers, Government entities. HIUs must
also run a software system for accessing and/or storing health information.
An important class of an HIU is a company or organization that provides an
application to create longitudinal health records of users and to maintain them
in a trusted location (e.g., on users’ personal devices or on a user-trusted cloud
service). We refer to such an application as a ​personal health locker ​and the
corresponding provider as a ​personal health locker provider​.
Personal Health
Record (PHR)
A personal health record of a user is any collection of health documents or files
pertaining to that user (i.e. with personally identifiable information linked to
that user), which is generated and stored at multiple HIPs. An HIU can create a
PHR of a user by aggregating personal health information about that user via
personal HIFs applied to multiple HIPs. Thus, a personal health record of a user
is a ​dynamically-defined concept​: it may include all or some of the full set of
health records of a user stored in HIP systems and it is created in real time
based on requests generated by an HIU. A PHR may have meta-information
attached to it which enables the consuming entity (the HIU) to view the
contents of the PHR in a human-readable manner.
Consent Manager
(CM)
A consent manager is an entity that acts as a consent collector for the user and
mediates personal HIFs from HIPs to HIUs. Our architecture allows multiple

8. entities to play the role of a CM and each must have its own front-end (a
mobile app, a Web app, or a human agent who interfaces with a mobile/Web
app) for interacting with users. A CM cannot access health information of users,
even in encrypted form, unless it is also an HIU and accesses information in
that capacity. Its role is primarily to enable consent collection, based on which
data is shared from HIPs to HIUs. It also enables HIUs to discover the different
sources (HIPs and their software systems) from which user information can be
shared. Consent managers are a key mechanism for ensuring ​privacy by design
in our architecture.
Consent Artefact A consent artefact is a machine-readable digital file that specifies the
parameters of data sharing that a user consents to in a personal HIF. These
parameters include the names of the entities involved in data sharing (HIP,
HIU), the duration of consent, the type of data access that is permitted, the
purpose of data sharing and others. Consent artefacts are generated by
consent managers (CMs) and shared with HIUs and HIPs once consent
collection is complete. Each consent artefact contains a digital signature which
ensures that the consent parameters cannot be modified by HIUs or HIPs and
thus addresses the threats of over-sharing of data and changes in access
permissions by any of these entities.
The notion of a consent artefact is developed in a ​technical standard​ released
by the ​Ministry of Electronics and Information Technology (MEITY)​. In the
current standard, we use consent artefacts that are digitally signed by the
consent collector, which is the consent manager in our architecture. Consent
artefacts also form a key ​privacy by design ​feature of our architecture.
User The term “user” refers to any individual who is availing the services of an HIP or
an HIU. Users maintain health records with HIPs in which their digital health
information is stored. Users must register with CMs in order to be able to give
consent to HIUs and enable personal HIFs to occur. This registration process
also results in creation of a user account at the CM and an ID referred to as the
user’s ​PHR ID​.
Gateway A gateway is a cloud-hosted software system that enables HIPs, HIUs, and CMs
to connect with each other and exchange information. Gateways ensure
interoperability between software systems run by these entities and, in
particular, enable any HIU, any HIP, and any CM (whose software systems
implement the standardized APIs defined in this document) to communicate
with any other entity in the ecosystem ​without the need of unilateral contracts
with each other​. Gateways are thus the key mechanism for ensuring ​scalability
of our architecture. We also envision gateways to play the role of enrolling,
monitoring and auditing different entities in the HIF ecosystem in a
semi-automated manner; thus, they are also a key vehicle for our design
principle of ​transparency and accountability​. Gateways communicate with
each other, which allows HIUs/HIPs/CMs connected in one gateway’s network
to interact with those on another’s network.

9. Gateway Provider A gateway provider is an entity that runs a gateway. Gateway providers are
envisaged to be regulated entities and only 1-2 gateway providers may operate
at country scale. Gateway providers do not directly interface with users.
Health Repository
(​erstwhile referred
to as​ Data Bridge)
A health repository is a software system that enables HIPs and HIUs to connect
to a gateway and through that, to other HIPs/HIUs and CMs in the HIF
ecosystem. These software systems can be built by HIPs/HIUs themselves or by
other software service providers. Repositories implement standardized APIs
which are essential for communicating with other entities in the ecosystem.
They may also provide storage solutions where health information obtained by
HIUs/HIPs can be reliably stored.
Health Repository
Provider (HRP)
A health repository provider is an entity that runs a health repository. Each
such provider may provide services to one or more HIPs/HIUs on one side and
may enable communication with one or more gateways on the other side.
2.2 Architecture
The Health Information Flows (HIF) architecture uses a layered approach to health information sharing
wherein we decouple the three essential components of the process:
1. The ​discovery of health information​: ​Before HIUs can obtain and aggregate health information
about users, they need to be able to discover where the information resides. In our architecture,
consent managers enable this discovery process for ​personal​ health information flows. For each
user, a CM obtains and maintains meta-information like the names of different HIPs where a
user’s health information was created and descriptors of such information like labels given to
different health records kept by the HIP. This happens through the execution of a ​“​discovery
flow​” ​(in which the meta-information is discovered by the CM) and a ​“​linking flow​” ​(in which
authorization is given by the user or the HIP to store the meta-information at the CM).
2. The ​consent for sharing health information​: ​Once the sources and types of a user’s personal
health information is known, an HIU needs to obtain consent from the user to be able to fetch
that information. In our architecture, CMs enable the process of consent collection as well. We
define the notion of a “​consent flow​” in which a consent request is generated by an HIU
software system, consent is gathered by a CM application, and post that, a ​consent artefact​ is
created and shared with the HIU and HIP.
3. The ​flow of health information: ​Once consent for fetching health information has been
obtained, the HIU can fetch health information from the HIP, potentially multiple times, as per
the terms in the consent artefact, and form users’ personal health records (PHRs). This is what
we refer to as the “​data flow​”. In our architecture, the request for any personal health
information from an HIU to an HIP is mediated by the CM but ​the information flows directly from
the HIP to the HIU​, without any involvement of the CM.

10. The following diagram shows the various components of our architecture and their interactions in the
health information flow ecosystem.
Figure 1: The HIF architecture
The diagram depicts one possible configuration in which the different components may be arranged.
There is a single gateway in this depiction and four health repositories, two that interface with a set of
HIPs (on the left), and two others that interface with a set of HIUs (on the right). Each hospital/lab
information management system is a software system that is used by multiple physical hospitals/labs.
“Aggregator software” refers to any kind of software system which serves multiple different clinical
establishments like labs and clinics and enables services like patient management, EMR, e-prescriptions.
While health repositories are shown as being distinct from the HIP/HIU software systems, they could be
different modules in the same software system.
The diagram shows two consent managers that interface with users via their respective user interfaces.
In practice, there could be several consent managers, which will allow for different user segments to be

11. served differently. For example, beneficiaries of Government programs like PM-JAY could be served by a
CM which enables illiterate or semi-literate users to give consent in an assisted manner, whereas users
of higher socio-economic strata may be served by a CM which offers a mobile app for gathering consent
directly from users. Even within one user segment, it is valuable to have multiple CMs serving that
segment; this increases choice for the users and spurs innovation in the area of consent management.
As discussed earlier, users can use personal health lockers for long-term storage of their health
information aggregated from different HIPs. One personal health locker is shown in the diagram. Health
lockers interface with users one side and with the gateway on the other side. The actual storage solution
used by health lockers to store health information may be managed by the locker provider itself or
externally-hosted (e.g., a personal health locker may just be a software service that stores health
information on users’ smartphones). Some health locker providers may provide both storage and
consent management services and thus play the dual role of locker provider as well as consent manager.
Important: ​An entity that plays the role of HIU in one health information flow may play the role of HIP in
another health information flow. Depending upon the consent given by a user, an HIU can aggregate
health information about the user ​and store that information in its own systems ​(for a period of time
specified in the consent artefact). This enables the HIU to serve as an information provider to other HIUs
seeking that information and hence become an HIP to such HIUs. Indeed, for an ecosystem to develop
around our architecture, it is valuable for the following principle to be enforced:
Principle of Reciprocity: ​Every HIU that aggregates personal health information of users from other
entities and stores that information (without violating user consent) must serve as an HIP to other
HIUs who seek that information.
The enforcement contours of this principle will be determined by accompanying privacy laws and is
beyond the scope of the architecture document.
It is particularly valuable for personal health locker providers to play the role of HIPs to other HIUs.
Health lockers provide a long-term storage solution for health information of users, which even HIP
software systems or health repositories may not offer and over time, personal health lockers will likely
become a more reliable source of information (for ​personal HIFs​) than these other systems.
2.3 Roles of different entities
Below, we summarize the roles played by entities that are unique to the HIF architecture i.e. consent
managers, gateway providers and health repository providers.
1. CMs: ​Consent managers are neutral, regulated, user-facing utilities whose primary role is to
collect consent from users for sharing personal health information from HIPs to HIUs. Other
than enabling consent collection and providing the desired user interface for it, CMs play a few
other crucial roles in our architecture which are listed below.
● Discovery of health information​: CMs help HIUs discover users’ health information and

12. they maintain meta-information about such information like the names of the HIPs
which have created health records for a user and labels given to such records. This
meta-information assists HIUs in determining what information to seek from HIPs.
● Consent lifecycle management: ​CMs manage the lifecycle of consent artefacts, including
activities like revocation and pausing of consent.
● Consent-related notifications: ​CMs notify users, HIUs and HIPs about key
consent-related events like consent revocation. CMs also receive notifications from HIU
/ HIP systems about events in the data flow e.g., notifications indicating transmission or
receipt of data, and maintain a record of such events for the benefit of the user.
By design, CMs never get access to shared health information, whether encrypted or raw. This
ensures that entities who play the role of a CM are not incentivized by a need to aggregate user
information and instead, are motivated to provide safe and reliable consent management
services to the user. Overall, CMs are one of our main mechanisms for ensuring ​user centricity
of our architecture.
2. Gateway providers:​ Gateways form the hub of information exchange in the HIF ecosystem. The
role of a gateway includes all of the following:
● Routing: ​The gateway is responsible for routing all communication between a CM’s
software system and a health repository and that between two health repositories,
except for the transfer of health information during the data flow. In other words,
gateways route ​all control communication​ ​across CMs, HIUs and HIPs - information that
is shared during the discovery, linking and consent flows. The transfer of health
information from an HIP to an HIU happens directly from a repository linked with the
HIP to a repository linked with the HIU, and does not involve the gateway, as shown in
Figure 1. This design choice is made with the consideration for scalability, and, in
particular, considering the large bandwidth requirements for health information.
● Interoperability: ​The gateway implements a set of standardized APIs and can
communicate with a CM system or a health repository only if such a system also
implements a set of standardized APIs. This enables a many-to-many communication
network to be rapidly set up across different entities and also enables evolvability of the
communication protocols.
● Registry management: ​Gateway providers maintain a ​registry​ of CMs and health
repositories, which stores information like the access URLs for different software
services of CMs/repositories and the mapping between HIP/HIU names and their
repositories. The registry is critical for routing requests between entities.
● Security: ​Gateways run a token-issuing service which is used to ensure security of all the
gateway APIs, and thus of all communication in the network.
● Audit: ​Gateway providers are responsible for auditing health repositories and CM
software systems and ensuring their compliance with the HIF technical standards.
Gateways are envisaged to be regulated entities and only 1-2 of them are expected to operate

13. at country scale.
3. Health repository providers:​ Health repository providers are enablers for HIPs and HIUs to
participate in health information flows. Their role covers the following:
● API services: ​Health repository providers enable information flows of all types for
HIUs/HIPs: personal HIFs (consented data sharing), sharing of non-personal data and
open data (unconsented data sharing) and compliance HIFs (unconsented data sharing,
needed for audits). They implement standardized APIs that are required to be able to
communicate with gateways, whereas their associated HIPs/HIUs may not implement
such APIs.
● Data services: ​Repository providers implement middleware software for data
standardization and data anonymization which enables HIUs and HIPs to participate in
different types of HIFs. They may enable HIFs for open data and non-personal data and
they may offer data analytics solutions for HIUs.
● Repository services: ​Health repository providers may provide long-term solutions to
HIUs/HIPs. This is particularly useful for small establishments (e.g., rural clinics or
hospitals) and enables them to participate in the HIF ecosystem.
In general, repository providers ​increase accessibility of healthcare data ​in the HIF ecosystem
and are key vehicles for implementing our ​diversity​ ​and ​scalability​ ​design principles​. ​They
address the problem of fragmentation in the healthcare space. A few repository providers could
potentially enable hundreds of thousands of disparate healthcare providers in the country to
come online, manage their storage and become “HIF-enabled”.
Health repository providers are not envisaged to be regulated entities, but every such provider
must meet strong certification requirements which will include both the functional as well as
non-functional requirements (like security and availability).
In earlier versions of this specification, we referred to health repositories as data bridges or API
bridges. The terminology has changed but the functionality remains the same.
2.4 User Interactions
In this section, we highlight how users interact with different entities in our architecture.
2.4.1 User interactions with HIPs and HIUs
Every user must have interacted with at least one HIP and at least one HIU before a health information
flow for that user can occur. When users interact with HIPs, HIP software systems create two types of
information:
1. A​ user profile​, with a ​verifiable ID (or IDs)​: This is created when the user interacts with an HIP

14. for the first time. It includes demographic information about the user (name, age, gender and
possibly, address) and a set of identities (IDs) using which the HIP identifies and authenticates
the user. The HIP may generate and assign an ID to a user (e.g., a hospital may assign a patient
ID to every new patient) or it may also leverage existing IDs linked to the user like the user’s
Aadhaar number, PM-JAY ID or his phone number.
Requirement #1: ​At least one of the IDs used in a user profile by any HIP software system
must be a ​verifiable ID​, which means that it must be possible for the HIP system to digitally
authenticate the user against that ID using a user-selected password, a one-time password
(OTP), biometrics or other means of user authentication.
It is possible that an HIP uses verifiable IDs that are shared across multiple users as long as it has
a mechanism to distinguish between multiple users with the same verifiable ID. Such IDs are
referred to as ​shared verifiable IDs​. ​A user’s mobile number is a good example of a shared
verifiable ID. When the mobile number is used as an ID, the HIP system could use demographic
details (name, age, gender, in particular) to distinguish users with the same mobile number.
2. A​ health record: ​Every transaction with an HIP may lead to the creation of new digital health
information which is stored in the HIP’s software system in the form of ​health records. ​We
define a health record as any collection of documents (or database entries) containing health
information about a user. The mapping from transactions to health records is HIP-determined: a
single transaction may generate one or more health records and a single health record may span
one or more transactions.
Requirement #2: ​The health records of a user created by an HIP system must be searchable
given a verifiable ID of the user (if the ID is a unique verifiable ID) or a combination of a
verifiable ID and a set of unique attributes of the user (if the ID is a shared verifiable ID).
Additionally, HIP systems may attach ​labels​ to each health record for the purpose of record
organization and search. Labels should preferably be intelligible by users so as to assist them in
recalling the care context in which the associated record was generated. An example of a label is
a ​visit ID ​assigned by a diagnostic lab for each visit made by a user to the lab. Another example is
a ​case ID ​assigned by a hospital for an episode of treatment provided by the hospital to a
patient. HIPs are free to use any policy for assigning labels to health records. Where
human-readable labels are not assigned, a transaction ID or a date-stamp could be used as the
label for each health record.
If an HIP system uses shared verifiable IDs to authenticate users, it is possible that two users with a
shared ID can access health records of each other. When such an HIP system participates in the HIF
ecosystem, it becomes possible for one user to allow an HIU to access the health record of another user
with whom the user shares a verifiable ID. This can be a valuable feature in some scenarios (e.g., to

15. enable delegated access control) but it also has some obvious risks. The risks should be suitably
communicated to users by every HIP which uses shared verifiable IDs in its systems.
2.4.2 Registration with CMs
Every user who wishes to enable his personal health information to be shared from HIPs to HIUs must
first register with a consent manager of his choice. This registration process involves collection of
essential demographic details about the user and a verifiable ID. The CM validates the verifiable ID by
having the user authenticate against it once. Once validated, the user creates a User ID to identify
himself in future interactions. In the discovery and linking flows, described below, each such User ID is
linked with a set of health records created by HIPs and these records then become discoverable by HIUs
when given that User ID. Thus, every health record of a user that is shareable via HIFs and can become a
part of a PHR of the user must be linked to some User ID created at a CM. We thus refer to this User ID
as the ​PHR ID​ of the user. PHR IDs form a critical component of the HIF architecture.
2.4.2.1 Structure of a PHR ID
The construct of the PHR ID is similar to that of the UPI ID in the Unified Payments Interface (UPI). In
particular, we require that all PHR IDs are of the form
phr-id​ ​:=​ <user-id>@<cm-name>
where user-id is an alphanumeric string that can contain only alphabets (a-z, A-Z), digits (0-9) or the
characters .(dot) and - (hyphen). CM-name is the name attached to the CM that generates the ID; this is
the same name maintained in the CM registry of the gateway provider where the CM is registered.
PHR IDs can be created either directly by the user or in an assisted manner. CMs may deploy different
approaches to register users and to create PHR IDs. This may include partnering with both HIPs and
HIUs, who have existing relationships with users. For example, CMs may partner with different
diagnostic labs and implement their user registration protocol as part of existing front-desk procedures
at the labs: every time a new user undertakes a diagnostic test at a lab (and a health record created for
the user in its LIMS system), the user could be given an option to create a PHR ID as well.
2.4.2.2 Multiplicity of PHR IDs
A user can have multiple PHR IDs across different CMs and can even create multiple PHR IDs at the same
CM. This feature enables users to create a partitioned view of their health information and is in keeping
with our ​privacy by design ​guiding principle. As an example, users may choose to link less sensitive
health records with one PHR ID and more sensitive ones with another PHR ID, and only allow a limited
set of HIUs to access health information linked to the latter ID.
Every PHR ID must correspond to a single user, even if the verifiable ID used at the time of ID creation
may be shared across users. Thus, each PHR ID is unique to a user and a “user-centric” form of a unique
ID (the user can choose an ID that is unique to him). This is distinct from the traditional notion of a
unique ID (e.g., Aadhaar), which enables the State, or entities designated by the State, to be able to

16. uniquely identify the user, and is thus more “State-centric” in design. If we were to require each PHR ID
to be linked to a unique ID like Aadhaar (only one PHR ID allowed per unique ID), it would imply
linkability of all PHR information to individual users, which is something we wish to avoid.
A PHR ID can also be destroyed by the user who created the ID. When a PHR ID is destroyed, users may
be given the option to port all information associated with that PHR ID, including the labels of all linked
health records, to another PHR ID, which is important for ensuring ​health information portability.
While we allow for users to have multiple PHR IDs, we also require that each user is able to link his
(active) PHR IDs and enable creation of a longitudinal view of his information ​across all PHR IDs created
in his lifetime​, if and when he wants to. This is important to ensure recoverability of all PHR information
of a user by the user himself, or by individuals delegated by the user. For this, we have developed the
idea of a ​PHR ID linking protocol,​ ​which will be described in a future version of this document.
2.4.2.2 PHR ID retrieval and lookup
When users interact with HIPs and HIUs, they may be required to furnish a PHR ID in order to enable
health information sharing. In order to aid the user in recalling their PHR IDs, a ​PHR ID retrieval flow
must be implemented. The HIP and HIU systems can use this flow to retrieve a user’s PHR ID, based on a
verifiable ID and other demographics information furnished by the user. CMs may also allow HIPs and
HIUs to check for the existence of a PHR ID using a ​PHR ID lookup flow.
2.4.3 Discovery and Linking
As discussed above, health information of users needs to be discovered and linked with a PHR ID before
HIUs can access such information from HIPs. This can happen in two ways.
2.4.3.1 CM-initiated discovery and linking
In this approach, the discovery and linking process is initiated by the CM, upon user request. There are
two parts to the process:
1. A ​discovery flow​, in which a user uses the CM front-end to specify a list of candidate HIPs where
his health records exist, along with the verifiable IDs used by those HIPs for the user (and,
possibly, user demographics information as well). The CM system sends a request to each of the
corresponding HIP systems, searching for all​ ​associated health records of the user. In response,
each HIP system returns the labels of the health records discovered for the user against the
verifiable IDs that are specified in the request.
2. A ​linking flow​. ​After the discovery flow is over, the user is asked to view the discovered health
record labels and to select a subset of the records for linking with his PHR ID. Once the user has
selected those records, the CM sends another set of requests to the HIPs, this time asking for
the user-specified records to be linked. Each HIP system that receives a linking request must ask
for authorization from the user for the linking to take place. This authorization involves
authenticating the user against the verifiable ID which was used to discover the health records

17. earlier. Once authorized, the selected records are linked to the given PHR ID.
2.4.3.2 HIP-initiated linking
In this approach, the linking process is initiated by the HIP, again upon user request. Here, the user
specifies a PHR ID and a set of health record labels to the HIP and the HIP’s software system sends a
linking request to the CM with the given PHR ID and the given set of labels. There is no discovery flow
that is required for this type of linking to occur. However, depending upon the policies set by the HIP,
user authentication may still be required before the HIP can issue the linking request to the CM. Prior to
linking, the HIP system may assist the user in retrieving his PHR ID using the PHR ID retrieval flow.
More details on these flows are given in Section 3.
2.4.4 Consent
Once a user’s account with a CM has one or more linked HIP records, the stage is set for the user to start
giving consent via the CM. In most situations, the consent process is triggered by an HIU software
system issuing a consent request to a CM, which results in the CM sending a notification to the user
informing him about the request. Subsequent to the notification, the user uses the CM’s front-end to
view the details of the consent request, which may cover requests to access health information from
multiple records in multiple HIPs. The user may approve some of these requests (and reject others), and
he authorizes his approval by authenticating to the CM. Subsequently, a set of consent artefacts are
generated by the CM, one for each HIP from which information is being sought, digitally signed by the
CM and each consent artefact is shared with the HIU system that made the consent request. Consent
artefacts are also sent to HIP systems to prepare them for future information requests.
Besides the ability to give consent, users can also revoke consent that was previously given by them and
may also be able to pause and resume the functioning of a consent artefact. All these functionalities can
be availed by interacting with the front-end of the CM that generated the artefact. A CM may also
provide users the ability to view all the consents granted by them through that CM, and details about
data flow events involving each of those consents.
2.5 Health information (HI) types
As discussed, a health record collected and shared by an HIP is viewed as a collection of one or more
digital files (or database entries) containing health information of a user. Each such file must be of a
certain type that is identifiable by HIU systems, and we refer to this meta-information as the ​health
information (HI) Type ​of the file. In our architecture, HI types are mapped to ​FHIR Resources​, a
taxonomy to define and represent health data in software systems. FHIR (Fast Health Interoperability
Resources) is an internationally accepted data exchange standard which can be used in partnership with
existing widely used standards.
We use FHIR resources to define only the meta information (the “envelope”) that accompanies the
health information in HIFs, but the actual information itself need not adhere to the FHIR standard. In

18. particular, we do not require existing software systems to comply with the FHIR standard in either
storing or sharing of health information. This enables HIU systems to interpret health information
received by them in HIFs but it still does not require HIP systems to change significantly. More details on
the process of defining HI types and using them in HIFs are forthcoming.
3 APIs and Flows
Before we describe the APIs and Flows in detail, we will discuss registries, which are a key building block
used in the HIF architecture.
3.1 Registries and related functionalities
Registries are software services that store master data about entities (users, organizations or systems) in
a manner that the data is self-maintainable by these entities, provides a high degree of trust to those
who wish to use the data and is accessible via open APIs. The ​National Digital Health Blueprint (NDHB)
outlines several types of entities that are to be part of registries, including users (patients, beneficiaries),
care professionals (doctors, nurses, ASHA workers, etc), care facilities (hospitals, labs, clinics, etc), payers
(insurers, health plans, etc), government bodies (ministries, regulators), pharmaceuticals (drugs, device
manufacturers etc), research organizations, and health technology companies.
In the HIF architecture, these registries are valuable from the point of view of onboarding HIPs and HIUs.
Since HIPs and HIUs could be care facilities, payers, government bodies, pharmaceuticals, research
organizations and health technology companies, registries for all these entities can be used to verify the
validity of an HIP/HIU when it is being onboarded.
Other than the registries listed above, we also need registries of certain entities that are unique to the
HIF ecosystem. This includes a registry for CMs, one for health repository providers and one for gateway
providers. These registries must be built and maintained by gateway providers and must be available for
access by other entities in the ecosystem.
3.1.1 Onboarding HIPs and HIUs using registries
Any entity wishing to participate in the HIF ecosystem as an HIP or an HIU must have a health repository
provider associated with itself. To create this association, it has two options: the entity may choose to
become a health repository provider itself (and register itself as such) OR it may enter into a contract
with an existing health repository provider, asking for its repository services.
Once an HIP/HIU has an associated health repository provider, it must register with a gateway provider
and go through an ​onboarding​ ​process​. Onboarding has two components:
1. Entity validation: ​An entity wishing to onboard as an HIP/HIU may list itself as an entity
registered in one of the NDHB-defined registries and prove itself as such. If the entity does not
exist in any of the external registries, it should prove its identity by other approaches defined by

19. the gateway provider. This process would also enable the gateway provider to create a profile of
the entity, which must include the name of the entity and an entity ID. For example, in the case
of care facilities, this could be a facility ID assigned by the facility registry or an HIP/HIU ID
created by the gateway.
2. Submitting health repository details: ​The entity must furnish the name of its associated health
repository provider and the access URL - in the repository provider’s domain - for all the HIF APIs
of this entity. The access URL must be in the list of access URLs provided by the entity’s
repository provider when registering itself.
All these steps must be undertaken by suitable human representatives of the entity that is being
onboarded.
3.1.2 Onboarding CMs and health repositories
Like HIPs and HIUs, CMs and health repository providers also need to register themselves with a
gateway provider. This process also involves an entity validation step and an information submission
step. However, in the case of CMs and repositories, there are no externally available registries and as
such, gateway providers need to create these registries.
3.1.2.1 CM registration
CMs need to validate themselves by providing information about license, if any, obtained from a
healthcare or other regulator and details about their registration as a company (or, if they are not a
company, then details of having registered as an organization of the type they are). CMs may also be
required to submit a certificate from a certification agency that claims the CM’s software system to be
compliant with the HIF standards. Through the certificate or otherwise, CM’s must provide SLAs on all
the HIF APIs implemented by them.
Once validated, CMs must submit all data that is required to create the CM’s entry in the CM registry.
The base schema for the CM registry is given below. This schema may be extended by the gateway.
Schema for CM registry:
cm-info:​ {
// private attributes:
cm-id:​ “integer”, // UUID used for addressing CM internally
license​: “string” // Base-64 encoded license document issued by a regulator
sla-details: ​“object” // Details of SLA provided by the CM
reg-time​: “string” // Registration time of the CM, in date-time format
last-updated​: “string” // Time of last update of CM info, in date-time format
// public attributes:
cm-full-name​:​ “string”, // Full name of the CM, an arbitrary alpha-numeric string
cm-name​:​ “string”, // Name of the CM used in all PHR IDs issued by it, format: [a-z|A-Z|-|.]*

20. accessURLs​:​ [ // list of URLs that could be used to access CM APIs
accessURL: ​“string”, // URL for accessing CM APIs
]
pki-certificate​:​ “string”, // Base-64 encoded X.509 certificate with CM’s long-term public key.
isActive​:​ “boolean” // Flag indicating whether CM is currently active or not
isBlacklisted​:​ “boolean” // Flag indicating whether CM has been blacklisted by the gateway
}
3.1.2.1 Repository registration
Like CMs, health repository providers must also furnish company registration details at the time of
registration in order to validate themselves. Software certification and SLAs must also be submitted. As
in the case of CMs, repository providers must submit other information that is needed to create a
registry entry for the repository provider. The base repository provider registry schema is given below. It
is extensible by gateway providers.
Schema for repository provider registry:
repository-provider-info:​ {
// private attributes:
repo-provider-id:​ “integer”, // UUID used for addressing the provider internally
sla-details: ​“object” // Details of SLA provided by the repository provider
reg-time​: “string” // Registration time of the repository provider, in date-time format
last-updated​: “string” // Time of last update of repository provider info, in date-time format
hip-list: ​[​ ​// List of HIPs for whom this is an associated repository provider
hip-id: ​“string” // HIP ID as defined at the time of HIP registration
]
hiu-list: ​[​ ​// List of HIUs for whom this is an associated repository provider
hiu-id: ​“string” // HIU ID as defined at the time of HIU registration
]
// public attributes:
repo-provider-full-name​:​ “string”, // Full name, an arbitrary alpha-numeric string
accessURLs​:​ [ // list of URLs that could be used to access repository provider APIs
accessURL: ​“string”, // URL for accessing repository provider APIs
]
pki-certificate​:​ “string”, // Base-64 encoded X.509 cert with provider’s long-term public key
isActive​:​ “boolean” // Flag indicating whether provider is currently active or not
isBlacklisted​:​ “boolean” // Flag indicating whether provider has been blacklisted
}

21. 3.1.3 Gateway peering
Each gateway provider needs to share information about itself with other gateway providers. This
results in every gateway provider maintaining a gateway registry which is mirrored at all other gateway
providers. Each gateway registry entry contains essential information like the name of the gateway
provider, a gateway ID, access URL, a PKI certificate and information about SLAs. Details about this are
forthcoming.
3.1.4 Profile updation of different entities
Information about different entities (HIPs, HIUs, CMs, repositories, gateways) needs to be kept
up-to-date by the gateway providers. This may involve look-ups with externally hosted registries and
checking for the status of PKI certificates. In the case of health repositories, there is one additional type
of update that is performed regularly: when an HIP (resp HIU) with whom the repository is associated
either registers with a gateway or de-registers from a gateway where it is registered, the attribute
hip-list (resp hiu-list) ​for that provider’s registry entry must be updated. Details about these update
protocols are forthcoming.
3.2 APIs
The following diagram shows the different APIs that are to be implemented by all software systems in
the HIF architecture:
Figure 2: APIs to be implemented by all software systems in the HIF architecture
Gateways need to implement five sets of APIs: gateway-cm APIs (interface to CMs), gateway-repository
APIs (interface to health repositories), registry APIs (APIs for accessing the registry), cross-gateway APIs

22. (APIs for peering with other gateways) and monitoring APIs. Each health repository implements a set of
APIs titled “repository APIs” which is meant for interfacing with a single gateway. Repositories may also
implement APIs for interfacing with HIPs and HIUs, but these APIs are not part of the HIF standard. Each
CM implements a set of APIs titled “cm APIs” which is meant for interfacing with a single gateway. Again,
CMs may have APIs that enable the CM back-end to interface with the CM front-end; these too are not
part of the standard.
For ensuring high scalability and in order to minimize state management overheads at the gateway, we
use a fully asynchronous approach in our design of the gateway APIs. For every API with an action verb ​V
in the gateway-repository (resp. gateway-cm) API set, there is a corresponding callback API with action
verb ​on-V ​in the repository (resp. cm) API set, using which the gateway submits the response that is
generated in response to action ​V. ​Similarly, for every API with action verb ​V ​in the repository (resp. cm)
API set, there is a corresponding callback API with action verb ​on-V ​in the gateway-repository (resp.
gateway-cm) API set, using which the gateway receives the response that is generated in response to
action ​V.
The details of all APIs and flow diagrams are available from ​https://projecteka.github.io/​. This document
only provides the high-level descriptions of the APIs.
3.2.1 gateway APIs
3.2.1.1 registry APIs
CM registry APIs
GET /cm-registry/all This is an API used by data repositories to get a list of all consent managers
registered with the gateway provider
GET /cm-registry/{cm} This is an API used by health repositories to fetch public information about
a CM
3.2.1.2 gateway-cm APIs
The gateway-cm API set consists of five categories of APIs, one each for the PHR-ID retrieval and search
flows, the discovery flow, the linking flow, the consent flow and the data flow.
PHR ID Retrieval and Lookup APIs
POST /users/on-get-id This is the callback API corresponding to the /users/get-id API in the cm API
set. The body contains either a PHR ID or an error message, to be filled if
PHR ID retrieval failed.
POST /users/on-find This is the callback API corresponding to the /users/find API in the cm API
set. The body contains either the name of a user (whose PHR ID was given

23. in the find request) or an error message, to be filled if the find request
failed.
Discovery Flow APIs
POST
/care-contexts/discover
This is the API used by CMs to initiate a discovery flow. The body contains
at least one verifiable ID of a user required for discovery, the user’s PHR ID
and, possibly, other information required to uniquely identify the user in
the HIP system. The header contains the HIP-ID of the destination HIP. It is
expected that the destination HIP system will return a set of (potentially
masked) care-context labels (equivalent to health record labels).
CM-initiated Linking Flow APIs
POST
/cm-links/link/init
This is the API used by CMs when initiating a linking flow. The request body
contains a PHR ID and a list of care-context labels to be linked with the ID
and the header contains the HIP-ID of the destination HIP.
POST
/cm-links/link/confirm
This API is used by CMs to submit a token sent by an HIP to the user during
link initiation. The token is destined for the HIP system where link initiation
happened. The body contains the token and a link reference number. The
header contains the destination HIP’s ID.
HIP-initiated Linking Flow APIs
POST
/hip-links/link/on-init
This is the callback API corresponding to the /hip-links/link/init API in the cm
API set. The body contains either information about a successful link
initiation (a link reference number created by the CM that issues this request
and details about the type of user authentication performed by the CM) OR
an error message, to be filled if the link request was not fulfilled. The header
contains the destination HIP’s ID.
POST
/hip-links/link/on-conf
irm
This is the callback API corresponding to the /hip-links/link/confirm API in
the cm API set. The body contains either information about whether linking
succeeded or not OR an error message in case linking fails. The header has
the destination HIP’s ID.
Consent Flow APIs
POST
/consent-requests/on-init
This is the callback API corresponding to the /consent-requests/init API
in the cm API set. The body contains either a consent request ID
assigned by the CM to the consent request or an error message in case
the consent request was not fulfilled. The header has the destination
HIU’s ID.

24. POST
/consent-requests/on-stat
us
This is the callback API corresponding to the /consent-requests/status
API in the cm API set. The body contains either information about a
successful status notification (the associated consent request’s ID, the
status of that consent request, and optionally, a list of consent artefact
IDs, specified in case consent was granted against that request) or an
error message in case the consent status request was not fulfilled. The
header has the destination HIU’s ID.
POST /consents/hiu/notify This API is used by a CM to send consent-related notifications, targeted
at an HIU’s health repository. The header contains the destination HIU’s
ID. The body contains either a consent request ID (OR a consent
artefact’s consent ID) for which notification is sent. There is a status flag
indicating whether consent was granted against the specified consent
request or not (OR whether the specified consent artefact was revoked,
paused or resumed). If the notification is about consent being granted,
the body also contains a list of consent IDs corresponding to the consent
artefacts that were generated.
POST /consents/hip/notify This API is used by a CM to send consent-related notifications, targeted
at an HIP’s health repository. The header contains the destination HIP’s
ID. The body contains the consent artefact’s consent ID for which
notification is sent. There is a status flag indicating whether consent was
granted, revoked, paused or resumed. If the notification is about
consent being granted, the body also contains the corresponding
consent artefact.
POST /consents/on-fetch This is the callback API corresponding to the /consents/fetch API in the
cm API set. The header contains the destination HIU’s ID. The body
contains the consent artefact that was requested.
3.2.1.3 gateway-repository APIs
The gateway-repository API also consists of four categories of APIs, as defined below.
PHR ID Retrieval and Lookup APIs
POST /users/get-id This is the API used by health repositories to fetch a PHR ID. The body
contains a verifiable ID of the user whose PHR ID is required and,
optionally, other user information (to help uniquely identify the user in the
CM system).
POST /users/find This is the API used by health repositories to check for the existence of a
PHR ID. The body contains a PHR ID.
Discovery Flow APIs

25. POST
/care-contexts/on-discover
This is the callback API corresponding to the care-contexts/discover API
in the repository API set. The body contains either a set of (potentially
masked) care-context labels or an error message, to be filled if the
discovery request was not fulfilled.
CM-initiated Linking Flow APIs
POST
/cm-links/link/on-init
This is the callback API corresponding to the links/link/init API in the
repository API set. The body contains either information about a successful
link initiation (a link reference number and some meta-information about
the type of user authorization being done by the HIP) or an error message, to
be filled if the link request was not fulfilled.
POST
/cm-links/link/on-conf
irm
This API is the callback API corresponding to the links/link/confirm API in the
repository API set. The body contains either information about successful
linking (the unmasked care-context labels successfully linked) or an error
message, indicating that linking failed.
HIP-initiated Linking Flow APIs
POST
/hip-links/link/init
This is the API used by health repositories to initiate a linking request on
behalf of an HIP system. The body contains a PHR ID and a set of care
context labels to be linked to the PHR ID. The header contains the
destination CM’s name.
POST
/hip-links/link/confirm
This API is used by health repositories to submit a token sent by a CM to the
user during link initiation. The token is destined for the CM where the linking
is required to take place. The body contains the token and a link reference
number. The header contains the destination CM’s ID.
Consent Flow APIs
POST
/consent-requests/init
This is the API used by an HIU’s health repository to send a consent
request to a CM. The header contains the CM-name of the destination
CM. The body contains the consent details, which includes all
parameters associated with the consent request like the PHR ID of the
user, the HI types of the records that are required to be accessed and
other details that would eventually go into the consent artefact once
consent is granted.
POST
/consent-requests/status
This is the API used by an HIU’s health repository to send a request to
check status of a consent request earlier issued by the same repository.
The header contains the CM-name of the destination CM. The body
contains the ID of the consent request whose status check is requested.

26. POST
/consents/hiu/on-notify
This is the callback API used by an HIU’s health repository to respond to
a consent notification sent by the gateway. The body contains either an
acknowledgement or an error message. The header has the destination
CM’s name.
POST
/consents/hip/on-notify
This is the callback API used by an HIP’s health repository to respond to
a consent notification sent by the gateway. The body contains either an
acknowledgement or an error message. The header has the destination
CM’s name.
POST /consents/fetch This API is used by an HIU’s health repository to request for a consent
artefact. The body contains the consent ID associated with that consent
artefact. The header has the destination CM’s name.
3.2.1.4 monitoring APIs
Details about monitoring APIs will be provided soon.
3.2.2 repository APIs
APIs in the repository API set mirror the APIs in the ​gateway-cm API set​. Each has a corresponding API in
the gateway-cm API set, with a similar name and almost similar contents. We describe them briefly here,
highlighting the differences with the corresponding gateway-cm APIs.
3.2.2.1 HIP-targeted APIs
PHR ID Retrieval and Lookup APIs
POST /users/on-get-id This is the callback API corresponding to the /users/get-id API in the
gateway-repository API set.
POST /users/on-find This is the callback API corresponding to the /users/find API in the
gateway-repository API set.
Discovery Flow APIs
POST /care-contexts/discover This is the API used by gateways during a discovery flow.
CM-initiated Linking Flow APIs
POST /links/link/init This is the linking initiation API used by gateways for CM-initiated linking.
POST /links/link/confirm This is the API used by gateways to submit a token and confirm

27. CM-initiated linking.
HIP-initiated Linking Flow APIs
POST
/hip-links/link/on-init
This is the callback API corresponding to the hip-links/link/init API in the
gateway-repository API set.
POST
/hip-links/link/on-conf
irm
This is the callback API corresponding to the hip-links/link/confirm API in the
gateway-repository API set.
Consent Flow APIs
POST /consents/hip/notify This API is used by a gateway to send consent-related notifications to
an HIP with whom the repository is associated.
3.2.2.2 HIU-targeted APIs
Consent Flow APIs
POST
/consent-requests/on-init
This is the callback API corresponding to the /consent-requests/init
API in the gateway-repository API set.
POST
/consent-requests/on-status
This is the callback API corresponding to the /consent-requests/status
API in the gateway-repository API set.
POST /consents/hiu/notify This API is used by a gateway to send consent-related notifications to
an HIU with whom the repository is associated.
POST /consents/on-fetch This is the callback API corresponding to the /consents/fetch API in
the gateway-repository API set.
3.2.3 cm APIs
APIs in the cm API set mirror the APIs in the ​gateway-repository API set​. Each has a corresponding API in
the gateway-repository API set, with the same name and similar contents. We describe them briefly
here.
PHR ID Retrieval and Lookup APIs
POST /users/get-id This is the API used by gateways to fetch a PHR ID from the CM.
POST /users/find This is the API used by gateways to check for the existence of a PHR ID.

28. Discovery Flow APIs
POST
/care-contexts/on-discover
This is the callback API corresponding to the care-contexts/discover API
in the gateway-cm API set.
CM-initiated Linking Flow APIs
POST /cm-links/link/on-init This is the callback API corresponding to the links/link/init API in the
gateway-cm API set.
POST
/cm-links/link/on-confirm
This API is the callback API corresponding to the links/link/confirm API
in the gateway-cm API set.
HIP-initiated Linking Flow APIs
POST
/hip-links/link/init
This is the linking initiation API used by gateways for HIP-initiated linking.
POST
/hip-links/link/confirm
This is the API used by gateways to submit a token and confirm HIP-initiated
linking.
Consent Flow APIs
POST
/consent-requests/init
This is the API used by gateways to send a consent request to a CM.
POST
/consent-requests/status
This is the API used by gateways for checking status of a consent request
earlier issued to the same CM.
POST
/consents/hiu/on-notify
This is the callback API used by a gateway to respond to an HIU-targeted
consent notification sent by a CM.
POST
/consents/hip/on-notify
This is the callback API used by a gateway to respond to an HIP-targeted
consent notification sent by a CM.
POST /consents/fetch This API is used by a gateway to request for the consent artefact
corresponding to a given consent ID.

29. 3.3 Flows
In presenting the various flows, we use the following conventions:
● Solid lines for interactions which are covered by this standard; dotted lines for interactions
which are also part of the flows but not covered by the standard.
● API names in bold and API parameters in brackets in the form of (​header; body​).
● HIP-IDs, HIU-IDs and CM-names are referred to as ​hip, hiu ​and ​cm ​respectively​.
● The symbol “|” denotes the logical operator OR.
● Parameters enclosed in square brackets “[ .. ]” are to be treated as optional parameters.
● We require that every request have a unique request ID (a UUID generated by the API
requester) and a timestamp. These are not explicitly shown in the flow diagrams. Every callback
API (API ending in ​on-V ​for some verb ​V​) must additionally have an ID whose value is the request
ID of the API request that is being responded to. This is also omitted in the diagrams.
● We specify only key body parameters in the flow diagrams and do this at a high level e.g.
consent-details​ is a parameter which contains various details related to a consent creation
request. Detailed description of API body contents and parameters is available from:
https://projecteka.github.io/
​3.3.1 PHR ID retrieval and lookup
We illustrate how PHR ID retrieval works when initiated at an HIP system. Retrieval can also be initiated
by an HIU system but that flow is not shown here. PHR ID retrieval begins with the user submitting a
verifiable ID to an HIP along with demographic information, triggering a get-id request to the associated
health repository. The health repository first gets a list of all available CMs from the gateway using the
registry API. For all CMs in the list of CMs, the repository sends simultaneous requests containing the
verifiable ID and demographic information submitted by the user. Each CM internally matches the
provided information against all user profiles and returns a PHR ID (and name of the user) if a match
succeeds. The matching algorithm is CM-determined and may involve doing fuzzy matches on user
demographic information. Eventually, the HIP system displays ​all ​PHR IDs returned by the different CMs
and lets the user select which PHR ID to use in succeeding flows.

30. The next diagram illustrates the PHR ID lookup flow, when the lookup is initiated by an HIU system. PHR
ID lookup can also be initiated by an HIP system, but that is not shown here. The ​response ​given by the
CM in this flow is a boolean response, indicating whether the given PHR ID exists or not.

31. 3.3.2 Discovery flow
Discovery involves the CM querying an HIP system about the existence of health records for a user with
a given set of verifiable IDs. In response, the HIP system provides a set of care context labels (in masked
form) which is sent by the health repository associated with the HIP.
3.3.3 CM-initiated linking flow
The CM initiated linking flow begins with the CM requesting an HIP system to link a set of care context
labels to be linked with a given PHR ID of the user. In response, the HIP system specifies the type of
authentication that the HIP system wishes to perform for the user (and associated parameters) for the
linking to take place and a ​link reference number​. In the current specification, only OTP-based
authentication is supported: the HIP system sends an OTP (aka token) to the user to a communication
address (phone number or email address) associated with his verifiable ID and the OTP needs to be
submitted by the user to the HIP system, via the CM front-end, in a stipulated period of time. The CM
submits this token to the HIP system along with the link reference number that was earlier received. If
authentication succeeds, the HIP system responds with a success message and linking is deemed
complete.

32. 3.3.4 HIP-initiated linking flow
In the HIP initiated linking flow, the user submits the linking request to the HIP along with his PHR-ID and
the HIP system optionally authenticates the user against his verifiable ID registered with it. The HIP
system sends a linking request to the CM (via its associated health repository), specifying the care
context labels it wishes to link for the user, and the CM then attempts to receive authorization from the
user for the linking to be completed. Currently, we allow only OTP/token-based authorization: the CM
sends an OTP to the user which must be then submitted back to the CM via either the CM front-end or a
front-end of the HIP system. (The diagram below shows the latter use case.) Once authorized, the CM
sends a confirmation message back to the HIP system.

33. 3.3.5 Consent flow
The consent flow has four components which we describe below:
3.3.5.1 Consent request from an HIU to a CM
Consent collection begins with an HIU system issuing a consent request to a CM against a given PHR ID.
(The CM to issue the request to is determined based on the PHR ID.) The CM acknowledges the request
by responding with a ​consent request ID ​(which is routed via the gateway and the health repository back
to the HIU system)​. ​Consent collection from the user happens asynchronously after a consent request
has been received by the CM. The CM may send a notification (e.g., via SMS) to the user at the time of
receipt of a consent request and ask the user to view the details of the request and either grant consent
or deny it. Subsequently, the CM notifies the HIU system that issued the consent request about the
change in status of the consent request. This notification, described in the next section, informs the HIU
whether the request was granted, in which case it also contains a list of consent artefact IDs of the

34. consent artefacts that were created against the request, OR it informs the HIU that consent was denied,
in which case no artefact IDs are sent.
3.3.5.2 Consent notification from a CM to an HIU
Consent-related notifications from a CM to an HIU system serve two purposes: first, when a consent
request is fulfilled by a CM (i.e. consent is either granted or denied by the user), the CM notifies the HIU
about the fulfillment of the request. In case fulfillment resulted in consent being granted, a list of
consent artefact IDs are sent to the HIU system. Each consent artefact ID or consent ID in this list
corresponds to a single consent artefact generated by the CM and contains information about consent
given to the HIU to fetch health information from a single HIP. Corresponding to each such consent
artefact is also an “HIP-facing” version of the artefact which contains nearly the same information,
except that it does not specify the name of the HIU. (See below.) If consent is denied, no artefact IDs are
sent and the HIU is informed about the denial of consent.
The second purpose of notifications from the CM to the HIU is to inform the HIU about a change in
status of a ​single ​consent artefact. In particular, if the consent artefact has been revoked, paused or
resumed by the user, a notification corresponding to this update is sent to the HIU system that triggered
the creation of the consent artefact. In this case, it is important that the CM receive acknowledgement
that the notification about the change in status of the artefact has been recorded by the HIU system,
which is accomplished by the /consents/hiu/on-notify/ callback APIs, as shown in the diagram below.

35. 3.3.5.3 Fetching a consent artefact from a CM
Once consent has been granted by the user, the CM notifies the HIU system as above and for each
consent artefact ID specified in the notification, the HIU system can issue a request to the CM to fetch
the corresponding artefact as shown below.
In situations where the notification about consent grant is not received from the CM in a timely manner
(according to SLAs provided by the CM), the health repository associated with the HIU system can
request for the status of the consent request that was earlier issued. In response, the CM responds with
the status of the consent request and if consent has been granted, it also sends the IDs of the consent
artefact(s) that were generated in response to the original consent request. This is illustrated in the next
sequence diagram.

36. 3.3.5.4 Consent notification from a CM to an HIP
As discussed above, whenever consent is granted by a user through a CM, two lists of consent artefacts
are generated by the CM. One is meant to be shared with the consent-seeking HIU, and these are
fetched by the HIU system using the consent fetch flow described above. For each artefact in this list of
artefacts, there is also an HIP-facing version of the artefact which has information about the HIP from
whom information can be fetched using the artefact, but which ​does not ​have information about the
HIU seeking the information. This enables HIUs to be hidden from the purview of the HIPs providing
health information and prevents HIPs from providing differentiated service to HIUs.
Each HIP-facing consent artefact is sent by the CM to the respective HIP using a consent notification. As
in the case of HIU-targeted consent notifications, HIP-targeted consent notifications also have a dual
purpose. The first is to notify HIPs about the generation of a consent artefact for fetching information
available from that HIP. In this case, the notification contains the artefact ID as well as the consent
artefact itself. The second purpose is to notify the HIP about a change in status of an already generated
consent artefact i.e. to notify the HIP that an artefact has been revoked, paused or resumed by the user.
In this case, the notification contains only the artefact ID. In both cases, the notification contains a status
attribute which is set to either GRANTED, REVOKED, PAUSED or RESUMED. In both cases, the
corresponding HIP system must send an acknowledgement for receipt of the consent notification via the
/consents/hip/on-notify APIs, as shown in the diagram. Acknowledgement is important for the CM to be
assured that the HIP received the consent notification.

37. 3.3.6 Data flow
The data flow takes place in roughly three stages. In the first stage, the HIU system (via its associated
health repository) communicates a health information request to the HIP system. This communication
happens via the CM, which sets a transaction ID (txn-id below) for the entire data flow. The transaction
ID is communicated to the HIU’s repository as well as the HIP’s repository. Within the health information
request, the HIU’s health repository embeds three key elements:
● The consent ID corresponding to the consent artefact against which the information request is
being made
● A ​data push URL. ​This is a callback URL where the information can be pushed by the HIP’s health
repository. The HIU may choose to specify a URL which hides its identity from the HIP system to
the extent possible. In particular, this URL need not be the same as the access URL specified by
the HIU at the time of registration with the gateway provider.
● A set of other parameters (denoted as ​params ​in the flow diagram). This includes the date-time
range for which information is requested and a set of encryption parameters to enable the HIP
repository to encrypt the information. In this standard, we use the Diffie-Hellman based
encryption for encrypting health information. More details on this are forthcoming and will be
provided in Section 4.
All this information is relayed from the HIU’s health repository to the CM (via the gateway) and then
from the CM to the HIP’s health repository (via the gateway), as shown in the diagram.
In the next stage, the HIP health repository validates the information request. For this, (a) it ensures that
the consent ID corresponds to an artefact that is neither expired, revoked nor paused; (b) the date-time
range specified in the request is contained in the time window for which the consent artefact allows
information access; (c) the encryption parameters are correctly defined. Once validated, the repository
(or the HIP system) encrypts the requested health records and sends the encrypted data, along with the
previously obtained transaction ID, to the data push URL communicated by the HIU. The encrypted data
must also be ​digitally signed ​using a long-term private key associated with the HIP system.

38. In the third and final stage, notifications are sent to the CM by the sending and receiving systems. The
HIP’s health repository sends a notification indicating that information was transmitted and the HIU
system (or the HIU’s health repository) sends a notification when it receives the information, indicating
whether the information fetch succeeded or failed.
4 Non-functional Requirements
Besides adhering to the API specifications defined in the preceding section, CMs and health repositories
are also required to fulfill a set of non-functional requirements which will ensure high security and
reliability of information in HIFs. Details of these requirements are forthcoming.