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

**1. 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.

**2. Request consent**

On click of **Request Consent** inside the widget, selects the date range, expiry, purpose, and record types, then submits the form.

**3. Patient approves**

The patient receives a notification on their ABHA-linked app and either grants or denies the request.

**4. Records arrive in your backend**

When the patient grants consent, Eka's ABDM gateway delivers the medical records to your registered callback/backend endpoint.

**5. 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](https://developer.eka.care/api-sdk/hie-cm/consents/consent-details.md) to get the approved care contexts, then calls the [Retrieve Health Records API](https://developer.eka.care/api-sdk/health-records/retrieve-health-records.md) for each care context to fetch the FHIR bundles, and renders them.

***

## 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)

```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](https://developer.eka.care/api-sdk/hie-cm/consents/consent-details.md) and [Retrieve Health Records API](https://developer.eka.care/api-sdk/health-records/retrieve-health-records.md) 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.

***

## 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](https://developer.eka.care/api-sdk/hie-cm/consents/consent-details.md) and [Retrieve Health Records API](https://developer.eka.care/api-sdk/health-records/retrieve-health-records.md). |
|  **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. |

> [!NOTE]
>
> Only **Success** consents have records associated with them. For all other
> statuses, no records will be available in your backend.

***

## 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.

### What your records page must do

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

**1. Call the Consent Details API**

Use the `consent_id` to call the [Consent Details API](https://developer.eka.care/api-sdk/hie-cm/consents/consent-details.md).
The response returns the list of approved facilities and their associated `care_context` entries.

**2. Fetch records for each care context**

For each `care_context` returned, call the [Retrieve Health Records API](https://developer.eka.care/api-sdk/health-records/retrieve-health-records.md).
This returns a raw FHIR bundle containing the patient's health records for that care context.

**3. Render the FHIR bundles**

Display the FHIR data in your application's UI. See the rendering options below.

### 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](https://developer.eka.care/api-sdk/hie-cm/consents/consent-details.md)
> and [Retrieve Health Records API](https://developer.eka.care/api-sdk/health-records/retrieve-health-records.md), and rendering the
> FHIR data, is entirely your responsibility.

***

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

> **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](https://developer.eka.care/api-sdk/hie-cm/consents/consent-details.md) to get the approved care contexts, and the [Retrieve Health Records API](https://developer.eka.care/api-sdk/health-records/retrieve-health-records.md) 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.

> **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.

> **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.

> **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.

> **What record types are supported?**
>
> OPConsultation, Prescription, DischargeSummary, DiagnosticReport, ImmunizationRecord, HealthDocumentRecord, and WellnessRecord. You can select one or more when requesting consent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.