> ## Documentation Index
> Fetch the complete documentation index at: https://developer.eka.care/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started

> Embed ABDM medical records consent management into your application

## Overview

The **ABDM Records** module is a plug-and-play UI widget that enables your application to request, track, and act on ABDM (Ayushman Bharat Digital Mission) health data consents on behalf of your patients. When a patient approves a consent request, the **View** button becomes available — your application is then responsible for fetching and rendering the records by calling Eka's APIs.

***

## How It Works

<Steps>
  <Step title="Embed the widget">
    Load the ABDM Records widget inside your application by rendering it in an `<iframe>` or a dedicated route, passing required URL parameters.
  </Step>

  <Step title="Request consent">
    On click of **Request Consent** inside the widget, selects the date range, expiry, purpose, and record types, then submits the form.
  </Step>

  <Step title="Patient approves">
    The patient receives a notification on their ABHA-linked app and either grants or denies the request.
  </Step>

  <Step title="Records arrive in your backend">
    When the patient grants consent, Eka's ABDM gateway delivers the medical records to your registered callback/backend endpoint.
  </Step>

  <Step title="Your app shows the records">
    The consent row updates to **Success**. When **View** is clicked, the widget opens your `consent-view` URL — a records page you build and host — passing `consent_id` as a query param. That page calls the [Consent Details API](/api-reference/user-app/abdm-connect/consents/consent-details) to get the approved care contexts, then calls the [Retrieve Health Records API](/api-reference/user-app/records/retrieve-health-records) for each care context to fetch the FHIR bundles, and renders them.
  </Step>
</Steps>

***

## Integration

### Embedding the widget

Render the widget inside an `<iframe>` (or directly in a React shell) and pass the required query parameters in the `src` URL.

Add the following HTML and script tags to your webpage:

