hiu_api.yaml

openapi: 3.0.0
info:
  version: "0.5"
  title: Health Repository Provider Specifications for HIU
  description: >
    The following are the specifications for the APIs to be implemented at the Health Repository end if an entity is only serving the role of a HIU. The specs are essentially duplicates from the Gateway and Bridge, but put together so as to make it clear to *HIUs* which set of APIs they should implement to participate in the network. 
    
      1. The APIs are organized by the flows - **identification**, **consent flow**, **data flow** and **monitoring**. They represent the APIs that are expected to be available at the HIU end by the Gateway. 
      2. For majority of the APIs, if Gateway has initiated a call, there are corresponding callback APIs on the Gateway. e.g for **/consents/hiu/notify** API on HIU end, its expected that a corresponding callback API **/consents/hiu/on-notify** on Gateway is called. Such APIs are organized under the **Gateway** label. 
      3. Gateway relevant APIs for HIUs are grouped under **Gateway** label. These include the APIs that HIPs are required to call on the Gateway. For example, to request a CM for consent, HIU would call **/consent-requests/init** API on gateway. 
      4. **NOTE**, in some of the API documentations below, **X-HIP-ID** is mentioned in header (for example in /auth/on-init). These are the cases, when a particular API is applicable for both HIU and HIP (e.g an entity is playing the role of HRP representing both HIU and HIP). If you are only playing the role of HIP, then only X-HIU-ID header will be sent 
servers:
  - url: https://dev.abdm.gov.in/gateway
    description: Sandbox
tags:
  - name: user auth
  - name: identification
  - name: consent flow
  - name: data flow
  - name: subscriptions
  - name: monitoring
  - name: Gateway
  - name: patient notification

