HIP-Initiated Linking

Link HIP care contexts to a patient's ABHA with a link token and notify the patient.

Use HIP-initiated linking when the patient shares an ABHA during registration. Link the care context when the health record is ready for share.

OCR-derived examples

The source stores several API examples as OCR text from screenshots. The examples below fix obvious OCR errors and show valid JSON. Verify each payload against the current sandbox Swagger before certification.

Flow

sequenceDiagram
  participant P as Patient
  participant HIP as HIP / HMIS
  participant CM as HIE-CM
  participant PHR as PHR apps
  P->>HIP: Shares ABHA during registration
  HIP->>HIP: Create or update health record
  HIP->>HIP: Assign record to care context
  HIP->>CM: POST /api/hiecm/v3/token/generate-token
  CM-->>HIP: POST /api/v3/hip/token/on-generate-token
  HIP->>CM: POST /api/hiecm/hip/v3/link/carecontext
  CM-->>HIP: POST /api/v3/link/on_carecontext
  CM->>PHR: Notify subscribed PHR apps
  PHR->>P: Shows linked record

Care context payload

Store only references in HIE-CM. Keep the clinical data inside the HIP system.

Field	Rule
`patient.referenceNumber`	Use the internal patient ID or MRN.
`patient.display`	Use a patient-friendly label.
`careContexts[].referenceNumber`	Use the episode or record group ID.
`careContexts[].display`	Use a clear OPD, IPD, or lab label.
`hiType`	Use one ABDM HI type for the care context.
`count`	Match the number of care contexts sent.

Care context object

{
  "patient": {
    "referenceNumber": "MRN-2026-00042",
    "display": "Sunrise Hospital records for Kiran Kumar",
    "careContexts": [
      {
        "referenceNumber": "OPD-2026-08-11-001",
        "display": "OPD consultation, General Medicine, 11 Aug 2026"
      }
    ]
  }
}

Step 1 — Assign records to care contexts

Create one care context for each OPD visit or IPD admission. Attach each record to exactly one care context. Use the same reference when you later fetch the FHIR bundle.

Display names

Write display names for patients, not for developers. Do not include diagnoses, test results, or sensitive data.

Step 2 — Generate or retrieve a link token

A link token authorizes HIP-initiated linking. Generate it during patient registration. Store it with the patient ABHA and HIP ID.

The source states that the current token validity is 6 months. Reject expired or invalid tokens. Regenerate the token with demographic authentication when you do not hold a valid token.

POST/api/hiecm/v3/token/generate-token

Generate a link token for HIP-initiated linking.

Generate a link token

curl -X POST "https://dev.abdm.gov.in/api/hiecm/v3/token/generate-token" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "REQUEST-ID: <uuid>" \
  -H "TIMESTAMP: <iso-8601-timestamp>" \
  -H "X-CM-ID: sbx" \
  -H "X-HIP-ID: <hip-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "abhaNumber": "91-1234-5678-9012",
    "abhaAddress": "kiran.kumar@sbx",
    "name": "Kiran Kumar",
    "gender": "M",
    "yearOfBirth": 1990
  }'

Synchronous response

{
  "status": "ACCEPTED"
}

HIE-CM sends the token to your bridge callback.

POST <callback_url>/api/v3/hip/token/on-generate-token

{
  "abhaAddress": "kiran.kumar@sbx",
  "linkToken": "<jwt-link-token>",
  "response": {
    "requestId": "<generate-token-request-id>"
  }
}

Step 3 — Link care contexts to ABHA

Send the link token in the X-LINK-TOKEN header. Send abhaNumber and abhaAddress when both were used to generate the token. If only one identifier was used, send that identifier.

POST/api/hiecm/hip/v3/link/carecontext

Link one or more care contexts to the patient's ABHA.

Link a care context

curl -X POST "https://dev.abdm.gov.in/api/hiecm/hip/v3/link/carecontext" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "REQUEST-ID: <uuid>" \
  -H "TIMESTAMP: <iso-8601-timestamp>" \
  -H "X-CM-ID: sbx" \
  -H "X-HIP-ID: <hip-id>" \
  -H "X-LINK-TOKEN: <link-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "abhaNumber": "91-1234-5678-9012",
    "abhaAddress": "kiran.kumar@sbx",
    "patient": [
      {
        "referenceNumber": "MRN-2026-00042",
        "display": "Sunrise Hospital records for Kiran Kumar",
        "careContexts": [
          {
            "referenceNumber": "OPD-2026-08-11-001",
            "display": "OPD consultation, General Medicine, 11 Aug 2026"
          }
        ],
        "hiType": "OPConsultation",
        "count": 1
      }
    ]
  }'

Synchronous response

{
  "status": "ACCEPTED"
}

HIE-CM then calls your bridge with the link status.

POST <callback_url>/api/v3/link/on_carecontext

{
  "abhaAddress": "kiran.kumar@sbx",
  "status": "Successfully Linked care context",
  "response": {
    "requestId": "<link-carecontext-request-id>"
  }
}

Step 4 — Notify updates to linked care contexts

Call the update notification API when a linked care context gets new records. This keeps PHR apps synchronized.

POST/api/hiecm/hip/v3/link/context/notify

Notify HIE-CM about updates in an already linked care context.

Notify a linked care context update

curl -X POST "https://dev.abdm.gov.in/api/hiecm/hip/v3/link/context/notify" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "REQUEST-ID: <uuid>" \
  -H "TIMESTAMP: <iso-8601-timestamp>" \
  -H "X-CM-ID: sbx" \
  -H "X-HIP-ID: <hip-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "notification": {
      "patient": {
        "id": "kiran.kumar@sbx",
        "referenceNumber": "MRN-2026-00042",
        "careContexts": [
          {
            "referenceNumber": "OPD-2026-08-11-001",
            "hiTypes": ["Prescription", "OPConsultation"]
          }
        ]
      }
    }
  }'

Acknowledgement callback

{
  "acknowledgement": {
    "status": "SUCCESS"
  },
  "response": {
    "requestId": "<notify-request-id>"
  }
}

Step 5 — Notify a patient by mobile

Use this flow when the patient did not share an ABHA at registration. Send only basic demographic data and the mobile number. ABDM sends an SMS with a secure deep link. The patient can open a PHR app, create an ABHA, and link records.

POST/api/hiecm/hip/v3/link/patient/links/sms/notify2

Ask ABDM to send a deep-link SMS to the patient.

Send a deep-link SMS

curl -X POST "https://dev.abdm.gov.in/api/hiecm/hip/v3/link/patient/links/sms/notify2" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "REQUEST-ID: <uuid>" \
  -H "TIMESTAMP: <iso-8601-timestamp>" \
  -H "X-CM-ID: sbx" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "<uuid>",
    "timestamp": "<iso-8601-timestamp>",
    "notification": {
      "phoneNo": "91XXXXXXXXXX",
      "hip": {
        "id": "<hip-id>",
        "name": "Sunrise Hospital"
      }
    }
  }'

Synchronous response

{
  "status": "ACCEPTED"
}

POST <callback_url>/api/v3/patients/sms/on-notify

{
  "requestId": "<sms-notify-request-id>",
  "status": "SMS_SENT",
  "response": {
    "requestId": "<original-request-id>"
  }
}

Production base URL

The source states this production base URL for these linking APIs.

https://apis.abdm.gov.in

Sources

ABDM Proposed Simplified Milestone 2 (DOCX→MD, 2026-08)

PreviousMilestone 2 — HIP Data Sharing Next M2 · Discovery & Link