<Note>
  For staging/dev environments, replace url with:

  * [https://abdm.dev.eka.care/abdm-records/index.html?abha=USER\_ABHA\_ID\&oid=PATIENT\_OID\&cid=CLINIC\_ID\&consent-view=https://yourapp.com/records\&token=YOUR\_GENERATED\_ACCESS\_TOKEN](https://abdm.dev.eka.care/abdm-records/index.html?abha=USER_ABHA_ID\&oid=PATIENT_OID\&cid=CLINIC_ID\&consent-view=https://yourapp.com/records\&token=YOUR_GENERATED_ACCESS_TOKEN)
</Note>

```html theme={null}
<iframe
  src="https://abdm.dev.eka.care/abdm-records/index.html?abha=USER_ABHA_ID&oid=PATIENT_OID&cid=CLINIC_ID&consent-view=https://yourapp.com/records&token=YOUR_GENERATED_ACCESS_TOKEN"
  width="100%"
  height="100%"
  frameborder="0"
/>
```

### URL parameters

| Parameter      | Required | Description                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `abha`         | Yes      | Patient's ABHA address (e.g. `user@abdm`)                                                                                                                                                                                                                                                                                                                                                        |
| `oid`          | Yes      | Patient's internal OID in your system                                                                                                                                                                                                                                                                                                                                                            |
| `cid`          | Yes      | Your clinic / HIU identifier registered with ABDM                                                                                                                                                                                                                                                                                                                                                |
| `consent-view` | Yes      | Base URL of your application's records page. When **View** is clicked, the widget appends `consent_id` and `abha` as query params and opens this URL — your page then calls the [Consent Details API](/api-reference/user-app/abdm-connect/consents/consent-details) and [Retrieve Health Records API](/api-reference/user-app/records/retrieve-health-records) to fetch and display the records |
| `token`        | Yes      | Short-lived Bearer token used to authenticate API calls to Eka's backend. Pass the raw access token value — **do not include the `Bearer ` prefix**                                                                                                                                                                                                                                              |

<Note>
  Tokens are short-lived. Generate a fresh token on each widget load from your
  backend and never expose long-lived credentials in the browser. Instead of
  route usage of iframe is preferred as it doesn't expose the token in the URL
  bar and allows better control over token refresh and security.
</Note>

***

## Requesting Consent

Click the **Request Consent** button in the top-right corner of the widget header. A modal will open with the following fields:

### Request modal fields

| Field                                | Description                                                                                     | Default                |
| ------------------------------------ | ----------------------------------------------------------------------------------------------- | ---------------------- |
| **Request To**                       | Patient's ABHA address (pre-filled, read-only)                                                  | From `abha` param      |
| **Records From**                     | Date range of records to fetch — choose a preset (Last 3 / 6 / 12 months) or set a custom range | Last 6 months to today |
| **Shared Records Will Expire In**    | How long the granted consent stays valid                                                        | 6 months               |
| **Purpose** *(Advanced)*             | Reason for requesting records                                                                   | Care management        |
| **Medical Record Type** *(Advanced)* | Types of records to include                                                                     | All types              |

#### Available record types

* OPConsultation
* Prescription
* DischargeSummary
* DiagnosticReport
* ImmunizationRecord
* HealthDocumentRecord
* WellnessRecord

#### Available purposes

* Care management
* Public Health
* Disease Specific Health Research

After filling in the details, click **Request Medical Records**. A confirmation screen appears:

> *"Your request for medical records has been sent. You can see the medical records once the patient approves your request."*

Click **Check Request Status** to return to the consent history table.

***

## Consent History Table

The widget's main screen shows a table of all consent requests for the patient. Each row represents one consent and includes:

| Column           | Description                                               |
| ---------------- | --------------------------------------------------------- |
| **Consent ID**   | Unique identifier for the consent                         |
| **Requested On** | Date the consent was requested                            |
| **Last Updated** | Date the consent status last changed                      |
| **Shared For**   | Date range of records covered by the consent              |
| **Expires In**   | Days remaining before the consent expires                 |
| **Status**       | Current state of the consent (see below)                  |
| **Action**       | **View** button — only visible when status is **Success** |

***

## Consent Statuses

Each consent request transitions through a lifecycle. The table shows a color-coded status badge for each row.

### Status reference

| Status badge   | Internal value | Meaning                                                                                                                                                                                                                                                                                                   |
| -------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 🟢 **Success** | `GRANTED`      | The patient approved the consent. The **View** action is now available — use it to fetch and display the records via the [Consent Details API](/api-reference/user-app/abdm-connect/consents/consent-details) and [Retrieve Health Records API](/api-reference/user-app/records/retrieve-health-records). |
| 🟡 **Pending** | `REQUESTED`    | The consent request has been sent to the patient and is awaiting their decision.                                                                                                                                                                                                                          |
| 🔴 **Denied**  | `DENIED`       | The patient explicitly rejected the consent request.                                                                                                                                                                                                                                                      |
| 🔴 **Revoked** | `REVOKED`      | The patient previously granted consent but has since revoked it.                                                                                                                                                                                                                                          |
| 🔴 **Expired** | `EXPIRED`      | The consent was granted but the expiry period has passed.                                                                                                                                                                                                                                                 |

<Info>
  Only **Success** consents have records associated with them. For all other
  statuses, no records will be available in your backend.
</Info>

***

## Viewing Records (Your Responsibility)

The widget manages the consent lifecycle only — it does **not** fetch or render medical record content. When a consent reaches **Success** state, a **View** button appears. Clicking it hands control over to a records page that **you build, host, and deploy**.

### What is the `consent-view` URL?

The `consent-view` parameter you pass when embedding the widget is the URL of your own hosted records page. When **View** is clicked, the widget opens that URL in a new tab and appends `consent_id` and `abha` as query parameters:

```
{consent-view}?consent_id={consentId}&abha={abhaAddress}
```

**Example:**

```
https://yourapp.com/records?consent_id=abc-123-xyz&abha=user@abdm
```

<Note>
  The widget opens this URL in a new tab. If the browser blocks the popup, it
  falls back to navigating the current tab.
</Note>

### What your records page must do

Once your page receives the `consent_id`, follow this flow:

<Steps>
  <Step title="Call the Consent Details API">
    Use the `consent_id` to call the [Consent Details API](/api-reference/user-app/abdm-connect/consents/consent-details).
    The response returns the list of approved facilities and their associated `care_context` entries.
  </Step>

  <Step title="Fetch records for each care context">
    For each `care_context` returned, call the [Retrieve Health Records API](/api-reference/user-app/records/retrieve-health-records).
    This returns a raw FHIR bundle containing the patient's health records for that care context.
  </Step>

  <Step title="Render the FHIR bundles">
    Display the FHIR data in your application's UI. See the rendering options below.
  </Step>
</Steps>

### Building your FHIR renderer

You have two options for rendering the FHIR bundles:

**Option 1 — Build your own renderer**

Parse and display the FHIR resources directly in your existing application UI. This gives you full control over the layout and presentation.

**Option 2 — Use FHIR Prism (recommended)**

[FHIR Prism](https://github.com/eka-care/fhir-prism) is an open-source FHIR rendering codebase maintained by Eka Care. It is **not a hosted service** — it is a codebase you clone, customise if needed, and deploy as your own web application. Once deployed, that URL becomes your `consent-view` value.

To get started with FHIR Prism:

1. Clone [github.com/eka-care/fhir-prism](https://github.com/eka-care/fhir-prism)
2. Customise the rendering as needed for your application
3. Deploy it to your own infrastructure
4. Pass the deployed URL as the `consent-view` parameter when embedding the widget

<Warning>
  The `consent-view` URL must be a page you own and host — the widget simply redirects to it.
  Fetching records via the [Consent Details API](/api-reference/user-app/abdm-connect/consents/consent-details)
  and [Retrieve Health Records API](/api-reference/user-app/records/retrieve-health-records), and rendering the
  FHIR data, is entirely your responsibility.
</Warning>

***

## API Reference

The widget communicates with Eka's backend using the following endpoints. All requests include your `token` as a Bearer token in the `Authorization` header.

| Method | Endpoint                    | Purpose                                 |
| ------ | --------------------------- | --------------------------------------- |
| `POST` | `/abdm/v1/consents/list`    | Fetch the consent history for a patient |
| `POST` | `/abdm/v1/consents/create`  | Submit a new consent request            |
| `POST` | `/abdm/v1/consents/details` | Fetch details of a specific consent     |

**Base URLs:**

| Environment | Base URL                   |
| ----------- | -------------------------- |
| Production  | `https://api.eka.care`     |
| Development | `https://api.dev.eka.care` |

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What happens after the patient approves consent?">
    The consent status updates to **Success** and the **View** button becomes active. Clicking **View** opens your hosted records page (`consent-view` URL) with the `consent_id`. Your page then calls the [Consent Details API](/api-reference/user-app/abdm-connect/consents/consent-details) to get the approved care contexts, and the [Retrieve Health Records API](/api-reference/user-app/records/retrieve-health-records) for each care context to fetch the FHIR bundles. You render those bundles using your own UI or the open-source [FHIR Prism](https://github.com/eka-care/fhir-prism) codebase deployed at your `consent-view` URL.
  </Accordion>

  <Accordion title="Can the patient revoke consent after approval?">
    Yes. If the patient revokes consent via their ABHA app, the consent status in
    the table will change to **Revoked**. Records already delivered to your
    backend are yours to retain per your data policy.
  </Accordion>

  <Accordion title="Why is the View button not appearing?">
    The **View** action only appears for consents with **Success** (GRANTED)
    status. Ensure the patient has approved the request and the table has
    refreshed.
  </Accordion>

  <Accordion title="How do I refresh the consent table?">
    The widget fetches the latest consent list each time it loads. Reload the widget or the page containing the `<iframe>` to see updated statuses.
  </Accordion>

  <Accordion title="What record types are supported?">
    OPConsultation, Prescription, DischargeSummary, DiagnosticReport, ImmunizationRecord, HealthDocumentRecord, and WellnessRecord. You can select one or more when requesting consent.
  </Accordion>
</AccordionGroup>