paths:
  /v0.5/users/auth/fetch-modes:
    post:
      tags:
        - Gateway
      summary: Get a patient's authentication modes relevant to specified purpose
      description: >
        This API is meant for identify supported authentication modes for a patient given a specific purpose
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientAuthModeQueryRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientAuthModeQueryRequest'
      responses:
        '202':
          description: Request Accepted
        '400':
          description: >
            Invalid request, required attributes not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  
  /v0.5/users/auth/on-fetch-modes:
    post:
      tags:
        - user auth
      summary: Identification result for a consent-manager user-id
      description: |
        If a patient is found then **auth** attribute contains the supported modes for the specified purpose. 
        Otherwise, error is raised for invalid requests or for non-existent id.
        Note in addition to the "Authorization" header, one of the following headers must be specified
        1. **X-HIU-ID** if the requester is HIU (identified from /auth/fetch-modes requester.id)
        2. **X-HIP-ID** if the requester is HIP (identified from /auth/fetch-modes requester.id)
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIP-ID"
        - $ref: "#/components/parameters/X-HIU-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientAuthModeQueryResponse'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientAuthModeQueryResponse'
      responses:
        '202':
          description: Request Accepted
        '400':
          description: >
            Invalid request, required attributes not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  
  /v0.5/users/auth/init:
    post:
      tags:
        - Gateway
      summary: Initialize authentication from HIP
      description: >
        This API is called by HIPs to initiate authentication of users. A transactionId is retuned by the corresponding callback API for confirmation of user auth.
          1. **NOTE**, only **KYC** purpose is applicable for HIU. Hence HIU should only sent KYC in **query.authMode** in the request
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientAuthInitRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientAuthInitRequest'
      responses:
        '202':
          description: Request accepted
        '400':
          description: >
            **Causes:**
              * patient id is not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                
  /v0.5/users/auth/on-init:
    post:
      tags:
        - user auth
      summary: Response to user authentication initialization from HIP
      description: >
        If the patient's id is valid, CM will return a transactionId as initialization of user auth. If the request is valid, then 'auth.mode' will convey how the authentication should be done. The authentication can be *mediated* or *direct*. For mediated authentication modes, HIP or HIU is epected to send over relevant code (OTP/token) or demographic info via subsequent API call to /auth/confirm. for direct authentication case, CM will notify requester through/users/auth/notify API. 
        
          1. **auth.mode** conveys whats the mode of authentication is, and what is expected from HIP/HIU in the subsequent /auth/confirm API call. Possible values 
              1. MOBILE_OTP - auth via OTP to registered mobile. Mediated. 
              2. AADHAAR_OTP - auth initiated with Aadhaar with OTP. Mediated. 
              3. DEMOGRAPHICS - auth initiated with demographic verification
              4. DIRECT - for authentication directly with the patient. e.g. Mobile App, SMS. In this case, the HIP/HIU is not expected to call subsequent /auth/confirm call. CM will do direct authentication with the User (e.g. Mobile App, SMS etc) and will notify requester
          2. **meta.expiry** conveys the expiry time of the token and the authentication session
          3. **NOTE**, only one of **X-HIP-ID** or **X-HIU-ID** will be sent as part of header, not both. 
          4. **NOTE**, only KYC purpose is applicable for HIU
          
        The error section in the body, represents the potential errors that may have occurred. Possible reasons:
          1. Patient id is invalid
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIP-ID"
        - $ref: "#/components/parameters/X-HIU-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientAuthInitResponse'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientAuthInitResponse'
      responses:
        '202':
          description: Request accepted
        '400':
          description: >
            **Causes:**
              * required information not provided
              * neither authInit nor error specified 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v0.5/users/auth/confirm:
    post:
      tags:
        - Gateway
      summary: Confirmation request sending token, otp or other authentication details from HIP/HIU for confirmation
      description: >
        This API is called by HIP/HIUs to confirm authentication of users. The transactionId returned by the previous callback API /users/auth/on-init must be sent. If Authentication is successful the callback API will send an "access token" for subsequent purpose specific API calls. Note only **credential.authCode** or **credential.demographic** should be sent
          1. demographic details are only required for  demographic auth as of now. 
          2. demographic details are required only in MEDIATED cases and if the **auth.mode** so demands. e.g. if **auth.mode** is DEMOGRAPHICS. Usually for demographic authentication, the name, gender and DOB must be exactly as specified in User Account.
          3. demographic.identifier is optional, however maybe required if authentication so mandates. 
          4. credential.authCode is required for other MEDIATED authentication like MOBILE_OTP, AADHAAR_OTP. 
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientAuthConfirmRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientAuthConfirmRequest'
      responses:
        '202':
          description: Request accepted
        '400':
          description: >
            **Causes:**
              * transaction id is not provided or invalid
              * token or other auth confirmation details not provided or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v0.5/users/auth/on-confirm:
    post:
      tags:
        - user auth
      summary: callback API for /auth/confirm (in case of MEDIATED auth) to confirm user authentication or not
      description: >
        This API is called by CM to confirm authentication of users.
        
          1. **auth.accessToken** - is specific to the purpose mentioned in the /auth/init. This token needs to be used for initiating the intended action. For example for HIP initiated linking of care-contexts
          2. **NOTE**, only one of **X-HIP-ID** or **X-HIU-ID** will be sent as part of header, not both.     
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIP-ID"
        - $ref: "#/components/parameters/X-HIU-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientAuthConfirmResponse'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientAuthConfirmResponse'
      responses:
        '202':
          description: Request accepted
        '400':
          description: >
            **Causes:**
              * required details not provided
              * neither auth nor error specified 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse' 
  
  /v0.5/patients/find:
    post:
      tags:
        - Gateway
      summary: Identify a patient by her consent-manager user-id
      description: >
        This API is meant for identify to patient given her consent-manager-user-id
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientIdentificationRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientIdentificationRequest'
      responses:
        '202':
          description: Request Accepted
        '400':
          description: >
            Invalid request, required attributes not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/patients/on-find:
    servers:
      - url: https://dev.abdm.gov.in/hiu
    post:
      tags:
        - identification
      summary: Identification result for a consent-manager user-id
      description: |
        If a patient is found then patient.name contains the patients name. 
        Otherwise, patient is not provided, and possibly error is raised for invalid requests
        Note in addition to the "Authorization" header, one of the following headers must be specified
        1. specify **X-HIU-ID** if the requester is HIU (identified from /find requester.id)
        2. specify **X-HIP-ID** if the requester is HIP (identified from /find requester.id)
      parameters:
        - $ref: "#/components/parameters/authorization"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientIdentificationResponse'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientIdentificationResponse'
      responses:
        '202':
          description: Request Accepted
        '400':
          description: >
            Invalid request, required attributes not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/consent-requests/init:
    post:
      tags:
        - Gateway
      summary: Create consent request
      description: Creates a consent request to get data about a patient by HIU user.
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/ConsentRequest'
      responses:
        '202':
          description: Request Accepted
        '400':
          description:  >
            **Causes:**
              * Invalid data sent 
              * Required attributes not mentioned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description:  >
            **Causes:**
              * Expired/Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/health-information/hiu/on-request:
    servers:
      - url: https://dev.abdm.gov.in/hiu
    post:
      tags:
        - data flow
      summary: Health information data request
      description: >
        Callback API for acknowledgement of Health information request made by HIU. Gateway calls this API when request has validated for the specified  consent id. Either the **hiRequest** or **error** would be specified. If the health info request was valid, then the ***hiRequest.transactionId*** specifies the transaction context against which HIP would send over the data. 
        Possible cases of errors are
          1. **Invalid consent artefact id**
          2. **Consent has expired**
          3. **Date ranges are invalid**
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIU-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HIUHealthInformationRequestResponse'
          application/xml:
            schema:
              $ref: '#/components/schemas/HIUHealthInformationRequestResponse'
      responses:
        '202':
          description: Request Accepted
        '400':
          description: >
            **Causes:**
              * Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Token is invalid or Link has expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/health-information/notify:
    post:
      tags:
        - Gateway
      summary: Notifications corresponding to events during data flow
      description: |
        API called by HIU and HIP during data-transfer.
        1. HIP on transfer of data would send **sessionStatus** - one of [TRANSFERRED, FAILED]
        2. HIP would also send **hiStatus** for each *careContextReference* - on of [DELIVERED, ERRORED]
        3. HIU on receipt of data would send **sessionStatus** - one of [TRANSFERRED, FAILED]. For example, FAILED when if data was not sent or if invalid data was sent
        4. HIU would also send **hiStatus** for each *careContextReference* - one of [OK, ERRORED]
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/X-CM-ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HealthInformationNotification'
          application/xml:
            schema:
              $ref: '#/components/schemas/HealthInformationNotification'
      responses:
        '202':
          description: Notification is Accepted
        '400':
          description: >
            **Causes:**
              * Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description:  >
            **Causes:**
              * Expired/Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/health-information/transfer:
    servers:
      - url: https://dev.abdm.gov.in/hiu
    post:
      tags:
        - data flow
      summary: health information transfer API
      description: >
        **NOTE**: This API is actually the callback URL that is passed as **dataPushUrl** in the data request API - /v0.5/health-information/hip/request. This API is directly called by HIP Data Bridge and is not mediated via CM, and hence not routed through the Gateway. 
          1. This API should be implemented at HIU side. It maybe implemented by the Data Bridge representing the HIU. 
          2. Entry elements maybe ***content*** or ***link***, although for version 1, entry ***content*** is preferred. 
          3. Entry ***content*** (or even link reference content) must be encrypted by means of Elliptic-curve Diffie–Hellman Key Exchange, utilizing the HIU keymaterials that are passed through the data request API - /v0.5/health-information/hip/request. 
          4. Media contains the mimetype of content, and for v1, it is "application/fhir+json"
          5. checksum is Md5 checksum of the data conent, before encryption
          6. Please refer to the ABDM Sandbox documentation for the format of FHIR bundle that is passed through content
      parameters:
        - $ref: '#/components/parameters/authorization'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataNotification'
          application/xml:
            schema:
              $ref: '#/components/schemas/DataNotification'
      responses:
        '202':
          description: Data accepted.
        '401':
          description: >
            **Causes:**
              * Invalid/Expired/Empty token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream services are down
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/consent-requests/on-init:
    servers:
      - url: https://dev.abdm.gov.in/hiu
    post:
      tags:
        - consent flow
      summary: Response to consent request
      description: |
        Result of consent request creation for a patient. **id** represents the consentrequest id created by CM. The result must contain either **id** or the **error** caused. <br/>
          Reasons for error may be
          * Invalid references (e.g patient id, hiu id), purpose, hiTypes, ranges, persmission
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIU-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentRequestInitResponse'
          application/xml:
            schema:
              $ref: '#/components/schemas/ConsentRequestInitResponse'
      responses:
        '202':
          description: Request Accepted
        '400':
          description:  >
            **Causes:**
              * Invalid data sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description:  >
            **Causes:**
              * Expired/Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/consent-requests/status:
    post:
      tags:
        - Gateway
      summary: Get consent request status
      description: Get status of consent request done previously
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentRequestStatusRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/ConsentRequestStatusRequest'
      responses:
        '202':
          description: Request Accepted
        '400':
          description: >
            **Causes:**
              * Invalid data sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description:  >
            **Causes:**
              * Expired/Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/consent-requests/on-status:
    servers:
      - url: https://dev.abdm.gov.in/hiu
    post:
      tags:
        - consent flow
      summary: Result of consent request status
      description: |
        Result of consent request done previously. Status of request can be GRANTED,  DENIED, EXPIRED. If the request was GRANTED, then 
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/X-HIU-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HIUConsentRequestStatus'
          application/xml:
            schema:
              $ref: '#/components/schemas/HIUConsentRequestStatus'
      responses:
        '202':
          description: Request Accepted
        '400':
          description: >
            **Causes:**
              * Invalid data sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description:  >
            **Causes:**
              * Expired/Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/consents/hiu/notify:
    servers:
      - url: https://dev.abdm.gov.in/hiu
    post:
      tags:
        - consent flow
      summary: Consent notification
      description: |
       Health information user will get notified about the consent request granted or denied, consent revoked, consent expired. 
       1. For consent request grant, status=GRANTED, consentRequestId=<consent-request-id>, and consentArtefacts is an array of generated consent artefact Ids.
       2. For consent request expiry, status=EXPIRED, consentRequestId=<consent-request-id>
       3. For consent request denied, status=DENIED, consentRequestId=<consent-request-id>
       4. For consent revocation, status=REVOKED, consentArtefacts is an array of revoked consent artefact ids
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/X-HIU-ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HIUConsentNotificationEvent'
      responses:
        '202':
          description: Request Accepted.
        '401':
          description: >
            **Causes:**
              * Invalid/Expired/Empty token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream services are down
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/consents/hiu/on-notify:
    post:
      tags:
        - Gateway
      summary: Consent notification
      description: |
        This API is called by HIU as acknowledgement to consent notifications, specifically for cases when consent is REVOKED or EXPIRED.
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/X-CM-ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HIUConsentNotificationResponse'
      responses:
        '202':
          description: Request Accepted.
        '401':
          description: >
            **Causes:**
              * Invalid/Expired/Empty token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream services are down
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/consents/fetch:
    post:
      tags:
        - Gateway
      summary: Get consent artefact
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentFetchRequest'
      responses:
        '202':
          description: Request Accepted
        '400':
          description:  >
            **Causes:**
              * Invalid data sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description:  >
            **Causes:**
              * Expired/Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/consents/on-fetch:
    servers:
      - url: https://dev.abdm.gov.in/hiu
    post:
      tags:
        - consent flow
      summary: Result of fetch request for a consent artefact
      description: |
       Must contain either consent or error. Possible reason of errors are 
       1. consentId passed through /fetch is invalid
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIU-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentArtefactResponse'
          application/xml:
            schema:
              $ref: '#/components/schemas/ConsentArtefactResponse'
      responses:
        '202':
          description: Request Accepted
        '400':
          description:  >
            **Causes:**
              * Invalid data sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description:  >
            **Causes:**
              * Expired/Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/health-information/cm/request:
    post:
      tags:
        - Gateway
      summary: Health information data request
      description: >
        Request for Health information against a consent id. CM would generate a transactionId against each consent and pass it as trnasaction context / correlation id to the HIP and also return the same to HIU via /on-request. 
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HIRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/HIRequest'
      responses:
        '202':
          description: Request Accepted
        '400':
          description: >
            **Causes:**
              * Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Token is invalid or Link has expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  
  /v0.5/heartbeat:
    servers:
      - url: https://dev.abdm.gov.in/hiu
    get:
      tags:
        - monitoring
      summary: Informs about server status
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/HeartbeatResponse'
  /v0.5/sessions:
    post:
      tags:
        - Gateway
      summary: Get access token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/SessionRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/SessionResponse'
        '404':
          description: >
            **Causes:**
              * Invalid consent request id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description:  >
            **Causes:**
              * Invalid client Id or secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/.well-known/openid-configuration:
    get:
      tags:
        - Gateway
      summary: Get openid configuration
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenIdConfiguration'
            application/xml:
              schema:
                $ref: '#/components/schemas/OpenIdConfiguration'
        '404':
          description: >
            **Causes:**
              * Invalid consent request id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/certs:
    get:
      tags:
        - Gateway
      summary: Get certs for JWT verification
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Certs'
            application/xml:
              schema:
                $ref: '#/components/schemas/Certs'
        '404':
          description: >
            **Causes:**
              * Invalid consent request id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  
  /v0.5/users/auth/notify:
    post:
      tags:
        - user auth
      summary: notification API in case of DIRECT mode of authentication by the CM
      description: >
        This API is called by CM to confirm authentication of users. The transactionId returned is same as that passed in /auth/on-init. The "auth.status" conveys whether the request was GRANTED or DENIED.
        
          1. **auth.accessToken** - is specific to the purpose mentioned in the /auth/init. This token needs to be used for initiating the intended action. For example for HIP initiated linking of care-contexts
          2. **NOTE**, only one of **X-HIP-ID** or **X-HIU-ID** will be sent as part of header, not both.
          3. The payload is conditional to the purpose of auth. If purpose specified in /auth/init is KYC or KYC_AND_LINK, then patient details are passed. **auth.accessToken** is passed only if the purpose is LINK or KYC_AND_LINK.
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIP-ID"
        - $ref: "#/components/parameters/X-HIU-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientAuthNotification'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientAuthNotification'
      responses:
        '202':
          description: Request accepted
        '400':
          description: >
            **Causes:**
              * required details not provided
              * neither auth nor error specified 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'                
  /v0.5/users/auth/on-notify:
    post:
      tags:
        - Gateway
      summary: callback API by HIU/HIPs as acknowledgement of auth notification
      description: >
        This API is called by HIU/HIPs to confirm acknowledgement for receipt of auth notification is case of DIRECT authentication. 
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientAuthNotificationAcknowledgement'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientAuthNotificationAcknowledgement'
      responses:
        '202':
          description: Request accepted
        '400':
          description: >
            **Causes:**
              * required details not provided
              * neither auth nor error specified 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >
            **Causes:**
              * Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'                
  
  /v0.5/subscription-requests/cm/init:
    post:
      tags:
        - Gateway
      summary: Request for subscription
      description: creates a request for subscription. The subscription categories can be for care-contexts linkages or availability of data against existing care-contexts. Note that the requester must have HIU role
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
      responses:
        '202':
          description: Request Accepted
        '400':
          description:  >
            **Causes:**
              * Invalid data sent 
              * Required attributes not mentioned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description:  >
            **Causes:**
              * Expired/Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/subscription-requests/hiu/on-init:
    post:
      tags:
        - subscriptions
      summary: callback API for the /subscription-requests/cm/init to notify a HIU on acceptance/acknowledgement of the request for subscription. 
      description: |
       This callback API acknowledges the request for subscription from a HIU, and sends back a "id" that will be used when the patient/user approves or denies the subscription. 
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/X-HIU-ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HIUSubscriptionRequestReceipt'
      responses:
        '202':
          description: Request Accepted.
        '401':
          description: >
            **Causes:**
              * Invalid/Expired/Empty token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream services are down
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/subscription-requests/hiu/notify:
    post:
      tags:
        - subscriptions
      summary: Notification for subscription grant/deny/revoke
      description: | 
        This API is used by CM to notify a HIU to grant or deny a request for subscription, and also to notify that in case an existing subscription is revoked or expired. For notifying that a particular subscription request was GRANTED or DENIED, the **subscriptionRequestId** is passed. 
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIU-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionApprovalNotification'
          application/xml:
            schema:
              $ref: '#/components/schemas/SubscriptionApprovalNotification'
      responses:
        '202':
          description: Request Accepted
        '400':
          description:  >
            **Causes:**
              * Invalid data sent 
              * Required attributes not mentioned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description:  >
            **Causes:**
              * Expired/Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/subscription-requests/hiu/on-notify:
    post:
      tags:
        - Gateway
      summary: Callback API for /subscription-requests/hiu/notify to acknowledge receipt of notification.
      description: |
        This API is called by HIU as acknowledgement to subscription request relevant notifications. 
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/X-CM-ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HIUSubscriptionRequestNotificationAcknowledgement'
      responses:
        '202':
          description: Request Accepted.
        '401':
          description: >
            **Causes:**
              * Invalid/Expired/Empty token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream services are down
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/subscriptions/hiu/notify:
    post:
      tags:
        - subscriptions
      summary: Notification to HIU on basis of a granted subscription
      description: |
        This API is used by CM to notify a HIU for notification relevant to subscription. Notifications are sent to subscribed HIUs whenever a new care-context is linked or new data is available on an existing linked care-context. 
        1. if event.category = LINK, then only care-contexts are passed when new care-contexts are linked for patient. 
        2. If event.category = DATA, then hiTypes are passed. Care-context is passed only if the subscribed HIU has any valid consent for that care-context
      
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIU-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HIUSubscriptionNotification'
          application/xml:
            schema:
              $ref: '#/components/schemas/HIUSubscriptionNotification'
      responses:
        '202':
          description: Request Accepted
        '400':
          description:  >
            **Causes:**
              * Invalid data sent 
              * Required attributes not mentioned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description:  >
            **Causes:**
              * Expired/Invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/subscriptions/hiu/on-notify:
    post:
      tags:
        - Gateway
      summary: Callback API for /subscriptions/hiu/notify to acknowledge receipt of notification.
      description: |
        This API is called by HIU as acknowledgement to consent notifications, specifically for cases when consent is REVOKED or EXPIRED.
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/X-CM-ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HIUSubscriptionNotificationAcknowledgment'
      responses:
        '202':
          description: Request Accepted.
        '401':
          description: >
            **Causes:**
              * Invalid/Expired/Empty token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >
            **Causes:**
              * Downstream services are down
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0.5/patients/status/notify:
    post:
      tags:
        - patient notification
      summary: Notification sent by Consent Manager
      description: |
        This API is to send patient's status (ACTIVE/DEACTIVATED/DELETED) to the HIU.
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-HIU-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HiuPatientStatusNotification'
          application/xml:
            schema:
              $ref: '#/components/schemas/HiuPatientStatusNotification'
      responses:
        '202':
          description: Request Accepted
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v0.5/patients/status/on-notify:
    post:
      tags:
        - Gateway
        - patient notification
      summary: Acknowledgment by HIU
      description: |
        This  API is to check if the Status is successfully sent for patient (Active/Deactivate/DELETED) to HIU and then "status" will be "OK" with no error.
      parameters:
        - $ref: "#/components/parameters/authorization"
        - $ref: "#/components/parameters/X-CM-ID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientStatusNotification'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatientStatusNotification'
      responses:
        '202':
          description: Request Accepted
        '500':
          description: >
            **Causes:**
              * Downstream system(s) is down.
              * Unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'


