Initiate the consent request

Create a consent request by a Health Information User (HIU) to access a patient’s health data.

POST/api/hiecm/consent/v3/request/init

By invoking this API, the HIU initiates the process of obtaining the necessary permissions from the patient to retrieve their health information. This consent request is a critical component of the health information exchange framework, ensuring that patient data is accessed in a secure, authorised, and transparent manner. The API supports the establishment of trust and compliance with privacy regulations, facilitating seamless and ethical health information exchange.

Authorizations

Authorizationbearer tokenRequired

The access token from POST /api/hiecm/gateway/v3/sessions, sent with a Bearer prefix.

Headers

REQUEST-IDstringRequired

Unique UUID for track the end to end request transaction

TIMESTAMPstringRequired

Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds

X-CM-IDstringRequired

Suffix of the consent manager to which the request was intended

Body

consentobjectRequired

consent.purposeobjectRequired

consent.purpose.textstringRequired

One of Care ManagementBreak the GlassPublic HealthHealthcare PaymentDisease Specific Healthcare ResearchSelf Requested

consent.purpose.codestringRequired

One of CAREMGTBTGPUBHLTHHPAYMTDSRCHPATRQT

consent.purpose.refUristringRequired

The reference URL. Should be a valid URL. Allow alpha numeric characters and special charactes like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"

consent.patientobjectRequired

consent.patient.idstringRequired

The abha address of the patient. It must start with Alphanumeric . and _ in the middle and must be ending with @abdm or @sbx. Allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.\-!]+[a-zA-Z0-9]@(abdm|sbx)$

consent.hipobject

Identifier and name of the health information provider.

consent.hip.idstringRequired

The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$

consent.hip.namestring

The name of the health information provider. Allows alpha numeric and special characters like "^[a-zA-Z]+[A-Za-z0-9_\\-@,().\\s\\xa0:/]+"

consent.hip.typestring

The type of the health information provider. Allows alpha numeric and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"

consent.hiuobjectRequired

consent.hiu.idstringRequired

The service ID of the health information user. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$

consent.hiu.namestring

The name of the health information user. Allows alpha numeric and special characters like "^[a-zA-Z]+[A-Za-z0-9_\\-@,().\\s\\xa0:/]+"

consent.hiu.typestring

The type of the health information user. Allows alpha numeric and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"

consent.careContextsobject[]

List of care contexts linked at the HIP end for the identified patient.

consent.careContexts.patientReferencestringRequired

A patient identifier with which patient is registered in the facility/hospital like abhaAddress @sbx. Allows alpha numeric and special characters like "^[a-zA-Z0-9_\\-@,().\"/: ]{0,255}$"

consent.careContexts.careContextReferencestringRequired

An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data). Allows alpha numeric and special characters like "^[a-zA-Z0-9_\\-@,().\"/:| ]{0,255}$"

consent.requesterobjectRequired

consent.requester.namestringRequired

The name of the requester

consent.requester.identifierobjectRequired

consent.requester.identifier.valuestringRequired

The type of the identification. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"

consent.requester.identifier.typestringRequired

The identification value. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"

consent.requester.identifier.systemstringRequired

Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"

consent.hiTypesstring[]Required

Types of health information document.

consent.permissionobjectRequired

consent.permission.accessModestringRequired

One of VIEWSTORESTREAMQUERY

consent.permission.dateRangeobjectRequired

consent.permission.dateRange.fromstringRequired

Should be UTC date time in ISO format. Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"

consent.permission.dateRange.tostringRequired

Should be UTC date time in ISO format. Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"

consent.permission.dataEraseAtstringRequired

The date at which the consent expire. Should be UTC. Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$" date time in ISO format

consent.permission.frequencyobjectRequired

consent.permission.frequency.unitstringRequired

One of HOURDAYWEEKMONTHYEAR

consent.permission.frequency.valuenumberRequired

The frequency unit value. Should be be a integer

consent.permission.frequency.repeatsnumberRequired

Should be be a integer

Responses

202

Accepted

The callback never arrives

400

Bad Request

Error codes for this module

401

Unauthorized

Everything returns 401

codestring

900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.

messagestring

descriptionstring

403

Forbidden

Error codes for this module

404

Not Found

Error codes for this module

errorobject

The error code and message, if any occurred.

error.codestringRequired

ABDM-1001 - No data found. May be returned either bare (ABDM-1001) or with a trailing ": " separator (ABDM-1001: ); match on the code itself and tolerate the separator.

error.messagestringRequired

500

Internal Server Error

Error codes for this module

codestring

900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.

messagestring

descriptionstring

503

Service Unavailable

Error codes for this module

codestringRequired

ABDM-1024 - Dependent service unavailable. May be returned either bare (ABDM-1024) or with a trailing ": " separator (ABDM-1024: ); match on the code itself and tolerate the separator.

messagestringRequired

curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/request/init \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "consent": {
    "purpose": {
      "text": "Care Management",
      "code": "CAREMGT",
      "refUri": "www.abc.com"
    },
    "patient": {
      "id": "<ABHA_ADDRESS>"
    },
    "hip": null,
    "hiu": {
      "id": "cowin_hiu_01"
    },
    "careContexts": [
      {
        "patientReference": "batman@tmh",
        "careContextReference": "Episode1"
      }
    ],
    "requester": {
      "name": "<ABHA_ADDRESS>",
      "identifier": {
        "value": "REG1",
        "type": "MH1001",
        "system": "https://www.sample.com"
      }
    },
    "hiTypes": [
      "Prescription"
    ],
    "permission": {
      "accessMode": "VIEW",
      "dateRange": {
        "from": "2021-09-28T12:30:08.573Z",
        "to": "2021-09-28T12:30:08.573Z"
      },
      "dataEraseAt": "2021-09-28T12:30:08.573Z",
      "frequency": {
        "unit": "HOUR",
        "value": 1,
        "repeats": 0
      }
    }
  }
}'

Accepted

Callbacks

After this call, ABDM posts Callback API of consent request for patient HIU. to /api/v3/hiu/consent/request/on-init. Open the callback.

Initiate the consent request

Authorizations

Headers

Body

Responses

Callbacks​

Callbacks