Skip to main content

user linking

On Discovery, HIP responds with found care contexts

Async Callback: After receiving a discovery request at the HIP bridge URL ({bridgeUrl}/v0.5/care-contexts/discover), the HIP calls this Gateway endpoint to return the list of care contexts found for the patient.

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/patient/care-context/on-discover

The HIP matches the patient using the demographics provided (name, gender, DOB, verified identifiers) and returns matching records.

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

transactionIdstringRequired

Same transactionId from the discover request received at HIP bridge

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

Discovery 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

Callbacks​

  • You make this call in reply to A discovery request for a patient you may hold records for, which ABDM posts to /api/v3/hip/patient/care-context/discover. Open the callback.
Last updated on