user linking

Link On-Init, HIP responds with OTP communication details

Async Callback: After receiving a link init request at the HIP bridge URL ({bridgeUrl}/v0.5/links/link/init), the HIP calls this Gateway endpoint to return the authentication details (OTP communication medium and expiry).

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-init

The Gateway uses this to prompt the patient to enter the OTP for link confirmation.

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

linkobjectRequired

link.referenceNumberstringRequired

HIP-generated link reference (UUIDv4)

link.authenticationTypestringRequired

One of DIRECTMEDIATED

link.metaobjectRequired

link.meta.communicationMediumstring

One of MOBILEEMAIL

link.meta.communicationHintstring

Masked hint (e.g. mobile ending digits)

link.meta.communicationExpirystring

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 init 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-Init, HIP responds with OTP communication details

curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/user-initiated-linking/v3/link/care-context/on-init \
  --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 '{
  "transactionId": "txn-uuid-001",
  "link": {
    "referenceNumber": "link-ref-uuid-001",
    "authenticationType": "DIRECT",
    "meta": {
      "communicationMedium": "MOBILE",
      "communicationHint": "OTP",
      "communicationExpiry": "2024-01-10T12:10:00.000Z"
    }
  },
  "response": {
    "requestId": "req-uuid-from-link-init"
  }
}'

Link init response accepted by Gateway

Callbacks

You make this call in reply to A request to start linking a care context, which ABDM posts to /api/v3/hip/link/care-context/init. Open the callback.

Link On-Init, HIP responds with OTP communication details

Authorizations

Headers

Body

Responses

Callbacks​

Callbacks