Discovery & Link

Implement user-initiated discovery and link care contexts from a PHR app.

Use Discovery & Link when the patient starts record linking from a PHR app. The patient selects a facility, then HIE-CM routes the request to the HIP.

OCR-derived examples

The source stores 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 PHR as PHR app
  participant CM as HIE-CM
  participant HIP as HIP / HMIS
  P->>PHR: Select facility and start discovery
  PHR->>CM: Send discovery request
  CM->>HIP: POST /api/v3/hip/patient/care-context/discover
  HIP->>HIP: Match patient records
  HIP->>CM: POST /api/hiecm/user-initiated-linking/v3/patient/care-context/on-discover
  CM->>PHR: Show unlinked care contexts
  P->>PHR: Select care contexts
  PHR->>CM: Start link init
  CM->>HIP: POST /api/v3/hip/link/care-context/init
  HIP->>P: Send OTP
  HIP->>CM: POST /api/hiecm/user-initiated-linking/v3/link/care-context/on-init
  P->>PHR: Enter OTP
  CM->>HIP: POST /api/v3/hip/link/care-context/confirm
  HIP->>CM: POST /api/hiecm/user-initiated-linking/v3/link/care-context/on-confirm
  CM->>PHR: Show link result

Mandatory APIs

Implement these bridge callbacks and HIE-CM response APIs.

Stage	Direction	Endpoint	Purpose
Discover	HIE-CM to HIP	`<callback_url>/api/v3/hip/patient/care-context/discover`	Ask HIP to find matching records.
On discover	HIP to HIE-CM	`/api/hiecm/user-initiated-linking/v3/patient/care-context/on-discover`	Return unlinked care contexts.
Link init	HIE-CM to HIP	`<callback_url>/api/v3/hip/link/care-context/init`	Ask HIP to start authentication.
On init	HIP to HIE-CM	`/api/hiecm/user-initiated-linking/v3/link/care-context/on-init`	Return link reference and OTP details.
Link confirm	HIE-CM to HIP	`<callback_url>/api/v3/hip/link/care-context/confirm`	Ask HIP to validate the OTP.
On confirm	HIP to HIE-CM	`/api/hiecm/user-initiated-linking/v3/link/care-context/on-confirm`	Return linked records or an error.

Step 1 — Receive a discovery request

HIE-CM sends verified and unverified identifiers to the HIP. Return 202 Accepted after you persist the request. Then process the match asynchronously.

POST <callback_url>/api/v3/hip/patient/care-context/discover

{
  "transactionId": "<transaction-id>",
  "patient": {
    "id": "kiran.kumar@sbx",
    "name": "Kiran Kumar",
    "gender": "M",
    "yearOfBirth": 1990,
    "verifiedIdentifiers": [
      {
        "type": "MOBILE",
        "value": "91XXXXXXXXXX"
      },
      {
        "type": "ABHA_ADDRESS",
        "value": "kiran.kumar@sbx"
      }
    ],
    "unverifiedIdentifiers": [
      {
        "type": "MR",
        "value": "MRN-2026-00042"
      }
    ]
  }
}

Immediate response

{
  "status": "ACCEPTED"
}

Step 2 — Match patient records

Implement a safe matching algorithm. Prefer verified identifiers over user-declared identifiers. Return no records when the match is weak.

Input	Match rule
ABHA address	Use exact match when the HIP stores it.
Mobile number	Use exact match when it is verified in your system.
Name	Use a strict normalized match or a high-confidence fuzzy match.
Gender	Use it as a supporting field.
Year of birth	Use it as a supporting field.
Patient ID or MRN	Use exact match when the user provides it.

Do not leak records

Never return a care context for a low-confidence match. Return an empty result instead of a wrong match.

Step 3 — Return discovered care contexts

Return only unlinked records for that patient. Do not include diagnoses, reports, test results, or clinical data.

Return discovered care contexts

curl -X POST "https://dev.abdm.gov.in/api/hiecm/user-initiated-linking/v3/patient/care-context/on-discover" \
  -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 '{
    "transactionId": "<transaction-id>",
    "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
      }
    ],
    "response": {
      "requestId": "<discover-request-id>"
    }
  }'

Synchronous response

{
  "status": "ACCEPTED"
}

Step 4 — Start link authentication

HIE-CM sends the selected care contexts to the HIP. Your HIP must generate a link reference number. Then send an OTP to the patient's mobile number in your system.

POST <callback_url>/api/v3/hip/link/care-context/init

{
  "transactionId": "<transaction-id>",
  "patient": {
    "id": "kiran.kumar@sbx",
    "referenceNumber": "MRN-2026-00042",
    "careContexts": [
      {
        "referenceNumber": "OPD-2026-08-11-001",
        "display": "OPD consultation, General Medicine, 11 Aug 2026"
      }
    ]
  }
}

Return link-init details

curl -X POST "https://dev.abdm.gov.in/api/hiecm/user-initiated-linking/v3/link/care-context/on-init" \
  -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 '{
    "transactionId": "<transaction-id>",
    "link": {
      "referenceNumber": "LINK-REF-20260811-0001",
      "authenticationType": "DIRECT",
      "meta": {
        "communicationMedium": "MOBILE",
        "communicationHint": "OTP",
        "communicationExpiry": "2026-08-11T14:36:33.000Z"
      }
    },
    "response": {
      "requestId": "<link-init-request-id>"
    }
  }'

Synchronous response

{
  "status": "ACCEPTED"
}

Step 5 — Confirm the link

HIE-CM forwards the OTP to your HIP. Validate the OTP against the link reference number. Then return the linked care contexts.

POST <callback_url>/api/v3/hip/link/care-context/confirm

{
  "transactionId": "<transaction-id>",
  "confirmation": {
    "linkRefNumber": "LINK-REF-20260811-0001",
    "token": "123456"
  }
}

Return link-confirm result

curl -X POST "https://dev.abdm.gov.in/api/hiecm/user-initiated-linking/v3/link/care-context/on-confirm" \
  -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 '{
    "transactionId": "<transaction-id>",
    "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
      }
    ],
    "response": {
      "requestId": "<confirm-request-id>"
    }
  }'

Synchronous response

{
  "status": "ACCEPTED"
}

Error response shape

Use an error object when discovery, init, or confirm fails. Always include the response object with the original request ID.

On-confirm error example

{
  "transactionId": "<transaction-id>",
  "error": {
    "code": "ABDM-1056",
    "message": "Invalid Link Reference Number"
  },
  "response": {
    "requestId": "<confirm-request-id>"
  }
}

Production base URL

The source states this production base URL for the HIE-CM APIs.

https://apis.abdm.gov.in

Sources

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

PreviousM2 · HIP-Initiated Linking Next M2 · Data Transfer