> For the complete documentation index, see [llms.txt](https://docs.coronasafe.network/abdm-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coronasafe.network/abdm-documentation/implementers-guide/building-hip.md). # Building HIP API Documentation for building the HIP is available here: [HIP APIs![](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAACXBIWXMAACxLAAAsSwGlPZapAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAIDSURBVHgB7dpBUsIwFAbgPxH3HkFvoCeQDc648wbgQRBwvIf1BrpidFzUG3gEjsBeJPbBMCIgCSVJX8r7Zlyohen/Q9KmLSCEEEKIQ6Wct+wPmzhq9IqXnAPmBL50W+v7MHjNoHUbPmx6/yUNuHh4b8OYbP6LQZ1o6xb94elv+PqxF9A47qHG7AUYc4Mac5kD1ic8pTJMpx8IReusKD7fuo1SNEk2sSe3SXAVhb+7yhBKt5Vv/f98Um7CA/sQ4ObPEWl/aRXgOTxJpwB7+GeUkEYBtvDG3BY/LyiBfwEu4feYkHkXEDg84VtAhPCEZwGRwhN+BUQMT3gVEDk84VNABeFJubWAbz7CKzWaLdJ2VH0Bvj75+QIqx46qHQIVfe2XVVcAg/CkmgKYhCfxC2AUnsSdBEOGv3/rFEeBx7W/W+4LxPsGMPvkF+IUwDQ8CV8A4/AkbAHMw5NwBSQQnoQpIJHwxH8BtpupjMKTAAVcj2YhN2EWnoQZAhRytQSG4Um4SXC5BKbhSdjDIIX+npxxDU/CnwjRnMBYeneHPZMCcOCkABy4cleEtL4srsCAFdons/tDnC4FjLH6pJgxdPmpA042hx9bXuU0BD6RKqWsj824FDBAqiZf1n23F0C3nP5b3XFG++xwFup2FFic08M8wWFcVYj2LYc2F5zXH0IIIYTg4Qf5mSgwxEiacwAAAABJRU5ErkJggg==)](https://sandbox.abdm.gov.in/swagger/ndhm-hip.yaml) [**Link to HIP Document**![](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAACXBIWXMAACxLAAAsSwGlPZapAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAIDSURBVHgB7dpBUsIwFAbgPxH3HkFvoCeQDc648wbgQRBwvIf1BrpidFzUG3gEjsBeJPbBMCIgCSVJX8r7Zlyohen/Q9KmLSCEEEKIQ6Wct+wPmzhq9IqXnAPmBL50W+v7MHjNoHUbPmx6/yUNuHh4b8OYbP6LQZ1o6xb94elv+PqxF9A47qHG7AUYc4Mac5kD1ic8pTJMpx8IReusKD7fuo1SNEk2sSe3SXAVhb+7yhBKt5Vv/f98Um7CA/sQ4ObPEWl/aRXgOTxJpwB7+GeUkEYBtvDG3BY/LyiBfwEu4feYkHkXEDg84VtAhPCEZwGRwhN+BUQMT3gVEDk84VNABeFJubWAbz7CKzWaLdJ2VH0Bvj75+QIqx46qHQIVfe2XVVcAg/CkmgKYhCfxC2AUnsSdBEOGv3/rFEeBx7W/W+4LxPsGMPvkF+IUwDQ8CV8A4/AkbAHMw5NwBSQQnoQpIJHwxH8BtpupjMKTAAVcj2YhN2EWnoQZAhRytQSG4Um4SXC5BKbhSdjDIIX+npxxDU/CnwjRnMBYeneHPZMCcOCkABy4cleEtL4srsCAFdons/tDnC4FjLH6pJgxdPmpA042hx9bXuU0BD6RKqWsj824FDBAqiZf1n23F0C3nP5b3XFG++xwFup2FFic08M8wWFcVYj2LYc2F5zXH0IIIYTg4Qf5mSgwxEiacwAAAABJRU5ErkJggg==)](https://sandbox.abdm.gov.in/static/media/Building%20HIP%20System%20_%20API%20Flow_M2__Documentation.d3949bd2.pdf) The flows which have to be built are: #### 1. Discovery of the patient’s information at the HIP When the gateway calls an HIP system and requests for a particular patient’s records with a set of verifiable Ids, the process of information discovery begins. Upon receipt of the request, the HIP health repository reverts with a set of care context labels (in masked form). The following flow diagram details the flows that take place during patient information discovery from the HIP perspective

Discovery

#### 2. Verify the patient and link the carecontext as requested by the patient This flow begins once a patient initiates a link request to the HIP to link the care context to the patient’s Consent Manager’s User ID. To enable the linking, the HIP system returns a link reference number along with the authentication type and its associated parameters. The HIP system sends an OTP to the patient’s phone number. Note, the phone number for OTP communication from HIP may be the same as verified by the CM or maybe a different number that the patient has chosen as preferred mode of communication with HIP - meaning it's up to the HIP to choose the phone number it sends OTP to. The patient, via patient app, submits the OTP received from the HIP system within the stipulated time. If the patient is successfully authenticated by the HIP, the linking is now complete. The following flow diagrams details the flows that take place while linking to a health repository representing an HIP

Linking

#### 3. Consent Request notification from an HIU to Consent Manager Obtaining the patient’s consent for information sharing begins when the HIU system issues a consent request to the consent manager for the patient’s data. The patient can view the request details, and choose to either grant consent or deny it. The CM, notifies the HIU, and also sends a notification to the HIP of the patient’s consent if granted. The following flow diagrams detail the flows that take place when patient provides consent and the notification that is sent to the HIP

Consent Notification from CM to HIP

#### 4. Data request and transfer The data request and transfer process between the HIU, CM and HIP passes through the following three stages: **First Stage** * The HIU system for patient’s health information to the HIP, through the CM against a valid granted consent. * The CM assigns a transaction 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 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. * 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. 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 gateway). **Second Stage** Once the HIP repository receives the information, it first validates the information request, as follows: * The HIP finds out if the consent ID corresponds to an expired, paused or revoked artefact. * It then checks if the request’s date-time range will correspond to the range for which the consent artefact allows information access. It also ensures that the encryption parameters are correctly defined. * Once the above checks are made and validated, the HIP health repository encrypts the requested health records and forwards it along with the transaction ID to the HIU’s data push URL, after signing the encrypted data with its long-term private key. **Third Stage** Finally, the CM receives notifications from both the HIP and the HIU. The HIP’s health repository notifies the CM that the requested information was transmitted to the HIU. The HIU’s health repository sends a notification that the requested information was successfully received, or that the request failed. All above 3 stages that pertains to HIP are shown in the following diagram:

Health Data Request and Transfer

#### 5. Share Patient profile with HIP Patients can share their profile details to a HIP via gateway. To achieve this, the gateway will forward the patient profile details to the concerned HIP and HIP will perform an acknowledgement to the gateway. The following flow diagram details the flows that take place during patient profile sahre from the HIP perspective

Share Patient Profile

ABHA App already has a functionality where a user can scan a QR Code placed at the health facility counter from within the app and share his/her profile details with the ABDM compliant Health facility (HIP) and do the express registration. This feature is being enhanced to now support the user scanning the QR Code using the phone’s camera or any other scanner. User would now have an option to proceed with the express registration with/without an app installed in the phone which would enable increased adoption as well. When a user scans the Health Facility QR code at the facility counter using the phone’s camera, the following use cases may trigger: **Use Case 1: ABDM compliant PHR application is already installed in user’s phone** After scanning the QR code, the user sees a pop-over list of all the PHR apps installed in his phone. He may select any application from this list and opens that application. * a. **User is not logged-on in the PHR app :** User is not logged-on in the PHR app: Once the user selected application launches, he/she will be redirected to the login page. After the successful login, he/she will be redirected to the share profile page. * b. **User is already logged-on in the PHR app:** Once the user selected application launches, user will be redirected to the share profile page. For instance, here ABHA SBX app is already installed in the device. When the user scans the QR code with using any 3rd party camera or scanner, the flow is as below: ![](https://sandbox.abdm.gov.in/static/media/Builiding_HIP.3a5b8208.png) **Use Case 2: No ABDM compliant PHR application is installed** After scanning the QR code, the user sees a browser from where he/she would be redirected to a User Initiated Deep link web page. This webpage will show the list of all the ABDM compliant PHR applications, from where the user has an option to select any application of his choice. The user would then be redirected to the respective application’s play store or Appstore page to install the app. Once the app is installed, the user may register/login and then would be redirected to the share profile page. For instance, when user has no application installed on his phone, the flow will be as below: ![](https://sandbox.abdm.gov.in/static/media/Builiding_HIP1.319fa8d0.png) 1. **Responsibilities of the PHR App** 2. **Support the intent for Share profile:** The app must publish the intent to support the URL “phr.abdm.gov.in” and respond as per the 2 use cases above if invoked 3. **Display the information that will be shared to the user:** All the information that will be shared with the HIP like Name, Date of Birth, Gender, Address, PHR Address, ABHA No, etc. 4. **Take consent from the user for sharing the details:** The PHR app must present the following consent language Once the user provides the consent and clicks on **“SHARE”,** his details would be shared via the HIE-CM by calling the share-profile API. The HIE-CM would verify this is a valid HIP and then call the share-profile API on the end point URL configured for the HIP. With this, the user completes the express registration and has also provided his consent to HIP to link his/her health records with the ABHA Address shared with the profile details. ![](https://sandbox.abdm.gov.in/static/media/Builiding_HIP2.a7416d9c.png)\ **Android Platform** Below intent needs to be added in the AndroidManifest.xml file
**iOS Platform-To be updated soon.**
**Specifications for the Health Facility QR Code:** Health facilities must first register in the Health Facility Registry and link with their HRP software before they can use the share feature. The health facility can generate a printable QR code for its facility using the QR code generator application at this link [https://www.the-qrcode-generator.com/![](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAACXBIWXMAACxLAAAsSwGlPZapAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAIDSURBVHgB7dpBUsIwFAbgPxH3HkFvoCeQDc648wbgQRBwvIf1BrpidFzUG3gEjsBeJPbBMCIgCSVJX8r7Zlyohen/Q9KmLSCEEEKIQ6Wct+wPmzhq9IqXnAPmBL50W+v7MHjNoHUbPmx6/yUNuHh4b8OYbP6LQZ1o6xb94elv+PqxF9A47qHG7AUYc4Mac5kD1ic8pTJMpx8IReusKD7fuo1SNEk2sSe3SXAVhb+7yhBKt5Vv/f98Um7CA/sQ4ObPEWl/aRXgOTxJpwB7+GeUkEYBtvDG3BY/LyiBfwEu4feYkHkXEDg84VtAhPCEZwGRwhN+BUQMT3gVEDk84VNABeFJubWAbz7CKzWaLdJ2VH0Bvj75+QIqx46qHQIVfe2XVVcAg/CkmgKYhCfxC2AUnsSdBEOGv3/rFEeBx7W/W+4LxPsGMPvkF+IUwDQ8CV8A4/AkbAHMw5NwBSQQnoQpIJHwxH8BtpupjMKTAAVcj2YhN2EWnoQZAhRytQSG4Um4SXC5BKbhSdjDIIX+npxxDU/CnwjRnMBYeneHPZMCcOCkABy4cleEtL4srsCAFdons/tDnC4FjLH6pJgxdPmpA042hx9bXuU0BD6RKqWsj824FDBAqiZf1n23F0C3nP5b3XFG++xwFup2FFic08M8wWFcVYj2LYc2F5zXH0IIIYTg4Qf5mSgwxEiacwAAAABJRU5ErkJggg==)](https://www.the-qrcode-generator.com/)
The content of the QR code is a URL in the following format [https://phrsbx.abdm.gov.in/share-profile?hip-id=IN3410000260\&counter-id=12345![](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAACXBIWXMAACxLAAAsSwGlPZapAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAIDSURBVHgB7dpBUsIwFAbgPxH3HkFvoCeQDc648wbgQRBwvIf1BrpidFzUG3gEjsBeJPbBMCIgCSVJX8r7Zlyohen/Q9KmLSCEEEKIQ6Wct+wPmzhq9IqXnAPmBL50W+v7MHjNoHUbPmx6/yUNuHh4b8OYbP6LQZ1o6xb94elv+PqxF9A47qHG7AUYc4Mac5kD1ic8pTJMpx8IReusKD7fuo1SNEk2sSe3SXAVhb+7yhBKt5Vv/f98Um7CA/sQ4ObPEWl/aRXgOTxJpwB7+GeUkEYBtvDG3BY/LyiBfwEu4feYkHkXEDg84VtAhPCEZwGRwhN+BUQMT3gVEDk84VNABeFJubWAbz7CKzWaLdJ2VH0Bvj75+QIqx46qHQIVfe2XVVcAg/CkmgKYhCfxC2AUnsSdBEOGv3/rFEeBx7W/W+4LxPsGMPvkF+IUwDQ8CV8A4/AkbAHMw5NwBSQQnoQpIJHwxH8BtpupjMKTAAVcj2YhN2EWnoQZAhRytQSG4Um4SXC5BKbhSdjDIIX+npxxDU/CnwjRnMBYeneHPZMCcOCkABy4cleEtL4srsCAFdons/tDnC4FjLH6pJgxdPmpA042hx9bXuU0BD6RKqWsj824FDBAqiZf1n23F0C3nP5b3XFG++xwFup2FFic08M8wWFcVYj2LYc2F5zXH0IIIYTg4Qf5mSgwxEiacwAAAABJRU5ErkJggg==)](https://phrsbx.abdm.gov.in/share-profile?hip-id=IN3410000260\&counter-id=12345) **hip-id:** Must be a valid Health Facility Registry ID issued by HFR **counter-id:** Can be any facility decided alphanumeric string. This field is passed back to the facility as part of the share-profile API call and can be used to identify the physical location where the QR code is present. **QR Code Guidelines if not using the QR generator from ABDM:** 1. Powered by ABDM must be part of the printed QR as in above image 2. The minimum height of the ABDM logo should be 25 pixels. **Note:** * While scanning the QR code from an android device, the experience may differ based on android version, brand of the mobile and skin of the android OS. * The experience may also differ based on the application from which the user is scanning the QR code. #### 6. Send SMS to Patient HIPs can send SMS to patients in case they have not registered and do not have a healthid after their visit. HIPs will call gateway with phone number, care-context-details and an optional deeplink URL. The following flow diagram details the flows that take place during "Sending SMS to Patient" from the HIP perspective

Send SMS to Patient

Please note: * The above flow has been demonstrated in the [third Webinar](https://www.youtube.com/watch?v=l8TiGXX8E34\&feature=youtu.be) * In order to see data on the ABHA Mobile Application, the data transfer should happen within certain time frame (10 mins). * You can also use the [HIU web interface](https://dev.ndhm.gov.in/hiu#/hiu/login) to test your HIP. ### HIP initiated linking HIP initiated linking is a process where the HIP can link the patient’s care context with the ABHA Number when the HIP has finished the patient registration and has uploaded the health records in their system To achieve this the HIPs need to do the following: 1. Get user auth for the action they want to perform. There are two different modes of Authentication - * Mediated (Mobile OTP, Aadhaar OTP, User Demographics) * Direct \ While seeking user auth, the HIP must send purpose of auth, current supported purposes are
* 1\. LINK - for purpose of adding care-contexts subsequently. User details are not returned in this case. * 2\. KYC - for getting basic user details. * 3\. KYC\_AND\_LINK - for requesting user details Once the user authentication is confirmed, CM returns “linking token” via /auth/on-confirm API. **NOTE** for KYC purpose, "linking token" is not returned. 2. Using the "linking token" returned above for linking, HIP can subsequently add care-contexts in subsequent API call /links/link/add-contexts. The following sections describe the flows to be built by HIP. #### 1. HIP initiated linking for the patients with mobile number The hospital registers the patient and typically uploads patient records in HIP’s EMR/EHR systems. The hospital will ask the patient if they wish to link the hospital record with their ABHA Number. The hospital will then send the request to CM with the patient preferred authentication mode and the ABHA Number. If the patient preferred authentication mode is OTP based, then the patient will receive an OTP which is forwarded to the CM. The CM validates the OTP and creates a new access token just for the purpose of linking. This new access token is passed to the HIP. The HIP has to call the CM with the new access token to add the care contexts.

HIP initiated linking with authentication type as mobile OTP

#### 2. HIP initiated linking for the patients with demographic details If the patient preferred authentication mode is user demographic based, then the patient will have to share their name, YOB, gender which is forwarded to the CM. The CM validates the user details and creates a new access token just for the purpose of linking. This new access token is passed to the HIP. The HIP has to call the CM with the new access token to add the care contexts.

HIP initiated linking with authentication type as user demographics

#### 3. HIP initiated linking for the patients with DIRECT auth In case of Direct authentication mode, HIP initiates the request with authMode DIRECT. This request gets added to the list of authorization requests on the consent manager which can be approved by the user. Once the user approves the direct authorization request, CM creates a new perpetual access token for the purpose of linking. This new access token is passed to the HIP. The HIP has to call the CM with the new access token to add the care contexts.

HIP initiated linking with authentication type as DIRECT