user linking

Link On-Confirm, HIP confirms linked care contexts

Async Callback: After receiving a link confirm request at the HIP bridge URL ({bridgeUrl}/v0.5/links/link/confirm) with the patient's OTP, the HIP validates the OTP and calls this Gateway endpoint to confirm the linked care contexts.

Mandatory

Certification cases USER_INIT_LINK_602, USER_INIT_LINK_603, USER_INIT_LINK_604, USER_INIT_LINK_605, USER_INIT_LINK_606, USER_INIT_LINK_607

POST/hiecm/user-initiated-linking/v3/link/care-context/on-confirm

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, so this is how you match an asynchronous reply to the call that caused it. Store it before you send the request, not after.

TIMESTAMPstringRequired

The current time in ISO 8601, UTC, with milliseconds and a Z suffix, from a synchronised clock. The sandbox rejects IST and accepts UTC.

X-CM-IDstringRequired

Which consent manager you are talking to. sbx on the sandbox and abdm in production. A dedicated error code exists for an invalid value here, which tells you how often it is wrong.

Body

patientobject[]Required

patient.referenceNumberstringRequired

HIP's internal patient reference number

patient.displaystringRequired

Patient display name

patient.careContextsobject[]Required

patient.hiTypeobject[]Required

patient.countintegerRequired

Total number of care contexts in this entry

responseobjectRequired

Echo of the requestId from the original Gateway-to-HIP request

response.requestIdstringRequired

requestId received in the original Gateway request to HIP bridge

Responses

202

Link confirm response accepted by Gateway

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

403

Forbidden. Returned as plain text ("Access Denied"), not JSON.

Error codes for this module

500

Internal server error.

Error codes for this module

Link On-Confirm, HIP confirms linked care contexts

curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/user-initiated-linking/v3/link/care-context/on-confirm \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 5f7a4a1e-59ba-4c0c-9e0c-8e6b3b6e2f11' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: <X_CM_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "patient": [
    {
      "referenceNumber": "PAT-REF-001",
      "display": "Ramesh Kumar",
      "careContexts": [
        {
          "referenceNumber": "VISIT-2024-001",
          "display": "OPD Visit 10-Jan-2024"
        }
      ],
      "hiType": [
        "Prescription"
      ],
      "count": 1
    }
  ],
  "response": {
    "requestId": "req-uuid-from-link-confirm"
  }
}'

Link confirm response accepted by Gateway

Callbacks

You make this call in reply to Confirmation of a link, carrying the token the patient approved, which ABDM posts to /api/v3/hip/link/care-context/confirm. Open the callback.

Link On-Confirm, HIP confirms linked care contexts

Authorizations

Headers

Body

Responses

Callbacks​

Callbacks