Records & Consents

A PHR app lets the patient discover, link, fetch, view, and upload health records. It also lets the patient manage consent requests from HIUs.

Use this page for the PHR-side flow. Use Milestone 2 for the HIP-side discovery and data transfer logic.

User-initiated discovery

Use user-initiated discovery when the patient did not share an ABHA address at the facility. The patient searches a facility or a health programme. The PHR app sends the patient identifiers to HIE-CM. HIE-CM forwards the request to the HIP.

sequenceDiagram
  participant Patient
  participant App as PHR app
  participant CM as HIE-CM
  participant HIP
  Patient->>App: Search facility or programme
  App->>CM: POST patient/care-context/discover
  CM->>HIP: POST callback /patient/care-context/discover
  HIP-->>CM: POST on-discover
  CM-->>App: POST callback /patient/care-context/on-discover
  Patient->>App: Select care context entries
  App->>CM: POST link/care-context/init
  CM->>HIP: POST callback /link/care-context/init
  HIP-->>Patient: Send OTP
  Patient->>App: Enter OTP
  App->>CM: POST link/care-context/confirm
  CM->>HIP: POST callback /link/care-context/confirm
  HIP-->>CM: POST on-confirm
  CM-->>App: Link success

curl -X POST "https://dev.abdm.gov.in/api/hiecm/user-initiated-linking/v3/patient/care-context/discover" \
  -H "Content-Type: application/json" \
  -H "REQUEST-ID: $(uuidgen | tr 'A-Z' 'a-z')" \
  -H "TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%S.000Z)" \
  -H "X-CM-ID: sbx" \
  -H "Authorization: Bearer <hiecm-access-token>" \
  -d '{
    "hip": {
      "id": "HIP_1"
    },
    "unverifiedIdentifiers": [
      {
        "type": "ABHA_ADDRESS",
        "value": "john.doe@sbx"
      },
      {
        "type": "MOBILE",
        "value": "9876543210"
      },
      {
        "type": "MR",
        "value": "123456"
      }
    ]
  }'

{
  "status": "ACCEPTED"
}

curl -X POST "https://dev.abdm.gov.in/api/hiecm/user-initiated-linking/v3/link/care-context/init" \
  -H "Content-Type: application/json" \
  -H "REQUEST-ID: $(uuidgen | tr 'A-Z' 'a-z')" \
  -H "TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%S.000Z)" \
  -H "X-CM-ID: sbx" \
  -H "Authorization: Bearer <hiecm-access-token>" \
  -d '{
    "transactionId": "2ec11b33-9a2d-4c8a-96a0-4b0d1fd5f511",
    "patient": [
      {
        "referenceNumber": "P12345",
        "display": "John Doe",
        "careContexts": [
          {
            "referenceNumber": "VISIT-2026-001",
            "display": "OP visit on 11 Aug 2026"
          }
        ],
        "hiType": "OPConsultation",
        "count": 1
      }
    ]
  }'

{
  "linkRefNumber": "link-ref-123",
  "status": "INITIATED"
}

curl -X POST "https://dev.abdm.gov.in/api/hiecm/user-initiated-linking/v3/link/care-context/confirm" \
  -H "Content-Type: application/json" \
  -H "REQUEST-ID: $(uuidgen | tr 'A-Z' 'a-z')" \
  -H "TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%S.000Z)" \
  -H "X-CM-ID: sbx" \
  -H "Authorization: Bearer <hiecm-access-token>" \
  -d '{
    "token": 123456,
    "linkRefNumber": "link-ref-123"
  }'

{
  "status": "ACCEPTED"
}

Discovery error states

After a successful link, show the provider in the Linked Facility tab. Send the data transfer request within 5 minutes after the patient taps Pull Records. Expect fetched records to appear within 2 hours.

Deep links

A facility can notify ABDM when it creates a record for a patient without an ABHA address. ABDM sends an SMS with a deep link such as phr.abdm.gov.in/uhi/<hipcode>. The deep link page lists approved PHR apps.

The PHR app must receive the HIPCODE parameter. It must bypass the normal home flow and start discovery automatically.

New user flow

Existing user flow

Sandbox exit details

Submit these details for deep link support:

Consent management

The PHR app is the patient interface for consent. It must support view, modify, grant, deny, active consent view, and revoke.

flowchart TD
  A[Consent request received] --> B[Show request to patient]
  B --> C{Patient action}
  C -->|Modify| D[Update parameters]
  D --> C
  C -->|Grant| E[Approve request]
  C -->|Deny| F[Deny request]
  E --> G[Show in active consents]
  G --> H[Revoke when patient asks]
  H --> I[Update HIE-CM status]

