consent

Initiate a consent request

Also known as: Consent Init Request. Initiates a new consent request for a patient's health records.

MandatoryAny one of them is mandatory

Certification cases HIU_FLOW_101, HIU_FLOW_102, HIU_FLOW_103, HIU_FLOW_104, HIU_FLOW_105, HIU_FLOW_106, HIU_FLOW_107, HIU_FLOW_108, HIU_FLOW_109, HIU_FLOW_110, HIU_FLOW_111, HIU_FLOW_112, HIU_FLOW_113

POST/hiecm/consent/v3/request/init

The Gateway notifies the patient via the ABHA App. The patient can approve or deny. The HIU receives the patient's decision via a callback to {hiuBridgeUrl}/v0.5/consents/hiu/notify.

Key fields: - purpose.code, ABDM-defined purpose codes (e.g. CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQST) - hiTypes, Health Information types requested - permission.accessMode, VIEW (read-only) or STORE - permission.dataEraseAt, Consent expiry after which data access is revoked

Authorizations

Authorizationbearer tokenRequired

Bearer token obtained from POST /hiecm/gateway/v3/sessions

Headers

REQUEST-IDstringRequired

A fresh UUID that you generate for this request. The callback that answers it carries the same value. In M3 a single consent can produce several callbacks, so keep the mapping from request id to consent request id rather than relying on ordering.

TIMESTAMPstringRequired

The current time in ISO 8601 UTC, with milliseconds and the Z suffix. The gateway rejects a request whose timestamp has drifted too far from its own clock, so take this from a synchronised clock rather than from a local one.

X-CM-IDstringRequired

Which consent manager you are talking to. sbx on the sandbox and abdm in production.

Body

consentobjectRequired

consent.purposeobjectRequired

consent.purpose.textstringRequired

consent.purpose.codestringRequired

ABDM consent purpose codes: - CAREMGT: Care Management - BTG: Break the Glass (emergency) - PUBHLTH: Public Health - HPAYMT: Health Payment - DSRCH: Disease Specific Healthcare Research - PATRQST: Patient Requested

One of CAREMGTBTGPUBHLTHHPAYMTDSRCHPATRQST

consent.purpose.refUristring

consent.patientobjectRequired

consent.patient.idstringRequired

Patient's ABHA address

consent.hiuobjectRequired

consent.hiu.idstringRequired

HIU service ID

consent.hiu.namestringRequired

HIU display name.

consent.hiu.typestring

Not otherwise constrained.

consent.hipobjectnull

Specific HIP to request from (null = any HIP)

consent.hip.idstringRequired

consent.hip.namestringRequired

HIP display name.

consent.hip.typestring

Not otherwise constrained.

consent.careContextsarraynull

Specific care contexts (null = all matching contexts)

consent.requesterobjectRequired

consent.requester.namestringRequired

Doctor / requester name

consent.requester.identifierobjectRequired

consent.requester.identifier.typestring

One of REGNONMCMCIAYUSH

consent.requester.identifier.valuestring

consent.requester.identifier.systemstring

consent.hiTypesobject[]Required

Health Information types being requested

consent.permissionobjectRequired

Responses

202

Consent request initiated successfully

The callback never arrives

400

Bad request, invalid parameters or missing fields

Error codes for this module

401

Unauthorized, missing or invalid Bearer token

Everything returns 401

Initiate a consent request

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: 5f7a4a1e-59ba-4c0c-9e0c-8e6b3b6e2f11' \
  --header 'TIMESTAMP: 2026-08-25T15:51:15.339Z' \
  --header 'X-CM-ID: <X_CM_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "consent": {
    "purpose": {
      "text": "Care Management",
      "code": "CAREMGT",
      "refUri": "http://terminology.hl7.org/CodeSystem/v3-ActReason"
    },
    "patient": {
      "id": "patient@sbx"
    },
    "hiu": {
      "id": "HIU_SERVICE_ID",
      "name": "City Health HIU"
    },
    "hip": null,
    "careContexts": null,
    "requester": {
      "name": "Dr. Sharma",
      "identifier": {
        "type": "REGNO",
        "value": "MCI-12345",
        "system": "https://www.mciindia.org"
      }
    },
    "hiTypes": [
      "Prescription",
      "DiagnosticReport"
    ],
    "permission": {
      "accessMode": "VIEW",
      "dateRange": {
        "from": "2023-01-01T00:00:00.000Z",
        "to": "2024-01-01T00:00:00.000Z"
      },
      "dataEraseAt": "2025-01-01T00:00:00.000Z",
      "frequency": {
        "unit": "HOUR",
        "value": 1,
        "repeats": 0
      }
    }
  }
}'

{
  "consentRequestId": "<CONSENT_REQUEST_ID>"
}

Generated from the schema. The values are placeholders, not a captured response.

Callbacks

After this call, ABDM posts The consent request was accepted, with its request id to /api/v3/hiu/consent/request/on-init. Open the callback.

Initiate a consent request

Authorizations

Headers

Body

Responses

Callbacks​

Callbacks