Skip to main content

​
In short

  • One call links a visit to the patient’s ABHA address as a care context.
  • Send the FHIR bundle in data if Eka stores the record; leave it out if you keep it.
  • The call returns 202; the result arrives on abha.link_care_context.
  • LINKED means the record is shareable; on ERRORED, read data.error.

​
When to use this

A patient with an ABHA has finished a visit, test or admission at your facility. You want that record linked to their ABHA address as a care context. Once linked, the care context is registered with ABDM and any Health Information User (HIU) the patient grants consent to can request it. Before you link, decide one thing: does Eka store the clinical data, or do you? If Eka stores it, you send the FHIR bundle with the link call and Eka answers every later data request for you. If you keep it, you leave the bundle out and answer each request yourself with Serve records on a fetch request. For records created before the patient’s ABHA was known, the patient claims them from a PHR app instead. See Answer discovery and link old records.

​
Before you start

  • A client access token, sent as a Bearer token. See Authorization.
  • Your facility onboarded as a Health Information Provider (HIP), with its HIP ID. See Milestone 4.
  • A webhook URL registered with Eka that can receive abha.link_care_context, and the means to verify the webhook signature.
  • The patient’s abha_address and Eka user id oid, saved on the patient record. They come from Create an ABHA with Aadhaar OTP or Log in to an existing ABHA.
  • Your own id for the care context, its display name and its health information type (hi_type, for example OPConsultation or Prescription).
  • If Eka is to store the data: the ABDM-compliant FHIR bundle for the care context.

​
Sequence

​
Steps

1

Link the care context

Call Care context linking. Send the patient’s oid in the X-Pt-Id header, your patient id in X-Partner-Pt-Id and your HIP ID in X-Hip-Id. In the body, send abha_address, oid, partner_user_id and one entry in care_contexts per record, each with care_context_id, display and hi_type.Decide on the data now. If Eka stores the data, put the base64-encoded FHIR bundle in each entry’s data field and list its health information types in hi_types. Eka then answers data requests for you, and you never receive abha.hip_data_fetch for this care context. If you keep the data, leave data out and run Serve records on a fetch request whenever a request arrives.The call returns 202 Accepted. That means Eka has taken the request, not that the care context is linked.
2

Wait for the linking status

Eka sends the abha.link_care_context webhook with the result. Acknowledge it with HTTP 200 within 5 seconds; Eka retries on any other status.Read data.status. If it is LINKED, mark the care context as linked on your side; it is now discoverable and shareable. If it is ERRORED, read data.error for the reason. data.retry_count reports how many times linking was retried.Match the webhook to your record by data.care_context_id.
3

Notify the patient (optional)

Call Notify unlinked care contexts with the patient’s 10-digit mobile_number. It notifies the gateway that a new health record is ready to be shared with the patient. It returns 202 Accepted.

​
State you must persist

​
When it fails

Which of these codes each call returns is not yet confirmed. The codes come from the errors page, matched by meaning. Log the code you actually receive.
Error responses carry code, error and source_error. The codes below are from the errors page; match the one you receive there.

​
Test it

The testing page has the sandbox base URL, credentials and the happy path for every journey.
  • Link one OPConsultation care context with data set, and receive abha.link_care_context with status LINKED
  • Link one care context without data, receive LINKED, then confirm a later consent request arrives as abha.hip_data_fetch
  • Send an invalid abha_address and check the error response
  • Return a non-200 from your webhook once and confirm Eka retries