View consent requests

Show the requester, purpose, HI types, date range, consent validity, and status.

curl -X GET "https://dev.abdm.gov.in/api/hiecm/consent/v3/request" \
  -H "REQUEST-ID: $(uuidgen | tr 'A-Z' 'a-z')" \
  -H "TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%S.000Z)" \
  -H "X-CM-ID: sbx" \
  -H "Authorization: Bearer <hiecm-access-token>"

{
  "requests": [
    {
      "requestId": "consent-req-123",
      "status": "REQUESTED",
      "purpose": "Care Management",
      "hiTypes": ["DiagnosticReport", "Prescription"]
    }
  ]
}

Modify before grant

Allow changes only where the request permits them. Let the patient adjust the date range, HI types, frequency, expiry, and access mode.

Grant consent

curl -X POST "https://dev.abdm.gov.in/api/hiecm/consent/v3/request/<request-id>/approve" \
  -H "Content-Type: application/json" \
  -H "REQUEST-ID: $(uuidgen | tr 'A-Z' 'a-z')" \
  -H "TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%S.000Z)" \
  -H "X-CM-ID: sbx" \
  -H "Authorization: Bearer <hiecm-access-token>" \
  -d '{
    "consents": [
      {
        "hiTypes": ["DiagnosticReport", "Prescription"],
        "hip": {
          "id": "HIP_1",
          "name": "Example Hospital",
          "type": "HIP"
        },
        "careContexts": [
          {
            "patientReference": "P12345",
            "careContextReference": "VISIT-2026-001"
          }
        ],
        "permission": {
          "dateRange": {
            "from": "2026-01-01T00:00:00.000Z",
            "to": "2026-08-11T00:00:00.000Z"
          },
          "frequency": {
            "unit": "HOUR",
            "value": 1,
            "repeats": 0
          },
          "accessMode": "VIEW",
          "dataEraseAt": "2026-09-11T00:00:00.000Z"
        }
      }
    ]
  }'

{
  "status": "ACCEPTED"
}

Deny consent

curl -X POST "https://dev.abdm.gov.in/api/hiecm/consent/v3/request/<request-id>/deny" \
  -H "Content-Type: application/json" \
  -H "REQUEST-ID: $(uuidgen | tr 'A-Z' 'a-z')" \
  -H "TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%S.000Z)" \
  -H "X-CM-ID: sbx" \
  -H "Authorization: Bearer <hiecm-access-token>" \
  -d '{
    "reason": "Patient denied the consent request"
  }'

{
  "status": "ACCEPTED"
}

View active consents

Show granted, expired, and revoked consents in the Approved section. Show which HIU can access which records.

Revoke consent

Warn the patient before revocation. Tell the patient that ABDM access will stop.

curl -X POST "https://dev.abdm.gov.in/api/hiecm/consent/v3/revoke" \
  -H "Content-Type: application/json" \
  -H "REQUEST-ID: $(uuidgen | tr 'A-Z' 'a-z')" \
  -H "TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%S.000Z)" \
  -H "X-CM-ID: sbx" \
  -H "Authorization: Bearer <hiecm-access-token>" \
  -d '{
    "consents": ["consent-artefact-123"]
  }'

{
  "status": "ACCEPTED"
}

Fetch and display records

A PHR app also acts as an HIU. After a care context link, create a consent request. Use auto-approve if the patient configured it. Then fetch records with the approved consent artefact.

See Milestone 3 for the HIU data request flow.

Upload records to a locker

The PHR app must let the patient scan or upload records. Examples include paper records, BP meter output, glucose meter output, and smartwatch records.

Use the selected or detected HI type. Use HealthDocumentRecord when the app cannot identify the HI type.

The PHR app must get a linking token for the ABHA address. Then it must add the uploaded item as a care context through HIP initiated linking. See Milestone 1 for linking tokens. Use Milestone 2 to share uploaded records through ABDM.

curl -X POST "https://dev.abdm.gov.in/api/hiecm/subscription-requests/v3/setup-locker" \
  -H "Content-Type: application/json" \
  -H "REQUEST-ID: $(uuidgen | tr 'A-Z' 'a-z')" \
  -H "TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%S.000Z)" \
  -H "X-CM-ID: sbx" \
  -H "Authorization: Bearer <hiecm-access-token>" \
  -d '{
    "patient": {
      "id": "john.doe@sbx"
    },
    "locker": {
      "id": "PHR_LOCKER_ID",
      "name": "Example PHR Locker"
    }
  }'

{
  "lockerId": "PHR_LOCKER_ID",
  "status": "ACTIVE"
}

Upload UX checks