components:
  parameters:
    authorization:
      name: Authorization
      in: header
      required: true
      description: Access token which was issued after successful login with gateway auth server, which will be sent by gateway to authenticate itself with API bridge.
      schema:
        type: string
    X-Origin-ID:
      name: X-Origin-ID
      in: header
      description: >
       Identifier of the health information provider user from which the request came.
       (Necessity of this header depends on the authentication at the Bridge)
       If gateway uses JWT authentication, from access token itself originator can be identified.
      schema:
        type: string
    X-HIP-ID:
      name: X-HIP-ID
      in: header
      required: true
      description: Identifier of the health information provider to which the request was intended.
      schema:
        type: string
    X-HIU-ID:
      name: X-HIU-ID
      in: header
      required: true
      description: Identifier of the health information user to which the request was intended.
      schema:
        type: string
    X-CM-ID:
      name: X-CM-ID
      in: header
      required: true
      description: Suffix of the consent manager to which the request was intended.
      schema:
        type: string
    LinkRefNumber:
      name: linkRefNumber
      in: path
      required: true
      description: Reference number for the link request made earlier.
      schema:
        $ref: '#/components/schemas/UuidSchema'
    ConsentRequestId:
      name: consentRequestId
      in: path
      required: true
      description: Consent request's identifier
      schema:
        type: string
        format: uuid
    ConsentId:
      name: consentId
      in: path
      required: true
      description: Consent request's identifier
      schema:
        type: string
        format: uuid
  schemas:
    UuidSchema:
      type: string
      format: uuid
      example: a1s2c932-2f70-3ds3-a3b5-2sfd46b12a18d
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          enum: [1000, 10001]
        message:
          type: string
      xml:
        name: Error
    consent:
      type: object
      required:
        - id
      properties:
        id:
          type: string
    DateRange:
      type: object
      required:
        - from
        - to
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
    HITypeEnum:
      type: string
      enum:
        - OPConsultation
        - Prescription
        - DischargeSummary
        - DiagnosticReport
        - ImmunizationRecord
        - HealthDocumentRecord
        - WellnessRecord
      xml:
        name: HIType
    ConsentStatus:
      type: string
      enum:
        - GRANTED
        - EXPIRED
        - DENIED
        - REQUESTED
        - REVOKED
    ConsentManagerPatientID:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          xml:
            attribute: true
          format: <user-id>@ndhm
          example: hinapatel@ndhm
    UsePurpose:
      type: object
      required:
        - text
        - code
      properties:
        text:
          type: string
        code:
          type: string
          description: From the fixed set, documented at refUri
        refUri:
          type: string
          format: uri
    Permission:
      type: object
      required:
        - accessMode
        - dateRange
        - dataEraseAt
        - frequency
      properties:
        accessMode:
          type: string
          enum: [VIEW, STORE, QUERY, STREAM]
        dateRange:
          type: object
          required:
            - from
            - to
          properties:
            from:
              type: string
              format: date-time
            to:
              type: string
              format: date-time
        dataEraseAt:
          type: string
          format: date-time
        frequency:
          type: object
          required:
            - unit
            - value
            - repeats
          properties:
            unit:
              type: string
              enum: [HOUR, WEEK, DAY, MONTH, YEAR]
            value:
              type: integer
            repeats:
              type: integer
      xml:
        name: Permission
    OrganizationRepresentation:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          xml:
            attribute: true
      xml:
        name: OrganizationResponse
    KeyMaterial:
      type: object
      required:
        - cryptoAlg
        - curve
        - dhPublicKey
        - nonce
      properties:
        cryptoAlg:
          type: string
          format: string
          example: ECDH
        curve:
          type: string
          format: string
          example: Curve25519
        dhPublicKey:
          $ref: '#/components/schemas/keyObject'
        nonce:
          type: string
          format: 32 byte string
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
    keyObject:
      type: object
      required:
        - expiry
        - parameters
        - keyValue
      properties:
        expiry:
          type: string
          format: date-time
        parameters:
          type: string
          format: string
          example: Curve25519/32byte random key
        keyValue:
          type: string
          format: string
    ConsentArtefactReference:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          example: '<consent-artefact-id>'
    HIUConsentNotificationEvent:
      type: object
      required:
        - requestId
        - timestamp
        - notification
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        notification:
          type: object
          required:
            - status
            - consentRequestId
          properties:
            consentRequestId:
              type: string
              example: '<consent-request-id>'
            status:
              $ref: '#/components/schemas/ConsentStatus'
            consentArtefacts:
              type: array
              items:
                $ref: '#/components/schemas/ConsentArtefactReference'
              description: if the status is GRANTED or REVOKED, then the consentArtefact references (Ids) must be specified.
    ConsentRequestInitResponse:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        consentRequest:
          type: object
          required:
            - id
          properties:
            id:
              type: string
              format: uuid
              description: id of the consent-request created
              example: f29f0e59-8388-4698-9fe6-05db67aeac46
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
      xml:
        name: ConsentRequestInitResponse
    TimestampSchema:
      type: string
      format: date-time
      description: Date time format in UTC, includes miliseconds YYYY-MM-DDThh:mm:ss.vZ
    RequestReference:
      type: object
      required:
        - requestId
      properties:
        requestId: 
          type: string
          format: uuid
          description: the requestId that was passed
    HeartbeatResponse:
      type: object
      required:
        - timestamp
        - status
      properties:
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        status:
          type: string
          enum:
            - UP
            - DOWN
        error:
          $ref: '#/components/schemas/Error'
      xml:
        name: HeartbeatResponse
    HIUConsentRequestStatus:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        consentRequest:
          type: object
          required:
            - id
            - status
            - consentArtefacts
          properties:
            id:
              type: string
              example: '<consent-request-id>'
            status:
              $ref: '#/components/schemas/ConsentStatus'
            consentArtefacts:
              type: array
              items:
                $ref: '#/components/schemas/ConsentArtefactReference'
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
    ConsentArtefactResponse:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        consent:
          type: object
          required:
            - consentDetail
            - status
            - signature
          properties:
            status:
              $ref: '#/components/schemas/ConsentStatus'
            consentDetail:
              type: object
              required:
                - consentId
                - createdAt
                - patient
                - careContexts
                - purpose
                - hip
                - hiu
                - consentManager
                - requester
                - permission
                - hiTypes
              properties:
                schemaVersion:
                  type: string
                  format: string
                consentId:
                  type: string
                  format: uuid
                createdAt:
                  type: string
                  format: date-time
                patient:
                  $ref: '#/components/schemas/ConsentManagerPatientID'
                careContexts:
                  type: array
                  items:
                    type: object
                    required:
                      - patientReference
                      - careContextReference
                    properties:
                      patientReference:
                        type: string
                        example: hinapatel79@hospital
                      careContextReference:
                        type: string
                        example: Episode1
                purpose:
                  $ref: '#/components/schemas/UsePurpose'
                hip:
                  type: object
                  allOf:
                    - $ref: '#/components/schemas/OrganizationRepresentation'
                    - xml:
                        name: hip
                hiu:
                  type: object
                  allOf:
                    - $ref: '#/components/schemas/OrganizationRepresentation'
                    - xml:
                        name: hiu
                consentManager:
                  type: object
                  allOf:
                    - $ref: '#/components/schemas/OrganizationRepresentation'
                    - xml:
                        name: consentManager
                requester:
                  $ref: '#/components/schemas/Requester'
                hiTypes:
                  type: array
                  items:
                    $ref: '#/components/schemas/HITypeEnum'
                permission:
                  $ref: '#/components/schemas/Permission'
            signature:
              type: string
              example: Signature of CM as defined in W3C standards; Base64 encoded
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
    Requester:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: Dr. Manju
        identifier:
          type: object
          required:
            - type
            - value
          properties:
            type: 
              type: string
              example: REGNO
            value:
              type: string
              example: "MH1001"
            system:
              type: string
              example: https://www.mciindia.org
    HIUHealthInformationRequestResponse:
        type: object
        required:
          - requestId
          - timestamp
          - resp
        properties:
          requestId:
            $ref: '#/components/schemas/UuidSchema'
          timestamp:
            $ref: '#/components/schemas/TimestampSchema'
          hiRequest:
            type: object
            required:
              - transactionId
              - sessionStatus
            properties:
              transactionId:
                $ref: '#/components/schemas/UuidSchema'
              sessionStatus:
                type: string
                enum:
                - REQUESTED
                - ACKNOWLEDGED
          error: 
            $ref: '#/components/schemas/Error'
          resp:
            $ref: '#/components/schemas/RequestReference'
    PatientIdentificationResponse:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        patient:
          type: object
          required:
            - id
            - name
          properties:
            id: 
              type: string
              example: hinapatel79@ndhm
            name:
              type: string
              example: Hina Patel
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
      xml:
        name: PatientIdentificationResponse
    DataNotification:
      type: object
      required:
        - transactionId
        - entries
        - keyMaterial
        - pageNumber
        - pageCount
      properties:
        pageNumber:
          type: integer
          description: Current page number.
        pageCount:
          type: integer
          description: Total number of pages.
        transactionId:
          type: string
          format: uuid
          description: Transaction Id issued when data requested.
        entries:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/EntryContent'
              - $ref: '#/components/schemas/EntryLink'
        keyMaterial:
          $ref: '#/components/schemas/KeyMaterial'
    EntryContent:
      type: object
      required:
        - content
        - media
        - checksum
        - careContextReference
      properties:
        content:
          type: string
          description: Encrypted content
          example: Encrypted content of data packaged in FHIR bundle
        media:
          type: string
          enum: ['application/fhir+json']
          description: mimetype of the content.
        checksum:
          type: string
          description: Md5 checksum of the content before encryption
        careContextReference:
          type: string
          example: RVH1008
          description: care context reference number.
    EntryLink:
      type: object
      required:
        - link
        - media
        - checksum
        - careContextReference
      properties:
        link:
          type: string
          description: Encrypted content
          example: https://data-from.net/sa2321afaf12e13
        media:
          type: string
          enum: ['application/fhir+json']
          description: mimetype of the content.
        checksum:
          type: string
          description: Md5 checksum of the content before encryption
        careContextReference:
          type: string
          example: NCC1701
          description: care context reference number.
    PatientIdentificationRequest:
      type: object
      required:
        - requestId
        - timestamp
        - query
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        query:
          type: object
          required:
            - patient
            - requester
          properties:
            patient:
              type: object
              required:
                - id
              properties:
                id:
                  type: string
                  example: hinapatel79@ndhm
            requester:
              type: object
              required:
                - type
                - id
              properties:
                type: 
                  type: string
                  enum: [HIU, HIP]
                id:
                  type: string
                  example: 100005
    ConsentRequest:
      type: object
      required:
        - requestId
        - timestamp
        - consent
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request. 
          example: "499a5a4a-7dda-4f20-9b67-e24589627061"
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        consent:
          type: object
          required:
            - purpose
            - patient
            - hiu
            - requester
            - hiTypes
            - permission
            - consentNotificationUrl
          properties:
            purpose:
              $ref: '#/components/schemas/UsePurpose'
            patient:
              type: object
              allOf:
                - $ref: '#/components/schemas/ConsentManagerPatientID'
                - xml:
                    name: patient
            hip:
              type: object
              allOf:
                - $ref: '#/components/schemas/OrganizationRepresentation'
                - xml:
                    name: hip
            careContexts:
              type: array
              items:
                $ref: '#/components/schemas/CareContextDefinition'
            hiu:
              type: object
              allOf:
                - $ref: '#/components/schemas/OrganizationRepresentation'
                - xml:
                    name: hiu
            requester:
              $ref: '#/components/schemas/Requester'
            hiTypes:
              type: array
              items:
                $ref: '#/components/schemas/HITypeEnum'
            permission:
              $ref: '#/components/schemas/Permission'
    ConsentRequestStatusRequest:
      type: object
      required:
        - consentRequestId
        - requestId
        - timestamp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        consentRequestId:
          type: string
    HIUConsentNotificationResponse:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        acknowledgement:
          type: array
          items:
            $ref: '#/components/schemas/ConsentAcknowledgement'
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
    ConsentAcknowledgement:
      type: object
      required:
        - status
        - consentId
      properties:
        status:
          type: string
          enum:
          - OK
          - UNKNOWN
        consentId:
          type: string
          example: <consent-artefact-id>
    ConsentFetchRequest:
      type: object
      required:
        - consentId
        - requestId
        - timestamp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        consentId:
          type: string
    HIRequest:
      type: object
      required:
        - requestId
        - timestamp
        - hiRequest
      properties:
        requestId:
          $ref: '#/components/schemas/UuidSchema'
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        hiRequest:
          type: object
          required:
            - consent
            - dataPushUrl
            - keyMaterial
            - dateRange
          properties:
            consent:
              $ref: '#/components/schemas/consent'
            dateRange:
              $ref: '#/components/schemas/DateRange'
            dataPushUrl:
              type: string
            keyMaterial:
              $ref: '#/components/schemas/KeyMaterial'
    SessionRequest:
      type: object
      required:
        - clientId
        - clientSecret
      properties:
        clientId:
          type: string
        clientSecret:
          type: string
    SessionResponse:
      type: object
      properties:
        accessToken:
          type: string
          example: eyJhbGciOiJSUzI1Ni.IsInR5cCIgOiAiSldUIiwia2lkIiA6ICJrVVp.2MXJQMjRyYXN1UW9wU2lWbkdZQUZIVFowYVZGVWpYNXFLMnNibTk0In0
        expiresIn:
          type: integer
          example: 1800
          description: In Minutes
        refreshExpiresIn:
          type: integer
          example: 1800
          description: In Minutes
        refreshToken:
          type: string
          example: eyJhbGciOiJSUzI1Ni.IsInR5cCIgOiAiSldUIiwia2lkIiA6ICJrVVp.2MXJQMjRyYXN1UW9wU2lWbkdZQUZIVFowYVZGVWpYNXFLMnNibTk0In0
        tokenType:
          type: string
          example: bearer
    OpenIdConfiguration:
      type: object
      properties:
        jwks_uri:
          type: string
          format: uri
          example: "https://ncg-gateway/certs"
    Certs:
      type: object
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/CertificateOrKeyGetSchema'
    CertificateOrKeyGetSchema:
      type: object
      properties:
        e:
          type: string
        kid:
          type: string
        kty:
          type: string
        n:
          type: string
        use:
          type: string
        x5c:
          type: array
          items:
            description: A PKIX certificate [RFC5280]
            type: string
        x5t:
          type: string
        x5t#S256:
          type: string
        alg:
          type: string
          
    PatientAuthPurpose:
      type: string
      enum: [LINK, KYC, KYC_AND_LINK]
      description: what is the purpose of user auth
    
    AuthenticationMode:
      type: string
      enum: ['MOBILE_OTP', 'DIRECT', 'DEMOGRAPHICS', 'AADHAAR_OTP']
      description: > 
        Subjected to CM specific capability
         1. MOBILE_OTP - for SMS OTP
         2. DIRECT - for authentication directly with the patient. e.g. Mobile App, SMS
         3. AADHAAR_OTP - for auth using OTP sent to Aadhaar number
         4. DEMOGRAPHICS - for auth using demographic verification.
    
    PatientAuthModeQueryRequest:
      type: object
      required:
        - requestId
        - timestamp
        - query
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        query:
          type: object
          required:
            - id
            - purpose
            - requester
          properties:
            id:
              type: string
              example: hinapatel79@ndhm
            purpose:
              $ref: '#/components/schemas/PatientAuthPurpose'
            requester:
              type: object
              required:
                - id
                - type
              properties:
                type: 
                  type: string
                  enum: [HIP, HIU]
                id:
                  type: string
                  example: "100005"
    
    PatientAuthModeQueryResponse:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        auth:
          type: object
          required:
            - purpose
            - modes
          properties:
            purpose:
              $ref: '#/components/schemas/PatientAuthPurpose'
            modes: 
              type: array
              items:
                $ref: '#/components/schemas/AuthenticationMode'
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
    
    PatientAuthInitRequest:
      type: object
      required:
        - requestId
        - timestamp
        - query
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        query:
          type: object
          required:
            - id
            - requester
            - purpose
          properties:
            id:
              type: string
              example: "hinapatel@ndhm"
              description: id  of the patient understood by the CM
            purpose:
              $ref: '#/components/schemas/PatientAuthPurpose'
            authMode:
              $ref: '#/components/schemas/AuthenticationMode'
            requester:
              type: object
              required:
                - type
                - id
              description: identification of requester
              properties:
                type: 
                  type: string
                  enum: [HIP, HIU]
                id:
                  type: string
                  example: 100005
      
    PatientAuthConfirmRequest:
      type: object
      required:
        - requestId
        - timestamp
        - transactionId
        - credential
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        transactionId:
          type: string
        credential:
          type: object
          description: note, demographic details are only required for demographic auth at this point.
          properties:
            authCode:
              type: string
            demographic:
              $ref: '#/components/schemas/PatientDemographic'
      
    PatientAuthInitResponse:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        auth:
          type: object
          required:
            - transactionId
            - mode
          properties:
            transactionId:
              type: string
            mode:
              $ref: '#/components/schemas/AuthenticationMode'
            meta:
              $ref: '#/components/schemas/AuthMeta'
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
      
    AuthMeta:
      type: object
      properties:
        hint:
          type: string
        expiry:
          type: string
          example: "2019-12-30T12:01:55Z"
      xml:
        name: Meta
      
    Identifier:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/IdentifierType'
        value:
          type: string
          example: "+919800083232"
      xml:
        name: Identifier
        
    IdentifierType:
      type: string
      enum: [MOBILE, MR, NDHM_HEALTH_NUMBER, HEALTH_ID]
      
    PatientGender:
      type: string
      enum: [M, F, O, U]
      
    PatientDemographic:
      type: object
      required:
        - name
        - gender
        - dateOfBirth
      description: Demographic details are only required for demographic auth at this point. Demographic details must be same as registered
      properties:
        name: 
          type: string
          example: "janki das"
        gender:
          $ref: '#/components/schemas/PatientGender'
        dateOfBirth:
          type: string
          example: "1972-02-29"
          description: date of birth in YYYY-MM-DD format. 
        identifier: 
          $ref: '#/components/schemas/AuthConfirmIdentifier'
    AuthConfirmIdentifier:
      type: object
      required:
        - type
        - value
      properties:
        type:
          $ref: '#/components/schemas/AuthConfirmIdentifierType'
        value:
          type: string
          example: "+919800083232"
      xml:
        name: AuthConfirmIdentifier
    AuthConfirmIdentifierType:
      type: string
      enum: [MOBILE]
      
    PatientAuthConfirmResponse:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        auth:
          type: object
          description: >
            depending on the purpose of auth, as specified in /auth/init, the response may include the following 
              1. LINK - only returns **accessToken**
              2. KYC - only returns **patient**
              3. KYC_AND_LINK - returns both **accessToken** and **patient**
          properties:
            accessToken :
              type: string
              description: access token for initialization of subsequent action. 
            validity:
              $ref: '#/components/schemas/AccessTokenValidity'
            patient:
              $ref: '#/components/schemas/PatientDemographicResponse'
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
            
    PatientDemographicResponse:
      type: object
      required:
        - id
        - name
        - gender
        - yearOfBirth
      properties:
        id:
          type: string
          example: <patient-id>@<consent-manager-id>
          description: PHR Identifier of patient at consent manager
        name:
          type: string
          example: "Hina Patel"
        gender:
          $ref: '#/components/schemas/PatientGender'
        yearOfBirth:
          type: integer
          example: 2000
        address:
          $ref: '#/components/schemas/PatientAddress'
        identifiers:
          type: array
          items:
            $ref: '#/components/schemas/Identifier'
          xml:
            name: identifiers
            wrapped: true

    HealthInformationNotification:
      type: object
      required:
        - requestId
        - timestamp
        - notification
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request.
          example: "499a5a4a-7dda-4f20-9b67-e24589627061"
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        notification:
          type: object
          required:
            - consentId
            - transactionId
            - doneAt
            - notifier
            - statusNotification
          properties:
            consentId:
              $ref: '#/components/schemas/UuidSchema'
            transactionId:
              $ref: '#/components/schemas/UuidSchema'
            doneAt:
              type: string
              format: date-time
            notifier:
              type: object
              required:
                - type
                - id
              properties:
                type:
                  type: string
                  enum: [HIU, HIP]
                id:
                  type: string
                  example: tmh
            statusNotification:
              type: object
              required:
                - sessionStatus
                - hipId
              properties:
                sessionStatus:
                  type: string
                  enum: [TRANSFERRED, FAILED]
                hipId:
                  type: string
                  example: max
                statusResponses:
                  type: array
                  items:
                    type: object
                    required:
                      - careContextReference
                      - hiStatus
                    properties:
                      careContextReference:
                        type: string
                      hiStatus:
                        type: string
                        enum: [DELIVERED, OK, ERRORED]
                        example: OK
                      description:
                        type: string
              
    PatientAddress:
      type: object
      properties:
        line:
          type: string
        district:
          type: string
        state:
          type: string
        pincode:
          type: string
    PatientAuthNotification:
      type: object
      required:
        - requestId
        - timestamp
        - transactionId
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        auth:
          type: object
          description: >
            depending on the purpose of auth, as specified in /auth/init, the response may include the following 
              1. LINK - only returns **accessToken**
              2. KYC - only returns **patient**
              3. KYC_AND_LINK - returns both **accessToken** and **patient**
          required:
            - transactionId
            - status
          properties:
            transactionId:
              type: string
              description: transaction id for auth session
            status:
              type: string
              enum: ["GRANTED", "DENIED"]
            accessToken :
              type: string
              description: access token for initialization of subsequent action. 
            validity:
              $ref: '#/components/schemas/AccessTokenValidity'
            patient:
              $ref: '#/components/schemas/PatientDemographicResponse'
    AccessTokenValidity: 
      type: object
      required:
        - purpose
        - requester
        - expiry
        - limit
      properties:
        purpose:
          $ref: '#/components/schemas/PatientAuthPurpose'
        requester:
          $ref: '#/components/schemas/PatientAuthRequester'
        expiry:
          $ref: '#/components/schemas/TimestampSchema'
        limit:
          type: integer
          example: "1"
          description: number of times, the token can be used
    
    PatientAuthRequester:
      type: object
      required:
        - type
        - id
      description: identification of requester
      properties:
        type: 
          type: string
          enum: [HIP, HIU]
        id:
          type: string
          example: 100005
    PatientAuthNotificationAcknowledgement:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        acknowledgement:
          type: object
          required:
            - status
          properties:
            status:
              type: string
              enum: ["OK"]
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
    CareContextDefinition:
      type: object
      required:
        - patientReference
        - careContextReference
      properties:
        patientReference:
          type: string
          example: batman@tmh
        careContextReference:
          type: string
          example: Episode1
    
    SubscriptionRequest:
      type: object
      required:
        - requestId
        - timestamp
        - subscription
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request. 
          example: "499a5a4a-7dda-4f20-9b67-e24589627061"
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        subscription:
          type: object
          required:
            - purpose
            - patient
            - hiu
            - categories
            - period
          properties:
            purpose:
              $ref: '#/components/schemas/UsePurpose'
            patient:
              $ref: '#/components/schemas/ConsentManagerPatientID'
            hiu:
              $ref: '#/components/schemas/OrganizationRepresentation'
            hips:
              type: array
              items:
                $ref: '#/components/schemas/OrganizationRepresentation'
            categories:
              type: array
              items:
                $ref: '#/components/schemas/SubscriptionCategory'
            period:
              $ref: '#/components/schemas/SubscriptionPeriod'
    HIUSubscriptionRequestReceipt:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        subscriptionRequest:
          type: object
          required:
            - id
          properties:
            id: 
              type: string
              format: uuid
              description: id of the consent-request created
              example: f29f0e59-8388-4698-9fe6-05db67aeac46
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
      xml:
        name: ConsentRequestInitResponse
    SubscriptionStatus:
      type: string
      enum: ["GRANTED", "DENIED"]
    SubscriptionCategory:
      type: string
      enum: ["LINK", "DATA"]
    SubscriptionPeriod:
      type: object
      required:
        - from
        - to
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
    HIUSubscriptionContext:
      type: object
      required:
        - categories
        - period
      properties:
        hip:
          $ref: '#/components/schemas/OrganizationRepresentation'
        categories:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionCategory'
        period:
          $ref: '#/components/schemas/SubscriptionPeriod'
    HIUSubscription:
      type: object
      required:
        - id
        - patient
        - hiu
        - sources
      properties:
        id:
          type: string
          example: "subscription Id"
        patient:
          $ref: '#/components/schemas/ConsentManagerPatientID'
        hiu:
          $ref: '#/components/schemas/OrganizationRepresentation'
        sources:
          type: array
          items:
            $ref: '#/components/schemas/HIUSubscriptionContext'
    SubscriptionApprovalNotification:
      type: object
      required:
        - requestId
        - timestamp
        - notification
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        notification:
          type: object
          required:
            - status
          properties:
            subscriptionRequestId:
              type: string
              example: 'request id of the subscription'
            status:
              $ref: '#/components/schemas/SubscriptionStatus'
            subscription:
              $ref: '#/components/schemas/HIUSubscription'
    HIUSubscriptionRequestNotificationAcknowledgement:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        acknowledgement:
          type: object
          required:
            - status
            - subscriptionRequestId
          properties:
            status:
              type: string
              enum: ["OK"]
            subscriptionRequestId:
              type: string
              example: "subscription Id"
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
    EventCategoryDetail:
      type: object
      required:
        - hiTypes
        - careContext
      properties:
        careContext:
          $ref: '#/components/schemas/CareContextDefinition'
        hiTypes:
          type: array
          items:
            $ref: '#/components/schemas/HITypeEnum'
    HIUSubscriptionEventContent:
      type: object
      required:
        - patient
        - hip
        - context
      properties:
        patient:
          $ref: '#/components/schemas/ConsentManagerPatientID'
        hip:
          $ref: '#/components/schemas/OrganizationRepresentation'
        context:
          type: array
          items:
            $ref: '#/components/schemas/EventCategoryDetail'
    HIUSubscriptionNotification:
      type: object
      required:
        - requestId
        - timestamp
        - event
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        event:
          type: object
          required:
            - id
            - published
            - subscriptionId
            - category
            - content
          properties:
            id:
              $ref: '#/components/schemas/UuidSchema'
            published:
              $ref: '#/components/schemas/TimestampSchema'
            subscriptionId:
              type: string
              example: "subscription Id"
            category: 
              $ref: '#/components/schemas/SubscriptionCategory'
            content:
              $ref: '#/components/schemas/HIUSubscriptionEventContent'
    HIUSubscriptionNotificationAcknowledgment:
      type: object
      required:
        - requestId
        - timestamp
        - resp
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        acknowledgement:
          type: object
          required:
            - status
            - eventId
          properties:
            status:
              type: string
              enum: ["OK"]
            eventId:
              type: string
              example: "subscription event Id"
        error: 
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'
    HiuPatientStatusNotification:
      type: object
      required:
        - requestId
        - timestamp
        - notification
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        notification:
          type: object
          required:
            - patient
            - status
          properties:
            status:
              type: string
              enum: [ DEACTIVATED, REACTIVATED, DELETED ]
            patient:
              type: object
              required:
                - id
              properties:
                id:
                  type: string
                  example: hina@ncg
    PatientStatusNotification:
      type: object
      required:
        - requestId
        - timestamp
        - acknowledgment
      properties:
        requestId:
          type: string
          format: uuid
          description: a nonce, unique for each HTTP request
          example: 5f7a535d-a3fd-416b-b069-c97d021fbacd
        timestamp:
          $ref: '#/components/schemas/TimestampSchema'
        acknowledgment:
          type: object
          required:
            - status
          properties:
            status:
              type: string
              enum: ["OK"]
        error:
          $ref: '#/components/schemas/Error'
        resp:
          $ref: '#/components/schemas/RequestReference'