# Connect Login
Source: https://developer.eka.care/api-sdk/auth/client-login

post /connect-auth/v1/account/login
Authorization APIs to get access and refresh token



# Delete Account
Source: https://developer.eka.care/api-sdk/auth/delete-account

delete /privacy/v1/user
Delete User Privacy Data

description: This api is used to delete the registered user account and the associated data.


# Getting started
Source: https://developer.eka.care/api-sdk/auth/getting-started



## Overview

The Eka API Authentication process ensures secure access to sensitive healthcare data through a robust authentication process. To interact with the APIs, third-party developers must obtain an access token, use it in all API requests, and handle token expiration efficiently. This guide outlines the essential steps to securely integrate with Eka's API.

### Key Components

* **Client Application:** A third-party application that communicates with Eka's API.
* **Eka API Gateway:** The server-side component that authenticates and processes API requests.

## Setting Up Your Eka Account

This is a **one-time setup** required before you can start using Eka services.

> [!NOTE]
>
> [Click here to visit Eka signup page to get started](https://login.eka.care/workspace/sign-in/?next=https://console.eka.care\&product_type=emr\&signup=user_only\&tab=sign-up).

> [!NOTE]
>
> Eka supports multiple sign-up options such as Google, Apple, Email Address, and Username.
> In this guide, we’ll use **Email Address** to walk through the setup steps.

**1. Choose Sign Up method of your choice**

On the welcome screen, select your preferred sign-up option.
For this guide, we will choose **Continue with Email Address**.

![Eka sign-up options screen](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/api-sdk/auth/images/eka-sign-up-options.png)

**2. Enter your email address**

Enter your email address and click **Submit**

![Eka enter email](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/api-sdk/auth/images/enter-email.png)

**3. Verify Email Using OTP**

Enter the one-time password (OTP) sent to your email address and click **Confirm**

![OTP verification screen](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/api-sdk/auth/images/verify-otp.png)

**4. Create Workspace**

You need to setup your workspace you use Eka. Enter your details and click on **Next**

![OTP verification screen](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/api-sdk/auth/images/setup-workspace.png)

**5. Automatic Account Creation and Login**

After submitting workspace details:

* Your Eka account is created
* You are automatically logged in
* Your workspace is ready to use

![Eka dashboard after signup](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/api-sdk/auth/images/console-dashboard.png)

## Creating API Credentials

Once your Eka account is set up, you can use the **Eka Developer Console**
to create and manage API client credentials. [Click here to visit Eka Developer Console](https://console.eka.care).

**1. Open the Eka Console Dashboard**

Once logged in, you’ll land on the Eka Console dashboard.

From the **Quick Actions** section, click
**Manage API Credentials (Client IDs and Secrets)**.

![Eka Console dashboard with Manage API Credentials highlighted](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/api-sdk/auth/images/developer-console-homepage.png)

**2. Create a New API Client**

Enter the required required details and click **Create**.

![Eka Console dashboard with Manage API Credentials highlighted](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/api-sdk/auth/images/create-api-creds.png)

**3. Copy Client Credentials**

After the client is created, securely copy:

* `client_id`
* `client_secret`

![Eka Console dashboard with Manage API Credentials highlighted](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/api-sdk/auth/images/save-client-secret.png)

> [!NOTE]
>
> Store the client secret securely. It will not be shown again.

### Authenticating with Eka APIs

**1. Obtain an Access Token**

Authenticate your client using the [login](/api-sdk/auth/client-login) API. This will return both an access token and a refresh token, which you will use for subsequent API requests.

**2. Using the Access Token**

Include the access token in the `auth` header of every API request to authenticate and access Eka’s services

**3. Handle Token Expiration**

To ensure continuous access to the API, implement logic to manage token expiration and renewal.

* If an API request returns a `401 Unauthorized` status code, it indicates that the access token has expired.
* Use the [refresh token](/api-sdk/auth/refresh-token-v2) API to obtain a new access token and re-authenticate.

## Accessing Another Workspace Using a Sharing Key

Eka allows access to another workspace using a **Sharing Key**. Developers who wish to access another workspace must request a Sharing Key
from the owner of that workspace. The Sharing Key can be generated from the Hub.
[Click here to visit Hub](https://hub.eka.care/account/).

**1. Generate a Sharing Key**

Click on ** API Token ** to visit page to view and manage sharing keys.
Click on ** Create ** and, provide the required information to create sharing key.

![Eka Console dashboard with Manage API Credentials highlighted](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/api-sdk/auth/images/hub-home.png)

![Create Sharing Key](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/api-sdk/auth/images/create-sharing-key.png)

**2. Provide the Sharing Key During Authentication**

After completing this step, continue to

[Authenticating with Eka APIs](/api-sdk/auth/getting-started#authenticating-with-eka-apis)

to generate an access token (provide ** sharing\_key ** in request body) and start making API requests.

***

## Long Lived Access Token

A Long-Lived Access Token is designed for backend-to-backend (server-to-server) communication between trusted systems.

**Why use a Long-Lived Token?**

* Simplifies authentication for system-to-system API calls
* Eliminates the need to repeatedly generate short-lived access tokens
* Ideal for long-running services and internal integrations

**When should you use this?**

* You are making backend-to-backend API calls
* You do not want to manage token refresh logic
* The integration is between trusted parties

**1. Generate Long Lived Token**

[Click here to visit Eka Developer Console](https://console.eka.care)
From the **Quick Actions** section, click
**Manage API Credentials (Client IDs and Secrets)**.
Click More options(three dot menu) and click on **Create Long Live Token**

![Eka Console dashboard with Manage API Credentials highlighted](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/api-sdk/auth/images/create-long-lived-token.png)

**2. Copy Long Live Token**

After the token is created, securely copy it.

![Save Long Live Token](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/api-sdk/auth/images/save-long-lived-token.png)

> [!NOTE]
>
> Store the token securely. It will not be shown again.

**3. Using Long Lived Token**

Include the token in the `Authorization` header of every API request to authenticate and access Eka’s services

## Best Practices

* Safeguard your client credentials (client\_id and client\_secret) at all times.
* Implement a reliable token renewal mechanism to handle token expiration.
* Always include the access token in the `auth` header for all API calls.
* Manage 401 Unauthorized errors gracefully by automatically refreshing the token.
* Ensure that your application complies with all privacy regulations when handling healthcare data.


# Authorize User
Source: https://developer.eka.care/api-sdk/auth/oauth2/authorize

get /oauth2/authorize
Starts the OAuth 2.0 Authorization Code flow.

Open this endpoint in the user's browser. Eka authenticates the user when
required and redirects the browser to the registered `redirect_uri`.
A successful redirect contains a short-lived, single-use authorization
`code` that your backend exchanges at `/oauth2/token`.

Eka grants a fixed scope set on this endpoint. Include it as the OAuth
`scope` query parameter:
`openid profile email offline_access`.

PKCE is optional. When using PKCE, use the `S256` challenge method and
generate a new verifier for every authorization request.


> [!NOTE]
>
> Open this endpoint in the user's browser. Do not call it as a backend API.

Use the Authorization Code flow. PKCE is optional. If you use PKCE, use
`code_challenge_method=S256` and generate a new verifier for every authorization request.
After authentication, Eka redirects the browser to your registered `redirect_uri` with a
single-use authorization code.

Your client application should verify `state` before exchanging the code. If your authorization
request includes a `nonce`, your client should verify it when validating the returned ID token.

> [!NOTE]
>
> Eka always grants this fixed scope set. Include it as the `scope` query parameter:
> `openid profile email offline_access`.


# Exchange Tokens
Source: https://developer.eka.care/api-sdk/auth/oauth2/token

post /oauth2/token
Exchanges a single-use authorization code for tokens, or exchanges a
refresh token for a new token set.

Refresh tokens are rotated on every refresh: each successful
`refresh_token` grant returns a new `refresh_token` and invalidates the
one that was sent. Always persist the latest refresh token from the
response.

Send parameters as `application/x-www-form-urlencoded`, including
`client_id` and `client_secret` in the form body.


Use this endpoint from your backend to:

* Exchange an authorization code using `grant_type=authorization_code`.
* Refresh a token set using `grant_type=refresh_token`.

Authorization codes are short-lived and can be used only once. If the authorization request used PKCE,
send the original `code_verifier` during the code exchange. A verifier is not used for the refresh-token grant.

Refresh tokens are rotated on every refresh. Each successful `refresh_token` grant returns a new
`refresh_token` and invalidates the one you sent, so always store the latest refresh token from the
response and use it for the next refresh. Reusing an old refresh token returns an `invalid_grant` error.


# Oidc Refresh
Source: https://developer.eka.care/api-sdk/auth/oidc-user-refresh

post /connect-auth/v1/oidc-client/{client_id}/refresh
Connect Client Auth Refresh



# Oidc Verify
Source: https://developer.eka.care/api-sdk/auth/oidc-user-verify

post /connect-auth/v1/oidc-client/{client_id}/verify
Connect Client Auth Verify and Eka Token



# Connect Refresh
Source: https://developer.eka.care/api-sdk/auth/refresh-token-v2

post /connect-auth/v1/account/refresh-token
Get new Authorization token using the refresh token



# Go SDK
Source: https://developer.eka.care/api-sdk/auth/sdks/go-sdk

A GO SDK for interacting with Eka Care APIs.

## Prerequisites

* Go 1.24+ (matches the SDK’s go.mod)
* Eka Care developer account and credentials (client\_id and client\_secret)

## Installation

```bash theme={null}
go get github.com/eka-care/eka-sdk-go
```

Install a specific version (recommended for reproducible builds):

```bash theme={null}
go get github.com/eka-care/eka-sdk-go@latest
# or pin to a specific release
go get github.com/eka-care/eka-sdk-go@vX.Y.Z
```

## Authentication and Setup

The SDK supports configuration via environment variables (recommended) or explicit options in code.

### Recommended: Environment variables

Set the following variables in your environment or a .env file:

```bash theme={null}
# Required
export EKA_ENVIRONMENT=production   # or development
export EKA_CLIENT_ID=your-client-id
export EKA_CLIENT_SECRET=your-client-secret
```

Then initialize the client from environment variables:

```go theme={null}
client := ekasdk.NewFromEnv()
```

### Alternative: Explicit configuration (not recommended for production)

```go theme={null}
client := ekasdk.New(
	ekasdk.WithEnvironment(ekasdk.EnvironmentProduction),
	ekasdk.WithClientID("your-client-id"),
	ekasdk.WithClientSecret("your-client-secret"),
)
```

## Quickstart

Authenticate and call an ABDM API (login init via PHR address):

```go theme={null}
package main

import (
	"context"
	"log"

	ekasdk "github.com/eka-care/eka-sdk-go"
	"github.com/eka-care/eka-sdk-go/internal/interfaces"
	"github.com/eka-care/eka-sdk-go/services/abdm/abha/login"
)

func auth() {
	ctx := context.Background()

	// Create SDK client from environment variables
	client := ekasdk.NewFromEnv()

	// Authenticate with Eka platform
	if err := client.Login(ctx); err != nil {
		log.Fatalf("Authentication failed: %v", err)
	}
}
```

## Configuration reference

* EKA\_CLIENT\_ID: Client ID from the developer portal (required)
* EKA\_CLIENT\_SECRET: Client secret from the developer portal (required)
* EKA\_ENVIRONMENT: production or development (required)

Configuration priority (highest to lowest):

* Environment variables
* Explicit options via WithXxx() functions
* Built-in defaults

## Troubleshooting

Typical auth/config errors when calling `client.Login(ctx)`:

```text theme={null}
"client ID is required for authentication. Set EKA_CLIENT_ID environment variable or use WithClientID() option"
"client secret is required for authentication. Set EKA_CLIENT_SECRET environment variable or use WithClientSecret() option"
"failed to authenticate with provided credentials: invalid client credentials"
```

## Examples and resources

* GitHub repository: [https://github.com/eka-care/eka-sdk-go](https://github.com/eka-care/eka-sdk-go)
* Examples: [https://github.com/eka-care/eka-sdk-go/tree/main/examples/quickstart](https://github.com/eka-care/eka-sdk-go/tree/main/examples/quickstart)
* Issues & support: [https://github.com/eka-care/eka-sdk-go/issues](https://github.com/eka-care/eka-sdk-go/issues)


# Java SDK
Source: https://developer.eka.care/api-sdk/auth/sdks/java-sdk

A Java Spring Boot SDK for interacting with Eka Care APIs.

# Overview

A Java Spring Boot SDK for processing medical documents through the Eka Care API. This SDK supports document submission, result polling, and FHIR data extraction.

## Prerequisites

* **JDK 17+** (verify with `java -version`)
* **Maven** (verify with `mvn -version`)
* **IDE**: IntelliJ IDEA, Eclipse, or VS Code with Java extensions
* **Eka Care API Credentials**: Valid client ID and secret

***

## Project Structure

```
ekacare-sdk/
├── src/main/java/com/example/ekacare/
│   ├── sdk/EkaCareSDK.java
│   ├── service/EkaCareService.java
│   └── controller/DocumentController.java
├── src/main/resources/application.properties
└── pom.xml
```

***

## Setup Instructions

### Step 1: Create Spring Boot Project

**Via Spring Initializr:**

* Visit [start.spring.io](https://start.spring.io)
* Select Maven, Java 17, Spring Boot 3.2.0
* Add "Spring Web" dependency
* Generate and extract

**Via IntelliJ IDEA:**
File → New → Project → Spring Initializr → Configure with Java 17 and Spring Boot 3.2.0

### Step 2: Add SDK Files

Copy files from the repository to respective directories:

* `EkaCareSDK.java` → `src/main/java/com/example/ekacare/sdk/`
* `EkaCareService.java` → `src/main/java/com/example/ekacare/service/`
* `application.properties` → `src/main/resources/`
* `pom.xml` → project root

### Step 3: Configure Credentials

Update `application.properties`:

```properties theme={null}
ekacare.client.id=YOUR_CLIENT_ID_HERE
ekacare.client.secret=YOUR_CLIENT_SECRET_HERE
```

### Step 4: Build

```bash theme={null}
mvn clean install
```

***

## Quick Start

### Direct SDK Usage

```java theme={null}
try (EkaCareSDK sdk = new EkaCareSDK("CLIENT_ID", "CLIENT_SECRET")) {
    Map<String, Object> result = sdk.processAndWait(
        "/path/to/document.jpg",
        "smart",
        10,  // poll interval (seconds)
        300  // timeout (seconds)
    );
    Map<String, Object> data = (Map<String, Object>) result.get("data");
    System.out.println("FHIR: " + data.get("fhir"));
}
```

### Spring Boot Service

```java theme={null}
@Component
public class MyDocumentProcessor {
    @Autowired
    private EkaCareService ekaCareService;

    public void process() throws InterruptedException {
        Map<String, Object> result = ekaCareService
            .processDocumentAndWait("/path/to/document.jpg", "smart");
        System.out.println("Result: " + result);
    }
}
```

***

## Example cURL Requests

```bash theme={null}
# Submit document asynchronously
curl -X POST http://localhost:8080/api/documents/process?task=smart \
  -F "file=@/path/to/document.jpg"

# Get processing result
curl http://localhost:8080/api/documents/abc123/result

# Synchronous processing (waits for completion)
curl -X POST http://localhost:8080/api/documents/process-sync?task=smart \
  -F "file=@/path/to/document.jpg"
```

***

## Troubleshooting

| Issue | Solution |
| - | - |
| File Not Found | Use absolute paths or verify relative path correctness |
| Authorization (401) | Validate credentials in properties file |
| Maven Build Fails | Run `mvn clean install -U` |
| Port 8080 In Use | Change in `application.properties`: `server.port=8081` |


# Python SDK
Source: https://developer.eka.care/api-sdk/auth/sdks/python-sdk

A Python SDK for interacting with Eka Care APIs.

You can install it as a python package as below

```bash theme={null}
pip install ekacare
```

***

## Quick Start

### Authentication

```python theme={null}
from ekacare import EkaCareClient

# Initialize with client credentials
client = EkaCareClient(
    client_id="your_client_id",
    client_secret="your_client_secret"
)

# Or initialize with an existing access token
client = EkaCareClient(
    client_id="your_client_id",
    client_secret="your_client_secret",
    access_token="your_access_token"
)

# Manually get an access token
token_response = client.auth.login()
access_token = token_response["access_token"]
```

***

## Error Handling

The SDK uses custom exceptions to handle errors:

```python theme={null}
from ekacare import EkaCareClient, EkaCareAPIError, EkaCareAuthError

client = EkaCareClient(
    client_id="your_client_id",
    client_secret="your_client_secret"
)

try:
    documents = client.records.list_documents()
except EkaCareAuthError as e:
    print(f"Authentication error: {e}")
except EkaCareAPIError as e:
    print(f"API error: {e}")
```

## License

This SDK is distributed under the MIT License.


# Push care context data to HIU
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/data-on-fetch

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/hip/care-context/data/on-fetch
Use this API to push encrypted FHIR data to the HIU after receiving the [`abha.hip_data_fetch`](/docs/hie-cm/webhooks/hip-data-fetch) webhook.

The HIP is responsible for preparing ABDM-compliant FHIR bundles, encrypting them using the key information received in the webhook, and pushing the data through this API. Use the `transaction_id` from the webhook payload to correlate the request.

This API is only needed if you are **not** storing health data on Eka servers.


## Used in

* [Serve records on a fetch request](/docs/hie-cm/workflows/serve-data-on-fetch)


# Push FHIR parsing status
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/data-on-push

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/hiu/care-context/data/on-push
API for HIU to push care context FHIR parsing status

## Used in

* [Receive and decrypt records as a HIU](/docs/hie-cm/workflows/hiu-receive-data)


# Fetch data push entry
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/data-push-entry

api-reference/user-app/abdm-connect/registration.yml GET /abdm/v1/hiu/care-context/data/{transaction_id}/entries/{content_ref}
Returns one entry of the [`abha.hiu_data_push`](/docs/hie-cm/webhooks/hiu-data-push) webhook, encrypted exactly as the HIP sent it.

**When to use**

Every entry in the webhook carries a `content_ref`. Large pushes cannot be delivered in one webhook, so for some entries `content` arrives as an empty string. Call this API for every entry whose `content` is empty. You can also call it for every entry and ignore the inline `content`.

An entry can be fetched for 15 minutes after the webhook is sent. After that it is deleted and cannot be fetched again, so fetch entries as soon as you receive the webhook.

**How to use**

1. From the webhook, take `data.transaction_id` (not the top-level `transaction_id`, which identifies the webhook delivery) and the entry's `content_ref`.
2. Call this API with the same credentials you use for the other ABDM Connect APIs.
3. Decrypt `content` with the webhook's `key_information` and your private key, the same way as an inline entry, and verify `checksum`.

A `404` means the transaction does not belong to your workspace, the `content_ref` is unknown, or the entry has expired.

<Note>We recommend fetching every entry through this API. Inline `content` in the webhook may be removed in a future version.</Note>



# Discover unlinked care-contexts
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/discover/discover

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/care-contexts/discover
ABDM allows a user to find their health records from any health facility they have visited via the discovery process. 

Discover API returns any unlinked care-context for the ABHA User.

## Used in

* [Discover and link records from a facility](/docs/hie-cm/workflows/phr-discover-and-link)


# Confirm Linking
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/discover/link-confirm

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/care-contexts/discover/link/confirm
Confirm linking for discovered care context

## Used in

* [Discover and link records from a facility](/docs/hie-cm/workflows/phr-discover-and-link)


# Initialise Linking
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/discover/link-init

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/care-contexts/discover/link/init
Initialise the linking for discovered care context.

## Used in

* [Discover and link records from a facility](/docs/hie-cm/workflows/phr-discover-and-link)


# Discover Link On Confirm
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/discover/link_on_confirm

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/care-contexts/discover/link/on-confirm
This API is used by HIP to confirm the linking of care contexts after OTP verification.

> [!NOTE]
>
> Call this API in response to the [Link Confirmation webhook](/docs/hie-cm/webhooks/discover-link-confirm), after validating the OTP. Use the `request_id` from the webhook payload and include the list of care contexts to be linked.

## Used in

* [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link)


# Discover Link On Init
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/discover/link_on_init

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/care-contexts/discover/link/on-init
This API is used by HIP to initiate the linking of unlinked health records (care contexts). HIP must send an OTP and provide details such as OTP expiry and other related information.

> [!NOTE]
>
> Call this API in response to the [Link Initiation webhook](/docs/hie-cm/webhooks/discover-link-init), after you have generated and sent the OTP to the patient. Use the `request_id` and `txn_id` from the webhook payload when constructing your response.

## Used in

* [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link)


# Discover On Care Contexts
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/discover/on_discover

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/care-contexts/on-discover
This API is used to send unlinked care contexts to abdm.

> [!NOTE]
>
> Call this API in response to the [Discovery Request Received webhook](/docs/hie-cm/webhooks/discover-care-context). Use the `request_id` and `txn_id` from the webhook payload when constructing your response.

## Used in

* [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link)


# Decrypt
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/ecdh/decrypt

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/ecdh/decrypt
Decrypt data using ECDH key exchange.

## Used in

* [Receive and decrypt records as a HIU](/docs/hie-cm/workflows/hiu-receive-data)


# Encrypt
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/ecdh/encrypt

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/ecdh/encrypt
Encrypt data using ECDH key exchange.

## Used in

* [Serve records on a fetch request](/docs/hie-cm/workflows/serve-data-on-fetch)


# Keys
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/ecdh/keys

api-reference/user-app/abdm-connect/registration.yml GET /abdm/v1/ecdh/keys
Generate ECDH key pair with nonce for encryption/decryption operations.

## Used in

* [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent)
* [Serve records on a fetch request](/docs/hie-cm/workflows/serve-data-on-fetch)


# Update public keyset
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/hiu-keys

api-reference/user-app/abdm-connect/registration.yml PATCH /abdm/v1/hiu/keyset
API to update the HIU's public keyset.

The client must generate a key pair, store the private key securely on their side, and push the public key and nonce to Eka using this API. This keyset can be updated at any time.

When requesting health data from external HIPs via ABDM, Eka shares this public key and nonce with the HIP. The client can then use their stored private key along with the public key shared by the external HIP to decrypt the health data received on the [Data Push Webhook](/docs/hie-cm/webhooks/hiu-data-push).

For details on key generation, encryption, and decryption, refer to the [ABDM Encryption and Decryption Guide](https://sandbox.abdm.gov.in/sandbox/v3/new-documentation?doc=EncryptionandDecryptions).


## Used in

* [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent)


# Care context linking
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/link/hip-linking

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/care-contexts/link
Use this API to link a care context to the patient's ABHA address. A care context represents a visit, test, or any logical grouping of health records.

After calling this API, listen for the [`abha.link_care_context`](/docs/hie-cm/webhooks/link-care-context) webhook to confirm whether the linking was successful. Once linked, other HIUs can request data for this care context through ABDM's consent flow.

You can optionally pass the FHIR data as a base64-encoded string in the `data` field. If provided, Eka stores it and handles data sharing automatically — you won't need to handle the `abha.hip_data_fetch` webhook. If not provided, you will receive the [`abha.hip_data_fetch`](/docs/hie-cm/webhooks/hip-data-fetch) webhook when an HIU requests the data.


## Used in

* [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip)


# Get Linked Providers
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/providers/providers

api-reference/user-app/abdm-connect/registration.yml GET /abdm/v1/care-contexts/providers

## Used in

* [List a patient's linked records](/docs/hie-cm/workflows/phr-list-records)


# Notify unlinked care contexts
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/records/notify

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/care-contexts/sms/notify
This API is used by HIP to notify the gateway when a new health record is ready to be shared with a user.

## Used in

* [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip)


# Get Linked CareContexts
Source: https://developer.eka.care/api-sdk/hie-cm/care-contexts/records/records

api-reference/user-app/abdm-connect/registration.yml GET /abdm/v1/care-contexts/linked

## Used in

* [List a patient's linked records](/docs/hie-cm/workflows/phr-list-records)


# Does Abha Address Exist
Source: https://developer.eka.care/api-sdk/hie-cm/commons/does-health-id-exist

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/registration/phr/check
This API endpoint allows to check whether provided health id is already present in system.

## Used in

* [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp)
* [Create an ABHA with face authentication](/docs/hie-cm/workflows/create-abha-face-auth)
* [Create an ABHA address with mobile OTP](/docs/hie-cm/workflows/create-abha-mobile-otp)


# Pincode Details
Source: https://developer.eka.care/api-sdk/hie-cm/commons/pincode-details

get /abdm/v1/registration/pincode/{pincode}
This API endpoint is used to fetch pincode details.



# Suggest Abha Address
Source: https://developer.eka.care/api-sdk/hie-cm/commons/suggest-abha-address

api-reference/user-app/abdm-connect/registration.yml GET /abdm/na/v1/registration/suggest
This API endpoint is used to fetch some suggested abha id that are available on the basis of user details.

## Used in

* [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp)
* [Create an ABHA with face authentication](/docs/hie-cm/workflows/create-abha-face-auth)
* [Create an ABHA address with mobile OTP](/docs/hie-cm/workflows/create-abha-mobile-otp)


# Get Status
Source: https://developer.eka.care/api-sdk/hie-cm/consents/auto-approval/get-status

api-reference/user-app/abdm-connect/registration.yml GET /abdm/v1/consents/auto-approval
Fetch the auto approval policy settings

## Used in

* [Set up the patient's health locker](/docs/hie-cm/workflows/set-up-health-locker)


# Update Auto Approval Policy
Source: https://developer.eka.care/api-sdk/hie-cm/consents/auto-approval/update-auto-approval-policy

api-reference/user-app/abdm-connect/registration.yml PATCH /abdm/v1/consents/auto-approval
Update the auto approval policy settings

## Used in

* [Set up the patient's health locker](/docs/hie-cm/workflows/set-up-health-locker)


# Consent Approve
Source: https://developer.eka.care/api-sdk/hie-cm/consents/consent-approve

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/consents/approve
This endpoint is used to approve the consent

## Used in

* [Approve, deny or revoke a consent in a PHR app](/docs/hie-cm/workflows/phr-act-on-consent)


# Consent Create
Source: https://developer.eka.care/api-sdk/hie-cm/consents/consent-create

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/consents/create

## Used in

* [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent)


# Consent Deny
Source: https://developer.eka.care/api-sdk/hie-cm/consents/consent-deny

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/consents/deny
This endpoint is used to deny the consent

## Used in

* [Approve, deny or revoke a consent in a PHR app](/docs/hie-cm/workflows/phr-act-on-consent)


# Consent Details
Source: https://developer.eka.care/api-sdk/hie-cm/consents/consent-details

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/consents/details

## Used in

* [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent)


# Consent List
Source: https://developer.eka.care/api-sdk/hie-cm/consents/consent-list

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/consents/list

## Used in

* [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent)


# Consent Revoke
Source: https://developer.eka.care/api-sdk/hie-cm/consents/consent-revoke

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/consents/revoke
This endpoint is used to revoke the consent

> [!NOTE]
>
> Getting list of consent artefact ids
>
> [Details API](/api-sdk/hie-cm/patient-requests/requests-get-details) has the list of consent artefacts under the key `providers.consent_artefact_id`.

## Used in

* [Approve, deny or revoke a consent in a PHR app](/docs/hie-cm/workflows/phr-act-on-consent)


# Change
Source: https://developer.eka.care/api-sdk/hie-cm/consents/pin/change

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/consents/pin/change
Change the consent pin by providing a old and new pin combination



# Exists
Source: https://developer.eka.care/api-sdk/hie-cm/consents/pin/exists

api-reference/user-app/abdm-connect/registration.yml GET /abdm/v1/consents/pin/exists
Returns if the user has already set the consent pin.

## Used in

* [Approve, deny or revoke a consent in a PHR app](/docs/hie-cm/workflows/phr-act-on-consent)


# Forgot Init
Source: https://developer.eka.care/api-sdk/hie-cm/consents/pin/forgot-init

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/consents/pin/forgot/init



# Forgot Verify
Source: https://developer.eka.care/api-sdk/hie-cm/consents/pin/forgot-verify

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/consents/pin/forgot/verify



# Reset
Source: https://developer.eka.care/api-sdk/hie-cm/consents/pin/reset

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/consents/pin/reset



# Set
Source: https://developer.eka.care/api-sdk/hie-cm/consents/pin/set

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/consents/pin/set

## Used in

* [Approve, deny or revoke a consent in a PHR app](/docs/hie-cm/workflows/phr-act-on-consent)


# Verify
Source: https://developer.eka.care/api-sdk/hie-cm/consents/pin/verify

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/consents/pin/verify
Verify the consent pin to approve/revoke consents

## Used in

* [Approve, deny or revoke a consent in a PHR app](/docs/hie-cm/workflows/phr-act-on-consent)


# Resend OTP
Source: https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/aadhaar-resend-otp

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/registration/aadhaar/resend
This endpoint is used to resend a otp for aadhaar registration process.

## Used in

* [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp)


# Auto Login
Source: https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/auto-login

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/registration/aadhaar/auto-login
API for Auto login

## Used in

* [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp)
* [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha)


# Create
Source: https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/create-abha

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/registration/aadhaar/create-phr
This API is used to create a new ABHA address

## Used in

* [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp)
* [Create an ABHA with face authentication](/docs/hie-cm/workflows/create-abha-face-auth)


# Generate OTP
Source: https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/initiate-registration

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/registration/aadhaar/init
This endpoint is used to initiate the Aadhaar registration process.

## Used in

* [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp)


# Mobile Resend OTP
Source: https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/mobile-resend-otp

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/registration/aadhaar/mobile/resend
This endpoint is used to resend the mobile otp for aadhaar registration process.

## Used in

* [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp)
* [Create an ABHA with face authentication](/docs/hie-cm/workflows/create-abha-face-auth)


# Mobile Verify OTP
Source: https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/mobile-verify

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/registration/aadhaar/mobile/verify
This API operates on a skip logic basis. If the mobile number provided in the second step differs from the one linked to the Aadhaar, this API will be used to verify the new mobile number.

## Used in

* [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp)
* [Create an ABHA with face authentication](/docs/hie-cm/workflows/create-abha-face-auth)


# Verify OTP
Source: https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/verify-otp

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/registration/aadhaar/verify
This endpoint is used to verify Aadhaar otp generated for registration using Aadhaar.

## Used in

* [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp)


# Capture Face
Source: https://developer.eka.care/api-sdk/hie-cm/enrollment/face-auth/face-auth-capture

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/face-auth/capture
Capture PID endpoint is used to capture face-auth pid.

## Used in

* [Create an ABHA with face authentication](/docs/hie-cm/workflows/create-abha-face-auth)


# Face Auth Init
Source: https://developer.eka.care/api-sdk/hie-cm/enrollment/face-auth/face-auth-init

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/face-auth/init
Face Auth endpoint is used to init face-auth endpoint.

## Used in

* [Create an ABHA with face authentication](/docs/hie-cm/workflows/create-abha-face-auth)


# Verify Face
Source: https://developer.eka.care/api-sdk/hie-cm/enrollment/face-auth/face-auth-verify

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/face-auth/verify
Verify PID endpoint is used to verify face-auth pid.

## Used in

* [Create an ABHA with face authentication](/docs/hie-cm/workflows/create-abha-face-auth)


# Create
Source: https://developer.eka.care/api-sdk/hie-cm/enrollment/mobile/create

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/registration/mobile/create-phr
This API is used to create a new ABHA address for the user.

## Used in

* [Create an ABHA address with mobile OTP](/docs/hie-cm/workflows/create-abha-mobile-otp)


# Generate OTP
Source: https://developer.eka.care/api-sdk/hie-cm/enrollment/mobile/init

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/registration/mobile/init
This endpoint is used to initiate the registration process for a mobile number.

## Used in

* [Create an ABHA address with mobile OTP](/docs/hie-cm/workflows/create-abha-mobile-otp)


# Resend OTP
Source: https://developer.eka.care/api-sdk/hie-cm/enrollment/mobile/resend

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/registration/mobile/resend
This endpoint is used to resend a mobile registration request.

## Used in

* [Create an ABHA address with mobile OTP](/docs/hie-cm/workflows/create-abha-mobile-otp)


# Verify OTP
Source: https://developer.eka.care/api-sdk/hie-cm/enrollment/mobile/verify

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/registration/mobile/verify
This endpoint allows  to verify a mobile otp.

## Used in

* [Create an ABHA address with mobile OTP](/docs/hie-cm/workflows/create-abha-mobile-otp)


# Generate OTP
Source: https://developer.eka.care/api-sdk/hie-cm/login/init

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/profile/login/init
Generates an OTP for login. Supports login via Aadhaar number, mobile number, ABHA number, and ABHA address.

## Used in

* [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha)


# Login
Source: https://developer.eka.care/api-sdk/hie-cm/login/login

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/profile/login/phr
Handles login via Aadhaar number, ABHA number, or mobile number.

## Used in

* [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha)


# Search Auth Methods
Source: https://developer.eka.care/api-sdk/hie-cm/login/methods

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/profile/login/methods
Searches for available authentication methods.

## Used in

* [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha)


# Verify OTP
Source: https://developer.eka.care/api-sdk/hie-cm/login/verify

api-reference/user-app/abdm-connect/registration.yml POST /abdm/na/v1/profile/login/verify
Verifies the login OTP. If logging in via ABHA address, this endpoint also completes the login process.

## Used in

* [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha)


# Link HFR
Source: https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hfr/link-facility

api-reference/user-app/abdm-connect/registration.yml POST /abdm/nhpr/v1/hfr/link
Link a facility to the ABDM Bridge

## Used in

* [Register and onboard a facility](/docs/hie-cm/workflows/register-hfr)


# Onboard HFR
Source: https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hfr/onboard-facility

api-reference/user-app/abdm-connect/registration.yml POST /abdm/nhpr/v1/hfr/onboard
Onboard Facility

## Used in

* [Register and onboard a facility](/docs/hie-cm/workflows/register-hfr)


# Search HFR
Source: https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hfr/search-facility

api-reference/user-app/abdm-connect/registration.yml GET /abdm/nhpr/v1/hfr/search/{hfrId}
Search Facility

## Used in

* [Register and onboard a facility](/docs/hie-cm/workflows/register-hfr)


# Check If HPR is Available
Source: https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hpr/check-hpr-available

api-reference/user-app/abdm-connect/registration.yml POST /abdm/nhpr/v1/hpr/aadhaar/check/available
Check HPR ID Availability

## Used in

* [Log in to HPR with a mobile OTP](/docs/hie-cm/workflows/hpr-mobile-login)


# Get HPR Info
Source: https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hpr/check-hpr-exist

api-reference/user-app/abdm-connect/registration.yml POST /abdm/nhpr/v1/hpr/aadhaar/check/exist
Check if HPR ID Exists

## Used in

* [Create an HPR ID with Aadhaar OTP](/docs/hie-cm/workflows/create-hpr-id)


# Create HPR
Source: https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hpr/create-hpr

api-reference/user-app/abdm-connect/registration.yml POST /abdm/nhpr/v1/hpr/aadhaar/create
Create HPR ID

## Used in

* [Create an HPR ID with Aadhaar OTP](/docs/hie-cm/workflows/create-hpr-id)


# Get Aadhaar OTP
Source: https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hpr/get-aadhar-otp

api-reference/user-app/abdm-connect/registration.yml POST /abdm/nhpr/v1/hpr/aadhaar/init
Get Aadhar OTP

## Used in

* [Create an HPR ID with Aadhaar OTP](/docs/hie-cm/workflows/create-hpr-id)


# Get Mobile OTP
Source: https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hpr/get-mobile-otp

api-reference/user-app/abdm-connect/registration.yml POST /abdm/nhpr/v1/hpr/aadhaar/mobile/init
Generate Mobile OTP

## Used in

* [Log in to HPR with a mobile OTP](/docs/hie-cm/workflows/hpr-mobile-login)


# Suggest IDs
Source: https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hpr/suggest-ids

api-reference/user-app/abdm-connect/registration.yml POST /abdm/nhpr/v1/hpr/aadhaar/suggest
Get Suggested HPR IDs

## Used in

* [Create an HPR ID with Aadhaar OTP](/docs/hie-cm/workflows/create-hpr-id)


# Verify Aadhaar OTP
Source: https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hpr/verify-aadhar-otp

api-reference/user-app/abdm-connect/registration.yml POST /abdm/nhpr/v1/hpr/aadhaar/verify
Verify Aadhar OTP

## Used in

* [Create an HPR ID with Aadhaar OTP](/docs/hie-cm/workflows/create-hpr-id)


# Verify Mobile
Source: https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hpr/verify-mobile

api-reference/user-app/abdm-connect/registration.yml POST /abdm/nhpr/v1/hpr/aadhaar/demo/verify
Verify Aadhaar Linked Mobile

## Used in

* [Create an HPR ID with Aadhaar OTP](/docs/hie-cm/workflows/create-hpr-id)


# Verify Mobile OTP
Source: https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hpr/verify-mobile-otp

api-reference/user-app/abdm-connect/registration.yml POST /abdm/nhpr/v1/hpr/aadhaar/mobile/verify
Verify Mobile OTP

## Used in

* [Log in to HPR with a mobile OTP](/docs/hie-cm/workflows/hpr-mobile-login)


# Onboard facility
Source: https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/onboarding

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/hip/onboard
Onboard facility

## Used in

* [Register and onboard a facility](/docs/hie-cm/workflows/register-hfr)


# Overview
Source: https://developer.eka.care/api-sdk/hie-cm/overview

Environments, authentication, headers, callbacks and errors for the ABDM Connect APIs, plus a Postman collection with every API and callback.

ABDM Connect is a REST API over the ABDM gateway. You call Eka, and Eka handles ABDM's gateway protocol, encryption and callbacks for you. This page covers what every ABDM Connect call has in common. New to ABDM? Read the [ABDM overview](/docs/hie-cm/about) first for the ecosystem, roles and milestones.

## In short

* Eka handles ABDM's gateway protocol, encryption and callbacks for you.
* Every call takes an Eka access token; some also need the patient's ABHA session.
* Many results arrive later on a webhook you register.

## Postman Collection

Every ABDM Connect API and callback, grouped by milestone in the order you build them, and a sandbox environment to fill in. Run **Connect Login** first; each step keeps the `txn_id`, `request_id` and user token it gets back for the steps after it. Callback requests replay the payloads Eka sends, so you can test your own webhook receiver.

[Collection](/api-reference/user-app/abdm-connect/postman/eka-abdm-connect.postman_collection.json)
[Environment](/api-reference/user-app/abdm-connect/postman/eka-abdm-connect-sandbox.postman_environment.json)

`https://developer.eka.care/api-reference/user-app/abdm-connect/postman/eka-abdm-connect.postman_collection.json`
Copy collection link

Postman, Insomnia, Hoppscotch and Bruno take this through Import, as a link or as the downloaded file.

## Environments

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

Build and certify against the sandbox, then switch the base URL.

## Authentication

Every ABDM Connect API takes an Eka access token for your client.

**1. Log in**

Call [Connect Login](/api-sdk/auth/client-login) with your `client_id` and `client_secret`. It returns an `access_token` and a `refresh_token`.

**2. Send the token**

Pass it on every request as `Authorization: Bearer <access_token>`.

**3. Refresh on 401**

A `401` means the access token expired. Get a new one with [Connect Refresh](/api-sdk/auth/refresh-token-v2).

```bash theme={null}
curl https://api.dev.eka.care/abdm/v1/session/status \
  --header 'Authorization: Bearer <access_token>' \
  --header 'X-Pt-Id: <eka user id>'
```

See [Authorization](/api-sdk/auth/getting-started) to get credentials.

### The patient's ABHA session

Some APIs also act for a specific patient and need their ABHA session with the ABDM gateway. It is separate from your client token:

* ABHA creation, login and [session verify](/api-sdk/hie-cm/session/verify) return the patient's `token`. APIs that need it, such as KYC, take it as `user_x_token` in the body.
* When the ABHA session expires, these APIs return HTTP `491`. Check it with [Session Status](/api-sdk/hie-cm/session/status) and start a new one with a mobile OTP. See [User Session](/docs/hie-cm/session/getting-started).

## Common Headers

Most ABDM Connect APIs take these headers to say which patient and facility the call is for.

| Header | Value |
| - | - |
| `X-Pt-Id` | Eka user ID (OID) of the patient |
| `X-Partner-Pt-Id` | Your own ID for the patient |
| `X-Hip-Id` | Your HIP ID, for the facility the call is made from |

Each API page lists the headers that call takes.

## Multi-step Flows

OTP and linking flows take more than one call. The first call returns a `txn_id` (or a `request_id`), and every later step in that flow sends it back.

## APIs by Milestone

| Milestone | Who needs it | Start here | Flow |
| - | - | - | - |
| M1: ABHA identity | Every integration | [ABHA creation and login](/docs/hie-cm/registration/intro), [Profile](/docs/hie-cm/profile/getting-started), [Scan & Share](/docs/hie-cm/scan-and-share/getting-started) | [M1 flow](/docs/hie-cm/flows/m1) |
| M2: Care context linking and data sharing | HIPs | [Care contexts](/docs/hie-cm/care-contexts/getting-started), [Discover and link](/docs/hie-cm/care-contexts/discover/introduction) | [M2 flow](/docs/hie-cm/flows/m2) |
| M3: Consent and data fetch | HIUs | [Consents](/docs/hie-cm/consents/getting-started) | [M3 flow](/docs/hie-cm/flows/m3) |
| M4: HPR and HFR | Every HMIS/LMIS | [Registries](/docs/hie-cm/nhpr-abdm/getting-started) | [M4 flow](/docs/hie-cm/flows/m4) |
| PHR app | Patient-facing apps | [PHR API map](/docs/hie-cm/phr/overview) | |
| UHI | Discovery and booking | [Blood bank](/docs/uhi/blood-bank/getting-started) | |
| NHCX | Hospitals raising cashless insurance claims | [NHCX claims](/docs/nhcx/getting-started) | |

## Callbacks

ABDM is asynchronous: many results reach you later as a webhook. Register your endpoint with the [Webhooks API](/api-sdk/webhooks/register-webhook). Every callback is a `POST` with a JSON body that names its `event`, and carries an `Eka-Webhook-Signature` header you should [verify](/docs/webhooks/webhook-signature).

| Event | Sent when |
| - | - |
| [`abha.created`](/docs/hie-cm/webhooks/abha-created) | An ABHA address is created |
| [`abha.locker_created`](/docs/hie-cm/webhooks/locker-created) | A health locker is created |
| [`abha.hip_profile_share`](/docs/hie-cm/webhooks/hip-scan-and-share) | A patient shares their profile by scanning your QR code |
| [`abha.link_care_context`](/docs/hie-cm/webhooks/link-care-context) | A care context you linked succeeds or fails |
| [`abha.care_context_discover`](/docs/hie-cm/webhooks/discover-care-context) | A patient searches your facility for their records |
| [`abha.care_context_discover_link_init`](/docs/hie-cm/webhooks/discover-link-init) | A patient starts linking the records they found |
| [`abha.context_discover_link_confirm`](/docs/hie-cm/webhooks/discover-link-confirm) | A patient confirms that link with an OTP |
| [`abha.hip_data_fetch`](/docs/hie-cm/webhooks/hip-data-fetch) | An HIU requests records you hold (only if Eka doesn't store them) |
| [`abha.hiu_data_push`](/docs/hie-cm/webhooks/hiu-data-push) | Records you requested arrive from a HIP |
| [`abha.subscription_notify`](/docs/hie-cm/webhooks/subscription-notify) | A provider links a new record for a subscribed patient |
| [`abha.subscription_modified`](/docs/hie-cm/webhooks/subscription-modify) | A subscription changes |
| [`abha.consent_update`](/docs/hie-cm/webhooks/consent-update) | A consent request's status changes |

## Encryption

Health records travel between HIPs and HIUs encrypted with ECDH on Curve25519. If Eka stores your records, Eka encrypts and decrypts them for you. If you serve records yourself, see [ECDH encryption](/docs/hie-cm/care-contexts/ecdh-encryption).

## Errors

`4XX` codes are request errors and `5XX` are server errors. Error bodies look like this:

```json theme={null}
{
  "code": 400,
  "error": "Validation failed",
  "source_error": {
    "code": "ABDM-1010",
    "message": "Validation failed"
  }
}
```

`source_error` carries ABDM's own code when the gateway refused the call. See [Errors](/docs/hie-cm/errors) for every code.

## SDKs

> **[ABHA Web SDK (M1)](/api-sdk/hie-cm/sdks/web-sdk/abha-sdk/get-started)**
>
> Drop-in ABHA creation, login, KYC and Scan & Share screens.

> **[Consent Management Web SDK (M3)](/api-sdk/hie-cm/sdks/web-sdk/consent-management/get-started)**
>
> A UI widget to request, track and act on consents for your patients.

> **[NHPR Web SDK (M4)](/api-sdk/hie-cm/sdks/web-sdk/nhpr-sdk/get-started)**
>
> A UI widget to register doctors on the HPR and their clinic on the HFR.

> **[Go SDK](/api-sdk/hie-cm/sdks/backend/go-sdk)**
>
> Backend client for the ABDM Connect APIs.


# List Requests
Source: https://developer.eka.care/api-sdk/hie-cm/patient-requests/list-requests

api-reference/user-app/abdm-connect/registration.yml GET /abdm/v1/requests
API to list all the Subscriptions and Consent requests

## Used in

* [Approve, deny or revoke a consent in a PHR app](/docs/hie-cm/workflows/phr-act-on-consent)


# Requests Get Details
Source: https://developer.eka.care/api-sdk/hie-cm/patient-requests/requests-get-details

api-reference/user-app/abdm-connect/registration.yml GET /abdm/v1/request

## Used in

* [Approve, deny or revoke a consent in a PHR app](/docs/hie-cm/workflows/phr-act-on-consent)


# ABHA card
Source: https://developer.eka.care/api-sdk/hie-cm/profile/cards/abha-card

api-reference/user-app/abdm-connect/registration.yml GET /abdm/v1/profile/asset/card
Fetch the ABHA card.<Note>Please cache these results locally. We do not recommend calling this API on every page load. Evict the cache when there is profile update.</Note>

## Used in

* [Manage the ABHA profile and KYC](/docs/hie-cm/workflows/manage-profile-and-kyc)


# ABHA QR Code
Source: https://developer.eka.care/api-sdk/hie-cm/profile/cards/qr-code

api-reference/user-app/abdm-connect/registration.yml GET /abdm/v1/profile/asset/qr
Fetch the data for ABHA qr code display. <Note>Please cache these results locally. We do not recommend calling this API on every page load. Evict the cache when there is profile update.</Note><Warning>There is no fixed structure for this JSON; it can vary depending on the creation of ABHA. Generate the QR code based on the content of the response body.</Warning>

## Used in

* [Manage the ABHA profile and KYC](/docs/hie-cm/workflows/manage-profile-and-kyc)


# Delete Profile
Source: https://developer.eka.care/api-sdk/hie-cm/profile/details/delete

api-reference/user-app/abdm-connect/registration.yml DELETE /abdm/v1/profile
This endpoint removes the specified ABHA profile along with all associated documents, vital records, and any other related data from the system.<Warning>Please note that the ABHA metadata will remain in the ABDM system, as ABDM does not provide a delete option</Warning>

## Used in

* [Manage the ABHA profile and KYC](/docs/hie-cm/workflows/manage-profile-and-kyc)


# Profile Details
Source: https://developer.eka.care/api-sdk/hie-cm/profile/details/profile-details

api-reference/user-app/abdm-connect/registration.yml GET /abdm/v1/profile
Fetches the ABHA profile of the User. <Note>Please cache these results locally. We do not recommend calling this API on every page load. Evict the cache when there is profile update.</Note>

## Used in

* [Manage the ABHA profile and KYC](/docs/hie-cm/workflows/manage-profile-and-kyc)


# Update Profile
Source: https://developer.eka.care/api-sdk/hie-cm/profile/details/update-profile

api-reference/user-app/abdm-connect/registration.yml PATCH /abdm/v1/profile
<Warning>Name, gender and date of birth cannot be edited for a KYC verified ABHA</Warning>

## Used in

* [Manage the ABHA profile and KYC](/docs/hie-cm/workflows/manage-profile-and-kyc)


# Kyc Init
Source: https://developer.eka.care/api-sdk/hie-cm/profile/kyc/kyc-init

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/profile/kyc/init
Request otp to initialise the KYC flow

## Used in

* [Manage the ABHA profile and KYC](/docs/hie-cm/workflows/manage-profile-and-kyc)


# Kyc Resend
Source: https://developer.eka.care/api-sdk/hie-cm/profile/kyc/kyc-resend

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/profile/kyc/resend
Resend otp for KYC

## Used in

* [Manage the ABHA profile and KYC](/docs/hie-cm/workflows/manage-profile-and-kyc)


# Kyc Verify
Source: https://developer.eka.care/api-sdk/hie-cm/profile/kyc/kyc-verify

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/profile/kyc/verify
Verify OTP to complete KYC

## Used in

* [Manage the ABHA profile and KYC](/docs/hie-cm/workflows/manage-profile-and-kyc)


# Search ABHA
Source: https://developer.eka.care/api-sdk/hie-cm/profile/search/search

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/profile/search
Search KYCed ABHA profiles using mobile number

> [!NOTE]
>
> Use the [Login APIs](/api-sdk/hie-cm/login/init) to complete the login

## Used in

* [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha)


# Get Provider Details
Source: https://developer.eka.care/api-sdk/hie-cm/providers/provider

api-reference/user-app/abdm-connect/registration.yml GET /abdm/v1/provider/{hip_id}
Fetches the Providers based on the HIP ID.

## Used in

* [Discover and link records from a facility](/docs/hie-cm/workflows/phr-discover-and-link)


# Search Providers
Source: https://developer.eka.care/api-sdk/hie-cm/providers/search/providers

api-reference/user-app/abdm-connect/registration.yml GET /abdm/v1/providers
Fetches the List of Providers.

## Used in

* [Discover and link records from a facility](/docs/hie-cm/workflows/phr-discover-and-link)


# Request to generate token
Source: https://developer.eka.care/api-sdk/hie-cm/scan-and-share/phr-scan-share

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v2/profile/share
Request to generate appointment token at the facility. <Note> Get the hip_id and counter_id by reading the QR code of the Hospital/Clinic.</Note> <Note>Use the device location for the location data</Note>

## Used in

* [Share a profile at a facility counter](/docs/hie-cm/workflows/phr-scan-and-share)


# Get appointment token
Source: https://developer.eka.care/api-sdk/hie-cm/scan-and-share/phr-scan-share-token

api-reference/user-app/abdm-connect/registration.yml GET /abdm/v2/profile/share/{request_id}
Get token number issued by the facility

## Used in

* [Share a profile at a facility counter](/docs/hie-cm/workflows/phr-scan-and-share)


# Profile Share V1
Source: https://developer.eka.care/api-sdk/hie-cm/scan-and-share/profile-share-v1

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/profile/share
Fetch the token from a hospital. <Note> Get the hip_id and counter_id by reading the QR code of the Hospital/Clinic.</Note> <Note>Use the device location for the location data</Note>



# On-Share
Source: https://developer.eka.care/api-sdk/hie-cm/scan-and-share/scan-on-share

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/hip/patient/profile/on-share
This API receives the Token Generated by the facility.

## Used in

* [Receive a scanned profile as a HIP](/docs/hie-cm/workflows/hip-scan-and-share)


# Golang
Source: https://developer.eka.care/api-sdk/hie-cm/sdks/backend/go-sdk



A Go SDK for integrating with Eka Care’s healthcare APIs, including ABDM (Ayushman Bharat Digital Mission) services.

## Overview

Use this SDK to authenticate with Eka Care, call ABDM services, and build backend integrations in Go with minimal boilerplate.

## Prerequisites

* Go 1.24+ (matches the SDK’s go.mod)
* Eka Care developer account and credentials (client\_id and client\_secret)

## Installation

```bash theme={null}
go get github.com/eka-care/eka-sdk-go
```

Install a specific version (recommended for reproducible builds):

```bash theme={null}
go get github.com/eka-care/eka-sdk-go@latest
# or pin to a specific release
go get github.com/eka-care/eka-sdk-go@vX.Y.Z
```

## Authentication and Setup

The SDK supports configuration via environment variables (recommended) or explicit options in code.

### Recommended: Environment variables

Set the following variables in your environment or a .env file:

```bash theme={null}
# Required
export EKA_ENVIRONMENT=production   # or development
export EKA_CLIENT_ID=your-client-id
export EKA_CLIENT_SECRET=your-client-secret
```

Then initialize the client from environment variables:

```go theme={null}
client := ekasdk.NewFromEnv()
```

### Alternative: Explicit configuration (not recommended for production)

```go theme={null}
client := ekasdk.New(
	ekasdk.WithEnvironment(ekasdk.EnvironmentProduction),
	ekasdk.WithClientID("your-client-id"),
	ekasdk.WithClientSecret("your-client-secret"),
)
```

## Quickstart

Authenticate and call an ABDM API (login init via PHR address):

```go theme={null}
package main

import (
	"context"
	"log"

	ekasdk "github.com/eka-care/eka-sdk-go"
	"github.com/eka-care/eka-sdk-go/internal/interfaces"
	"github.com/eka-care/eka-sdk-go/services/abdm/abha/login"
)

func main() {
	ctx := context.Background()

	// Create SDK client from environment variables
	client := ekasdk.NewFromEnv()

	// Authenticate with Eka platform
	if err := client.Login(ctx); err != nil {
		log.Fatalf("Authentication failed: %v", err)
	}

	// Common headers used by ABDM services
	headers := interfaces.Headers{
		PatientID:     "eka-user-oid",
		PartnerUserID: "your-user-id",
		HipID:         "your-hip-id",
	}

	// Example: ABDM login (init via PHR address)
	otpReq := &login.InitLoginRequest{
		Identifier: "demo@abdm",
		Method:     login.LoginMethodPhrAddress,
	}

	otpResp, err := client.ABDM.Login().LoginInit(ctx, headers, otpReq)
	if err != nil {
		log.Printf("ABDM login failed: %v", err)
		return
	}

	log.Printf("Success! Transaction ID: %s", otpResp.TxnID)
}
```

## Configuration reference

* EKA\_CLIENT\_ID: Client ID from the developer portal (required)
* EKA\_CLIENT\_SECRET: Client secret from the developer portal (required)
* EKA\_ENVIRONMENT: production or development (required)

Configuration priority (highest to lowest):

* Environment variables
* Explicit options via WithXxx() functions
* Built-in defaults

## Available services

Once authenticated, you can access:

* ABDM services: `client.ABDM.Login()`, `client.ABDM.Registration()`, `client.ABDM.Profile()`
* More services will be added as they become available

## Troubleshooting

Typical auth/config errors when calling `client.Login(ctx)`:

```text theme={null}
"client ID is required for authentication. Set EKA_CLIENT_ID environment variable or use WithClientID() option"
"client secret is required for authentication. Set EKA_CLIENT_SECRET environment variable or use WithClientSecret() option"
"failed to authenticate with provided credentials: invalid client credentials"
```

## Examples and resources

* GitHub repository: [https://github.com/eka-care/eka-sdk-go](https://github.com/eka-care/eka-sdk-go)
* Examples: [https://github.com/eka-care/eka-sdk-go/tree/main/examples/quickstart](https://github.com/eka-care/eka-sdk-go/tree/main/examples/quickstart)
* Issues & support: [https://github.com/eka-care/eka-sdk-go/issues](https://github.com/eka-care/eka-sdk-go/issues)


# Profile KYC
Source: https://developer.eka.care/api-sdk/hie-cm/sdks/web-sdk/abha-sdk/abha-kyc

Complete implementation guide for the ABHA SDK to be used for ABHA KYC Verification Flow.

# ABHA SDK - Profile KYC Implementation

This guide provides everything you need to integrate the ABHA SDK into your application for ABHA Profile KYC Verification.

* **ABHA Profile KYC**: Get your ABHA address KYC verified.

### Implementation Example

Add the following HTML and script tags to your webpage:

> [!NOTE]
>
> For staging/dev environments, replace the SDK URLs with:
>
> * **JS:** `https://unpkg.com/@eka-care/abha-stg/dist/sdk/abha/js/abha.js`
> * **CSS:** `https://unpkg.com/@eka-care/abha-stg/dist/sdk/abha/css/abha.css`

```html theme={null}
<!DOCTYPE html>
<html>
  <head>
    <title>ABHA SDK Integration for ABHA Profile KYC</title>

    <!-- Include ABHA SDK CSS -->
    <link
      rel="stylesheet"
      href="https://unpkg.com/@eka-care/abha/dist/sdk/abha/css/abha.css"
    />
  </head>
  <body>
    <h1>ABHA SDK Demo</h1>

    <!-- Mount Button -->
    <button class="button" onclick="mountABHASDK()">Mount SDK</button>

    <!-- Container for ABHA SDK -->
    <div id="sdk_container"></div>

    <!-- Include ABHA SDK JS -->
    <script
      type="module"
      src="https://unpkg.com/@eka-care/abha/dist/sdk/abha/js/abha.js"
    ></script>

    <script>
      function mountABHASDK() {
        window.initAbhaApp({
          containerId: "sdk_container",
          clientId: 'ext',

         // Pass the data here: 
          data: {
             accessToken: "<your_access_token>", // Pass the access token you have
             oid: "<patient_oid>", // Pass OID of the patient
             hipId: "<available_HFR_ID>", // Pass the HFR ID you have
             identifier:'<phr_address_of_the_patient_to_be_kyced>', // Pass the phr address as identifier to get it kyc verified 
             identifier_type:"phr_address",  // Pass the identifier type i.e. "phr_address"
             flow:'abha-kyc', // Pass the flow as abha-kyc
             orgIconUrl: "<url_of_your_org_logo>", // Pass the url of the logo of your organisation for ex https://cdn.eka.care/vagus/cl5jgf0u500070shaetqw0r5l.png
             linkToOrgIcon: "<url_of_image_to_link_abha_to_your_org>", // Pass the url of an image which depicts linking abha to your organisation for ex https://cdn.eka.c
          },

          // KYC Success callback
          onKYCSuccess: (params) => {
            console.log("ABHA KYC Verified successfully:", params);
            
            // Example: Store ABHA data in your app
            if (window.EkaAbha) {
              window.EkaAbha.onAbhaKYCSuccess(JSON.stringify(params));
            }
          },

          // Error callback
          onError: (params) => {
            console.error("ABHA SDK failed:", params);

            // Example: Store ABHA data in your app
            if (window.EkaAbha) {
              window.EkaAbha.onAbhaFailure(JSON.stringify(params));
            }
          },

          // Abha Close callback
          onAbhaClose: () => {
            console.log("ABHA SDK closed");
          }, 

        });
      }
    </script>
  </body>
</html>
```

## Core Functions

### 1. initAbhaApp

Initializes and renders the ABHA SDK in your specified container.

**Parameters:**

| Name | Type | Required | Description |
| - | - | - | - |
| `containerId` | `string` | | The HTML element ID where the SDK will mount. |
| `clientId` | `string` | | Provide clientId as `ext`. |
| `data` | `{` `accessToken: string;` `oid?: string;` `hipId?: string;` `identifier: string;` `identifier_type: string;` `flow: string;` `orgIconUrl?: string;` `linkToOrgIcon?: string;` ` }` |  Optional | Configuration data for initializing the ABHA flow.  - **accessToken:** Pass the access token you have generated from [Connect Login ](https://developer.eka.care/api-sdk/auth/client-login) API without the word `Bearer`. - **oid:** Pass the OID of the patient if available. - **hipId:** Pass the HFR ID you have. - **identifier:** Pass the identifier value i.e. phr address to get it kyced. - **identifier\_type:** Pass the type of identifier which you passed in `identifier` key i.e. "phr\_address".  - **flow:** Pass the type of flow for which you want to use SDK for i.e. `abha-kyc` for KYC flow. - **orgIconUrl:** Public CDN URL of the logo of your organisation url should start with https\://. [Example](https://cdn.eka.care/vagus/cl5jgf0u500070shaetqw0r5l.png) - **linkToOrgIcon:** Public CDN URL of the icon representing “Link ABHA to your organisation” url should start with https\://. [Example](https://cdn.eka.care/vagus/cm6agrs5000090tfwfz984x5b.webp)   `keys with ? are optional.` |
| `onKYCSuccess` | `(params: TOnAbhaKycSuccessParams) => void` | | Triggered when the user KYC verified successfully. |
| `onError` | `(params: TOnAbhaFailureParams) => void` | | Triggered when an error occurs during the ABHA flow. |
| `onAbhaClose` | `() => void` | | Triggered when SDK closes. |

**Example:**

```javascript theme={null}
window.initAbhaApp({
  containerId: "sdk_container",
  data: {
    accessToken: "your_access_token_here",
    oid: "patient_oid_here",
    identifier: "phr_address_of_the_patient_to_be_kyced"
    identifier_type: "phr_address"
    flow: "abha-kyc"
    hipId: "available HFR ID",
    linkToOrgIcon: "url_of_image_to_link_abha_to_your_org",
  },
  onKYCSuccess: (params) => {
    console.log("ABHA KYC verification successful!", params);
  },
  onError: (error) => {
    console.error("ABHA flow failed:", error);
  },
  onAbhaClose: (error) => {
    console.error("ABHA SDK closed");
  },
});
```

## Callback Parameters

### onKYCSuccess Callback

The onKYCSuccess callback is triggered when the ABHA KYC flow completes successfully.
It returns a confirmation message indicating that the KYC has been verified.

**Callback Signature:**

```typescript theme={null}
onKYCSuccess: (params: TOnAbhaKycSuccessParams) => void;
```

**Type Definitions**

```typescript theme={null}
type TOnAbhaKycSuccess = string;
```

**Parameters**

| | Type | Description |
| - | - | - |
| `TOnAbhaKycSuccess` | `string` | A confirmation message from SDK post KYC verification |

**Example:**

```javascript theme={null}
const onKYCSuccess = (params) => {
  console.log("KYC verification Success:", params);

  alert("KYC was verified successfully!");

  // Optionally pass data to native bridge if available
  if (window.EkaAbha) {
    window.EkaAbha.onAbhaKYCSuccess(params);
  }
};
```

### onError Callback

The onError callback is triggered whenever an ABHA flow fails or is interrupted.
It provides details about the failure through structured parameters, allowing you to handle or forward the error appropriately (for example, to native apps or monitoring tools).

**Callback Signature:**

```typescript theme={null}
onError: (params: TOnAbhaFailureParams) => void;
```

**Type Definitions**

```typescript theme={null}
type TOnAbhaFailureParams = {
  error?: string;
  response?: TAuthVerifyV2Response;
};

type TAuthVerifyV2Response = {
  skip_state: number;
  method: AUTH_METHOD;
  data?: {
    tokens: {
      sess: string;
      refresh: string;
    };
    profile: TProfileRecord;
  };
  txn_id: string;
  error?: {
    code: number;
    message: string;
  };
};

enum AUTH_METHOD {
  EMAIL = 1,
  MOBILE = 2,
  ABHA = 7,
}

type TProfileRecord = {
  fln: string;
  fn: string;
  mn?: string;
  ln?: string;
  gen?: "M" | "F" | "O" | "U" | undefined; // 'male' | 'female' | 'other' | 'unknown'
  dob?: string;
  mobile?: string;
  email?: string;
  uuid?: string;
  bloodgroup?: "" | "A+" | "A-" | "B+" | "B-" | "O+" | "O-" | "AB+" | "AB-";
  pic?: string;
  as?: string;
  "dob-valid"?: boolean;
  "is-d"?: boolean;
  "is-d-s"?: boolean;
  "is-p"?: boolean;
  oid: string;
  at: string;
  type?: 1 | 2 | 3 | 4 | 5 | 6;
  "health-ids"?: Array<string>;
  abha_number?: string;
  kyc_verified?: boolean;
};

```

**Parameters**

| Key | Type | Description |
| - | - | - |
| `error` | `string?` | Short description of the failure or error message. |
| `response` | `TAuthVerifyV2Response?` | Partial or full API response object returned from ABHA services. |

**Example:**

```javascript theme={null}
const onError = (params) => {
  console.error("ABHA Error:", params);

  if (params.response?.error?.code === 1001) {
    alert("Authentication failed. Please try again.");
  } else if (params.error === "NETWORK_ERROR") {
    alert("Please check your internet connection.");
  } else {
    alert("Something went wrong. Please retry.");
  }

  // Forward the error to native handler if available
  if (window.EkaAbha) {
    window.EkaAbha.onAbhaFailure(JSON.stringify(params));
  }
};
```

### onAbhaClose Callback

The onAbhaClose callback is triggered when the ABHA SDK flow gets closed.

**Callback Signature:**

```typescript theme={null}
onAbhaClose: () => void;
```

**Example:**

```javascript theme={null}
const onAbhaClose = () => {
  console.log("ABHA SDK Closed");
};
```

**Suggest Handling**

* Always log the full error response (params) for debugging.
* Display friendly error messages for known error.code values.
* If params.response is present, inspect response.error.message for more detail.
* If integrating with native apps, forward the serialized error object:

```javascript theme={null}
window.EkaAbha.onAbhaFailure(JSON.stringify(params));
```

## Container Styling

Ensure your container has sufficient space:

```html theme={null}
<div
  id="sdk_container"
  style="width: 100%; height: 600px; border: 1px solid #ddd;"
></div>
```

## Troubleshooting

### Common Issues

#### 1. SDK Not Rendering

**Problem**: Nothing appears in the container.

**Solution**:

* Ensure containerId matches an existing HTML element.
* Verify the SDK JS and CSS are correctly loaded.
* Check browser console for errors.

#### 2. APIs Not Being Called

**Problem**: API requests are not triggered after the SDK is mounted.

**Solution**:

* Ensure that the accessToken is passed correctly (do not include the Bearer prefix) and that the token has not expired.
* To prevent CORS-related issues, ensure that your domain is whitelisted.

#### 3. Callback Not Triggered

**Problem**: onSuccess, onError, onKYCSuccess, onConsentSuccess, onAbhaClose isn’t firing.

**Solution**:

* Make sure callbacks are passed as valid functions.
* Avoid race conditions (e.g., calling before SDK fully loads).

#### 4. Styling Issues

**Problem**: SDK content appears misaligned or clipped.

**Solution**:

* Give your container a fixed height (e.g., 600px).
* Ensure no parent element uses overflow: hidden.


# Registration
Source: https://developer.eka.care/api-sdk/hie-cm/sdks/web-sdk/abha-sdk/abha-login-create

Complete implementation guide for the ABHA SDK to be used for ABHA Login or Create.

# ABHA SDK - Login or Create

This guide provides everything you need to integrate the ABHA SDK into your application for Create ABHA, Login with ABHA flows into your healthcare applications. It provides:

* **Create ABHA**: Create a new ABHA using Mobile or Aadhaar.
* **Login with ABHA**: Login to your exisiting ABHA using PHR Address, ABHA number, Aadhaar number or Mobile number.

### Implementation Example

Add the following HTML and script tags to your webpage:

> [!NOTE]
>
> For staging/dev environments, replace the SDK URLs with:
>
> * **JS:** `https://unpkg.com/@eka-care/abha-stg/dist/sdk/abha/js/abha.js`
> * **CSS:** `https://unpkg.com/@eka-care/abha-stg/dist/sdk/abha/css/abha.css`

```html theme={null}
<!DOCTYPE html>
<html>
  <head>
    <title>ABHA SDK Integration</title>

    <!-- Include ABHA SDK CSS -->
    <link
      rel="stylesheet"
      href="https://unpkg.com/@eka-care/abha/dist/sdk/abha/css/abha.css"
    />
  </head>
  <body>
    <h1>ABHA SDK Demo</h1>

    <!-- Mount Button -->
    <button class="button" onclick="mountABHASDK()">Mount SDK</button>

    <!-- Container for ABHA SDK -->
    <div id="sdk_container"></div>

    <!-- Include ABHA SDK JS -->
    <script
      type="module"
      src="https://unpkg.com/@eka-care/abha/dist/sdk/abha/js/abha.js"
    ></script>

    <script>
      function mountABHASDK() {
        window.initAbhaApp({
          containerId: "sdk_container",
          clientId: 'ext',
        
         // Pass access token and oid
          data: {
            accessToken: "<your_access_token>", // Pass the access token you have
            oid: "<patient_oid>", // Pass OID of the patient
            hipId: "<available_HFR_ID>", // Pass the HFR ID you have
            orgIconUrl: "<url_of_your_org_logo>", // Pass the url of the logo of your organisation for ex https://cdn.eka.care/vagus/cl5jgf0u500070shaetqw0r5l.png
            linkToOrgIcon: "<url_of_image_to_link_abha_to_your_org>", // Pass the url of an image which depicts linking abha to your organisation for ex https://cdn.eka.care/vagus/cm6agrs5000090tfwfz984x5b.webp
            skipABHAEnable: "<boolean_value_here>" // Pass boolean as true if you want Skip ABHA button to be enabled on login screen
          },

          // Success callback
          onSuccess: (params) => {
            console.log("ABHA Registration flow completed successfully:", params);
            
            // Example: Store ABHA data in your app
            if (window.EkaAbha) {
              window.EkaAbha.onAbhaSuccess(JSON.stringify(params));
            }
          },

          // Error callback
          onError: (params) => {
            console.error("ABHA SDK failed:", params);

            // Example: Store ABHA data in your app
            if (window.EkaAbha) {
              window.EkaAbha.onAbhaFailure(JSON.stringify(params));
            }
          },

          // Abha Close callback
          onAbhaClose: () => {
            console.log("ABHA SDK closed");
          },

          // Skip ABHA callback
          onSkipAbha: (params) => {
            console.log("ABHA flow SKIPPED:", params);
          },

        });
      }
    </script>
  </body>
</html>
```

## Core Functions

### 1. initAbhaApp

Initializes and renders the ABHA SDK in your specified container.

**Parameters:**

| Name | Type | Required | Description | |
| - | - | - | - | - |
| `containerId` | `string` | | The HTML element ID where the SDK will mount. | |
| `clientId` | `string` | | Provide clientId as `ext`. | |
| `data` | `{` `accessToken: string;` `oid?: string;` `hipId?: string;` `orgIconUrl?: string;` `linkToOrgIcon?: string;` `skipABHAEnable?: boolean;` `}` |  Optional | Configuration data for initializing the ABHA flow.  - **accessToken:** Pass the access token you have generated from [Connect Login ](https://developer.eka.care/api-sdk/auth/client-login) API without the word `Bearer`. - **oid:** Pass the OID of the patient if available. - **hipId:** Pass the HFR ID you have. - **orgIconUrl:** Public CDN URL of the logo of your organisation url should start with https\://. [Example](https://cdn.eka.care/vagus/cl5jgf0u500070shaetqw0r5l.png) - **linkToOrgIcon:** Public CDN URL of the icon representing “Link ABHA to your organisation” url should start with https\://. [Example](https://cdn.eka.care/vagus/cm6agrs5000090tfwfz984x5b.webp) - **skipABHAEnable:** Pass the boolean as true if you want Skip ABHA button to be enabled on login screen.  `keys with ? are optional.` | |
| `onSuccess` | `(params: TOnAbhaSuccessParams) => void` | | Triggered when the user successfully creates or logs in to ABHA. | |
| `onError` | `(params: TOnAbhaFailureParams) => void` | | Triggered when an error occurs during the ABHA flow. | |
| `onAbhaClose` | `() => void` | | Triggered when SDK closes. | |
| `onSkipAbha` | `(params: TOnSkipABHA) => void` |  Optional | Triggered if the ABHA flow is skipped. | |

**Example:**

```javascript theme={null}
window.initAbhaApp({
  containerId: "sdk_container",
  data: {
    accessToken: "your_access_token_here",
    oid: "patient_oid_here",
    hipId: "available HFR ID",
    linkToOrgIcon: "url_of_image_to_link_abha_to_your_org",
    skipABHAEnable: "boolean_value_here"
  },
  onSuccess: (params) => {
    console.log("ABHA created successfully!", params);
  },
  onError: (error) => {
    console.error("ABHA flow failed:", error);
  },
  onAbhaClose: (error) => {
    console.error("ABHA SDK closed");
  },
  onSkipAbha: (params) => {
    console.log("ABHA flow skipped by user:", params);
  },

});
```

## Callback Parameters

### onSuccess Callback

The onSuccess callback is triggered when the ABHA flow completes successfully.
It returns verified user details and tokens, which can be used to log in or continue the user’s session.

**Callback Signature:**

```typescript theme={null}
onSuccess: (params: TOnAbhaSuccessParams) => void;
```

**Type Definitions**

```typescript theme={null}
type TOnAbhaSuccessParams = {
  response: TAuthVerifyV2Response;
};

type TAuthVerifyV2Response = {
  skip_state: number;
  method: AUTH_METHOD;
  data?: {
    tokens: {
      sess: string;
      refresh: string;
    };
    profile: TProfileRecord;
  };
  txn_id: string;
  error?: {
    code: number;
    message: string;
  };
};

enum AUTH_METHOD {
  EMAIL = 1,
  MOBILE = 2,
  ABHA = 7,
}

type TProfileRecord = {
  fln: string;
  fn: string;
  mn?: string;
  ln?: string;
  gen?: "M" | "F" | "O" | "U" | undefined; // 'male' | 'female' | 'other' | 'unknown'
  dob?: string;
  mobile?: string;
  email?: string;
  uuid?: string;
  bloodgroup?: "" | "A+" | "A-" | "B+" | "B-" | "O+" | "O-" | "AB+" | "AB-";
  pic?: string;
  as?: string;
  "dob-valid"?: boolean;
  "is-d"?: boolean;
  "is-d-s"?: boolean;
  "is-p"?: boolean;
  oid: string;
  at: string;
  type?: 1 | 2 | 3 | 4 | 5 | 6;
  "health-ids"?: Array<string>;
  abha_number?: string;
  kyc_verified?: boolean;
};

```

**Parameters**

| Key | Type | Description |
| - | - | - |
| `response` | `TAuthVerifyV2Response` | The complete ABHA verification response, containing session tokens, user profile, and transaction details. |

**Example:**

```javascript theme={null}
const onSuccess = (params) => {
  console.log("ABHA Success:", params.response);

  const abhaNumber = params.response.data?.profile?.abha_number;
  const userName = params.response.data?.profile?.name;

  alert(`Welcome ${userName}! Your ABHA Number: ${abhaNumber}`);

  // Optionally pass data to native bridge if available
  if (window.EkaAbha) {
    window.EkaAbha.onAbhaSuccess(JSON.stringify(params));
  }
};
```

### onError Callback

The onError callback is triggered whenever an ABHA flow fails or is interrupted.
It provides details about the failure through structured parameters, allowing you to handle or forward the error appropriately (for example, to native apps or monitoring tools).

**Callback Signature:**

```typescript theme={null}
onError: (params: TOnAbhaFailureParams) => void;
```

**Type Definitions**

```typescript theme={null}
type TOnAbhaFailureParams = {
  error?: string;
  response?: TAuthVerifyV2Response;
};

type TAuthVerifyV2Response = {
  skip_state: number;
  method: AUTH_METHOD;
  data?: {
    tokens: {
      sess: string;
      refresh: string;
    };
    profile: TProfileRecord;
  };
  txn_id: string;
  error?: {
    code: number;
    message: string;
  };
};

enum AUTH_METHOD {
  EMAIL = 1,
  MOBILE = 2,
  ABHA = 7,
}

type TProfileRecord = {
  fln: string;
  fn: string;
  mn?: string;
  ln?: string;
  gen?: "M" | "F" | "O" | "U" | undefined; // 'male' | 'female' | 'other' | 'unknown'
  dob?: string;
  mobile?: string;
  email?: string;
  uuid?: string;
  bloodgroup?: "" | "A+" | "A-" | "B+" | "B-" | "O+" | "O-" | "AB+" | "AB-";
  pic?: string;
  as?: string;
  "dob-valid"?: boolean;
  "is-d"?: boolean;
  "is-d-s"?: boolean;
  "is-p"?: boolean;
  oid: string;
  at: string;
  type?: 1 | 2 | 3 | 4 | 5 | 6;
  "health-ids"?: Array<string>;
  abha_number?: string;
  kyc_verified?: boolean;
};

```

**Parameters**

| Key | Type | Description |
| - | - | - |
| `error` | `string?` | Short description of the failure or error message. |
| `response` | `TAuthVerifyV2Response?` | Partial or full API response object returned from ABHA services. |

**Example:**

```javascript theme={null}
const onError = (params) => {
  console.error("ABHA Error:", params);

  if (params.response?.error?.code === 1001) {
    alert("Authentication failed. Please try again.");
  } else if (params.error === "NETWORK_ERROR") {
    alert("Please check your internet connection.");
  } else {
    alert("Something went wrong. Please retry.");
  }

  // Forward the error to native handler if available
  if (window.EkaAbha) {
    window.EkaAbha.onAbhaFailure(JSON.stringify(params));
  }
};
```

### onAbhaClose Callback

The onAbhaClose callback is triggered when the ABHA SDK flow gets closed.

**Callback Signature:**

```typescript theme={null}
onAbhaClose: () => void;
```

**Example:**

```javascript theme={null}
const onAbhaClose = () => {
  console.log("ABHA SDK Closed");
};
```

### onSkipAbha Callback

The onSkipAbha callback is triggered when the ABHA SDK flow is skipped. The callback is functional when skipABHAEnable is set to true in the data parameter while initializing the SDK.

**Callback Signature:**

```typescript theme={null}
onSkipAbha: (params: TOnSkipABHA) => void;
```

**Example:**

```javascript theme={null}
const onSkipAbha = (params) => {
  console.log("ABHA SDK Skipped:", params);
};
```

**Type Definitions**

```typescript theme={null}
 type IdentifierType = "mobile" | "aadhaar_number" | "abha_number" | "phr_address";

 type TOnSkipABHA = {
  identifier?: string;
  identifier_type?: IdentifierType[]; // No default value here
};
```

**Parameters**

| Key | Type | Description |
| - | - | - |
| `identifier` | `string?` | It will be login identifier value filled by user. |
| `identifier_type` | `IdentifierType[]?` | It will be type of login identifier. |

**Suggest Handling**

* Always log the full error response (params) for debugging.
* Display friendly error messages for known error.code values.
* If params.response is present, inspect response.error.message for more detail.
* If integrating with native apps, forward the serialized error object:

```javascript theme={null}
window.EkaAbha.onAbhaFailure(JSON.stringify(params));
```

## Container Styling

Ensure your container has sufficient space:

```html theme={null}
<div
  id="sdk_container"
  style="width: 100%; height: 600px; border: 1px solid #ddd;"
></div>
```

## Troubleshooting

### Common Issues

#### 1. SDK Not Rendering

**Problem**: Nothing appears in the container.

**Solution**:

* Ensure containerId matches an existing HTML element.
* Verify the SDK JS and CSS are correctly loaded.
* Check browser console for errors.

#### 2. APIs Not Being Called

**Problem**: API requests are not triggered after the SDK is mounted.

**Solution**:

* Ensure that the accessToken is passed correctly (do not include the Bearer prefix) and that the token has not expired.
* To prevent CORS-related issues, ensure that your domain is whitelisted.

#### 3. Callback Not Triggered

**Problem**: onSuccess, onError, onKYCSuccess, onConsentSuccess, onAbhaClose isn’t firing.

**Solution**:

* Make sure callbacks are passed as valid functions.
* Avoid race conditions (e.g., calling before SDK fully loads).

#### 4. Styling Issues

**Problem**: SDK content appears misaligned or clipped.

**Solution**:

* Give your container a fixed height (e.g., 600px).
* Ensure no parent element uses overflow: hidden.


# Scan & Share
Source: https://developer.eka.care/api-sdk/hie-cm/sdks/web-sdk/abha-sdk/abha-s&s

Complete implementation guide for the ABHA SDK to be used for ABHA Scan & Share Book Appointment Flow.

# ABHA SDK - Scan & Share Implementation

This guide provides everything you need to integrate the ABHA SDK into your application for ABHA Scan & Share Book Appointment Flow.

* **ABHA Scan & Share**: Get your Appointments Booked through ABHA.

### Implementation Example

Add the following HTML and script tags to your webpage:

> [!NOTE]
>
> For staging/dev environments, replace the SDK URLs with:
>
> * **JS:** `https://unpkg.com/@eka-care/abha-stg/dist/sdk/abha/js/abha.js`
> * **CSS:** `https://unpkg.com/@eka-care/abha-stg/dist/sdk/abha/css/abha.css`

```html theme={null}
<!DOCTYPE html>
<html>
  <head>
    <title>ABHA SDK Integration for ABHA Scan & Share</title>

    <!-- Include ABHA SDK CSS -->
    <link
      rel="stylesheet"
      href="https://unpkg.com/@eka-care/abha/dist/sdk/abha/css/abha.css"
    />
  </head>
  <body>
    <h1>ABHA SDK Demo</h1>

    <!-- Mount Button -->
    <button class="button" onclick="mountABHASDK()">Mount SDK</button>

    <!-- Container for ABHA SDK -->
    <div id="sdk_container"></div>

    <!-- Include ABHA SDK JS -->
    <script
      type="module"
      src="https://unpkg.com/@eka-care/abha/dist/sdk/abha/js/abha.js"
    ></script>

    <script>
      function mountABHASDK() {
        window.initAbhaApp({
          containerId: "sdk_container",
          clientId: 'ext',

         // Pass the data here:
          data: {
             oid: "<patient_oid>", // Pass OID of the patient
             hipId: "<available_HFR_ID>", // Pass the HFR ID you have
             counter_id: "<available_HIP_code>" // Pass the facility HIP code
             identifier:'<phr_address_of_the_patient>', // Pass the phr address as identifier of the patient
             identifier_type:"phr_address",  // Pass the identifier type i.e. "phr_address"
             flow:'scan-share', // Pass the flow as scan-share
             orgIconUrl: "<url_of_your_org_logo>", // Pass the url of the logo of your organisation for ex https://cdn.eka.care/vagus/cl5jgf0u500070shaetqw0r5l.png
             linkToOrgIcon: "<url_of_image_to_link_abha_to_your_org>", // Pass the url of an image which depicts linking abha to your organisation for ex https://cdn.eka.care/vagus/cm6agrs5000090tfwfz984x5b.webp
          },

          // Scan & Share Success callback
          onAppointmentBookedSuccess: (params) => {
            console.log("Appointment Booked successfully:", params);

            // Example: Store ABHA data in your app
            if (window.EkaAbha) {
              window.EkaAbha.onAppointmentBookedSuccess(JSON.stringify(params));
            }
          },

          // Error callback
          onError: (params) => {
            console.error("ABHA SDK failed:", params);

            // Example: Store ABHA data in your app
            if (window.EkaAbha) {
              window.EkaAbha.onAbhaFailure(JSON.stringify(params));
            }
          },

          // Abha Close callback
          onAbhaClose: () => {
            console.log("ABHA SDK closed");
          },

        });
      }
    </script>
  </body>
</html>
```

## Core Functions

### 1. initAbhaApp

Initializes and renders the ABHA SDK in your specified container.

**Parameters:**

| Name | Type | Required | Description |
| - | - | - | - |
| `containerId` | `string` | | The HTML element ID where the SDK will mount. |
| `clientId` | `string` | | Provide clientId as `ext`. |
| `data` | `{` `oid?: string;` `hipId?: string;` `counter_id?: string;` `orgIconUrl?: string;` `linkToOrgIcon?: string;` `identifier: string;` `identifier_type: string;` `flow: string;` `orgIconUrl?: string;` `linkToOrgIcon?: string; ` `}` | | Configuration data for initializing the ABHA flow.  - **oid:** Pass the OID of the patient if available. - **hipId:** Pass the HFR ID you have. - **counter\_id:** Pass the HIP code of the facility you have. - **identifier:** Pass the identifier value i.e. phr address of the patient. - **identifier\_type:** Pass the type of identifier which you passed in `identifier` key i.e. "phr\_address". - **flow:** Pass the type of flow for which you want to use SDK for i.e. `scan-share` for Scan & Share Flow. - **orgIconUrl:** Public CDN URL of the logo of your organisation url should start with https\://. [Example](https://cdn.eka.care/vagus/cl5jgf0u500070shaetqw0r5l.png) - **linkToOrgIcon:** Public CDN URL of the icon representing “Link ABHA to your organisation” url should start with https\://. [Example](https://cdn.eka.care/vagus/cm6agrs5000090tfwfz984x5b.webp)   `keys with ? are optional.` |
| `onAppointmentBookedSuccess` | `(params: TOnAbhaSnSAppointmentSuccessParams) => void` | | Triggered when the Appointment is booked and token gets generated successfully. |
| `onError` | `(params: TOnAbhaFailureParams) => void` | | Triggered when an error occurs during the ABHA flow. |
| `onAbhaClose` | `() => void` | | Triggered when SDK closes. |

**Example:**

```javascript theme={null}
window.initAbhaApp({
  containerId: "sdk_container",
  data: {
    oid: "patient_oid_here",
    hipId: "available_HFR_ID",
    counter_id: "available_HIP_code"
    identifier: "phr_address_of_the_patient"
    identifier_type: "phr_address"
    flow:'scan-share', // Pass the flow as scan-share
  },
  onAppointmentBookedSuccess: (params) => {
    console.log("Appointment Booked successfully!", params);
  },
  onError: (error) => {
    console.error("ABHA flow failed:", error);
  },
  onAbhaClose: (error) => {
    console.error("ABHA SDK closed");
  },
});
```

## Callback Parameters

### onAppointmentBookedSuccess Callback

The onAppointmentBookedSuccess callback is triggered when the appointment is booked and token gets generated successfully.
It returns a confirmation message indicating that the Appointment is booked.

**Callback Signature:**

```typescript theme={null}
onAppointmentBookedSuccess: (params: TOnAbhaSnSAppointmentSuccessParams) => void;
```

**Type Definitions**

```typescript theme={null}
type TOnAbhaSnSAppointmentSuccess = string;
```

**Parameters**

| | Type | Description |
| - | - | - |
| `onAppointmentBookedSuccess` | `string` | A confirmation message from SDK post Appointment Token generation |

**Example:**

```javascript theme={null}
const onAppointmentBookedSuccess = (params) => {
  console.log("Appointment Booked successfully!:", params);

  alert("Appointment Booked successfully!");

  // Optionally pass data to native bridge if available
  if (window.EkaAbha) {
    window.EkaAbha.onAppointmentBookedSuccess(params);
  }
};
```

### onError Callback

The onError callback is triggered whenever an ABHA flow fails or is interrupted.
It provides details about the failure through structured parameters, allowing you to handle or forward the error appropriately (for example, to native apps or monitoring tools).

**Callback Signature:**

```typescript theme={null}
onError: (params: TOnAbhaFailureParams) => void;
```

**Type Definitions**

```typescript theme={null}
type TOnAbhaFailureParams = {
  error?: string;
  response?: TAuthVerifyV2Response;
};

type TAuthVerifyV2Response = {
  skip_state: number;
  method: AUTH_METHOD;
  data?: {
    tokens: {
      sess: string;
      refresh: string;
    };
    profile: TProfileRecord;
  };
  txn_id: string;
  error?: {
    code: number;
    message: string;
  };
};

enum AUTH_METHOD {
  EMAIL = 1,
  MOBILE = 2,
  ABHA = 7,
}

type TProfileRecord = {
  fln: string;
  fn: string;
  mn?: string;
  ln?: string;
  gen?: "M" | "F" | "O" | "U" | undefined; // 'male' | 'female' | 'other' | 'unknown'
  dob?: string;
  mobile?: string;
  email?: string;
  uuid?: string;
  bloodgroup?: "" | "A+" | "A-" | "B+" | "B-" | "O+" | "O-" | "AB+" | "AB-";
  pic?: string;
  as?: string;
  "dob-valid"?: boolean;
  "is-d"?: boolean;
  "is-d-s"?: boolean;
  "is-p"?: boolean;
  oid: string;
  at: string;
  type?: 1 | 2 | 3 | 4 | 5 | 6;
  "health-ids"?: Array<string>;
  abha_number?: string;
  kyc_verified?: boolean;
};
```

**Parameters**

| Key | Type | Description |
| - | - | - |
| `error` | `string?` | Short description of the failure or error message. |
| `response` | `TAuthVerifyV2Response?` | Partial or full API response object returned from ABHA services. |

**Example:**

```javascript theme={null}
const onError = (params) => {
  console.error("ABHA Error:", params);

  if (params.response?.error?.code === 1001) {
    alert("Authentication failed. Please try again.");
  } else if (params.error === "NETWORK_ERROR") {
    alert("Please check your internet connection.");
  } else {
    alert("Something went wrong. Please retry.");
  }

  // Forward the error to native handler if available
  if (window.EkaAbha) {
    window.EkaAbha.onAbhaFailure(JSON.stringify(params));
  }
};
```

### onAbhaClose Callback

The onAbhaClose callback is triggered when the ABHA SDK flow gets closed.

**Callback Signature:**

```typescript theme={null}
onAbhaClose: () => void;
```

**Example:**

```javascript theme={null}
const onAbhaClose = () => {
  console.log("ABHA SDK Closed");
};
```

**Suggest Handling**

* Always log the full error response (params) for debugging.
* Display friendly error messages for known error.code values.
* If params.response is present, inspect response.error.message for more detail.
* If integrating with native apps, forward the serialized error object:

```javascript theme={null}
window.EkaAbha.onAbhaFailure(JSON.stringify(params));
```

## Container Styling

Ensure your container has sufficient space:

```html theme={null}
<div
  id="sdk_container"
  style="width: 100%; height: 600px; border: 1px solid #ddd;"
></div>
```

## Troubleshooting

### Common Issues

#### 1. SDK Not Rendering

**Problem**: Nothing appears in the container.

**Solution**:

* Ensure containerId matches an existing HTML element.
* Verify the SDK JS and CSS are correctly loaded.
* Check browser console for errors.

#### 2. APIs Not Being Called

**Problem**: API requests are not triggered after the SDK is mounted.

**Solution**:

* Ensure that the accessToken is passed correctly (do not include the Bearer prefix) and that the token has not expired.
* To prevent CORS-related issues, ensure that your domain is whitelisted.

#### 3. Callback Not Triggered

**Problem**: onSuccess, onError, onAppointmentBookedSuccess, onAbhaClose isn’t firing.

**Solution**:

* Make sure callbacks are passed as valid functions.
* Avoid race conditions (e.g., calling before SDK fully loads).

#### 4. Styling Issues

**Problem**: SDK content appears misaligned or clipped.

**Solution**:

* Give your container a fixed height (e.g., 600px).
* Ensure no parent element uses overflow: hidden.


# Custom Theming
Source: https://developer.eka.care/api-sdk/hie-cm/sdks/web-sdk/abha-sdk/abha-sdk-theme

Customize the ABHA SDK colors to match your application's branding

# ABHA SDK - Customizing the Theme

The ABHA SDK supports full color-token overriding. You can pass a `theme` object during initialization to match your application's branding.

## Passing theme to initAbhaApp

The `theme` parameter is an optional key in `initAbhaApp`. Pass it alongside your other configuration:

| Name | Type | Required | Description |
| - | - | - | - |
| `theme` | `object` |  Optional | Color token overrides to match your organisation's design system. All keys are optional — only supply the tokens you want to change. |

```javascript theme={null}
window.initAbhaApp({
  containerId: "sdk_container",
  clientId: "ext",
  theme: {
    // pass only the tokens you want to override
  },
  data: { /* ... */ },
  onSuccess: (params) => { /* ... */ },
  onError: (params) => { /* ... */ },
});
```

## Default Theme Colors

If no theme is provided, the SDK uses the following default values:

```typescript theme={null}
const defaultAbhaColors = {
  semantic: {
    error: '#BD0F0F',
    warning: '#FCB069',
    success: '#27B961',
  },
  primary: {
    brand: '#6B5CE0', // Main buttons, radios, and active states
  },
  surface: {
    base: '#FFFFFF',      // Background of pages
    subtle: '#F2F4F7',    // Card backgrounds
    muted: '#E4E7EC',     // Dividers and borders
    strong: '#BEC5D0',
    success: '#D5F6E2',   // Success background alerts
    neutral: '#0000000D',
    danger: '#DD3F3F',
    abhaCard: '#232477',  // Specific background for the ABHA ID card
  },
  content: {
    primary: '#111B31',   // Heading and main text
    secondary: '#4B596D', // Subtext
    muted: '#9EA8B8',     // Disabled or placeholder text
    success: '#1B7E43',   // Success text
    enabled: '#ffffff',   // Enabled button text color
  },
  qrCodeColors: {
    fgColor: '#000000',   // Color of the QR code dots
    bgColor: '#FFFFFF'    // Background of the QR code
  }
};
```

## Overriding the Theme

To customize the look, add the `theme` key to your `initAbhaApp` configuration:

```typescript theme={null}
window.initAbhaApp({
  containerId: "sdk_container",
  clientId: "ext",
  theme: {
    primary: {
      brand: '<your_org_primary_color>',    // Brand color
    },
    semantic: {
      error: '<your_semantic_error_color>',
      warning: '<your_semantic_warning_color>',
      success: '<your_semantic_success_color>',
    },
    surface: {
      base: '<your_base_color>',            // Background of pages
      subtle: '<your_subtle_color>',        // Card backgrounds
      muted: '<your_muted_color>',          // Dividers and borders
      strong: '<your_strong_color>',
      success: '<your_success_color>',      // Success background alerts
      neutral: '<your_neutral_color>',
      danger: '<your_danger_color>',
      abhaCard: '<your_abhaCard_color>',    // Specific background for the ABHA ID card
    },
    content: {
      primary: '<your_content_primary_color>',     // Heading and main text
      secondary: '<your_content_secondary_color>', // Subtext
      muted: '<your_content_muted_color>',         // Disabled or placeholder text
      success: '<your_content_success_color>',     // Success text
      enabled: '<enabled_button_text_color>',      // Enabled button text color
    },
    qrCodeColors: {
      fgColor: '<your_qrcode_dot_color>',  // Color of the QR code dots
      bgColor: '<your_qrcode_bg_color>'    // Background of the QR code
    }
  },
  data: {
    orgIconUrl: "https://your-domain.com/logo.png",
    // ... rest of your data
  },
  onSuccess: (params) => { /* ... */ },
  onError: (params) => { /* ... */ },
  // ... other methods
});
```

## Troubleshooting

### Common Theming Issues

#### 1. Button Not Visible or Hard to See

**Problem**: A button appears invisible, blends into the background, or is difficult to read.

**Cause**: This typically happens when `primary.brand` and `content.enabled` are too similar (e.g., both set to white or both dark), making the button label invisible against its background.

**Solution**:

* Ensure `primary.brand` (button background) and `content.enabled` (button text) have sufficient contrast.
* A dark `primary.brand` should pair with a light `content.enabled` (e.g., `#ffffff`), and vice versa.

```typescript theme={null}
theme: {
  primary: {
    brand: ‘#1A237E’,   // Dark button background
  },
  content: {
    enabled: ‘#FFFFFF’, // Light text on button — must contrast with brand
  },
}
```

#### 2. Color Discrepancy — Overrides Not Taking Effect

**Problem**: You passed a theme but some colors still appear as defaults.

**Cause**: Token keys may be misspelled, nested incorrectly, or using the wrong casing.

**Solution**:

* Double-check that your token keys exactly match the structure in [Default Theme Colors](#default-theme-colors). The SDK performs a shallow merge — missing or misnamed keys fall back to defaults silently.
* Verify nesting: tokens like `surface.base` must be passed as `surface: { base: ‘...’ }`, not as a flat key.

```typescript theme={null}
// ❌ Wrong — flat key, will be ignored
theme: {
  ‘surface.base’: ‘#F9FAFB’,
}

// ✅ Correct — nested object
theme: {
  surface: {
    base: ‘#F9FAFB’,
  },
}
```

#### 3. Success / Error States Look Off

**Problem**: Success alerts, error messages, or validation states are visually inconsistent or unreadable.

**Cause**: Overriding only `semantic.success` without also updating `surface.success` and `content.success` (or vice versa) breaks the foreground/background pairing for state banners.

**Solution**: Always override semantic state colors as a group — the background surface token, the text content token, and the semantic indicator token together.

| State | Tokens to keep in sync |
| - | - |
| Success | `semantic.success`, `surface.success`, `content.success` |
| Error | `semantic.error`, `surface.danger` |
| Warning | `semantic.warning` |

#### 4. ABHA Card Color Not Changing

**Problem**: The ABHA ID card background color is not updating despite passing a theme.

**Solution**: The card background is controlled by `surface.abhaCard`, not `surface.base` or `primary.brand`. Pass it explicitly:

```typescript theme={null}
theme: {
  surface: {
    abhaCard: ‘#1A237E’, // Override the ABHA card background
  },
}
```

#### 5. QR Code Invisible or Unreadable

**Problem**: The QR code is not scannable or appears blank.

**Cause**: `qrCodeColors.fgColor` and `qrCodeColors.bgColor` may have been set to the same or similar colors.

**Solution**: Maintain high contrast between the QR dot color and background — black on white is the most reliable combination for scanner compatibility.

```typescript theme={null}
theme: {
  qrCodeColors: {
    fgColor: ‘#000000’, // QR dots — keep dark
    bgColor: ‘#FFFFFF’, // QR background — keep light
  },
}
```


# Get Started
Source: https://developer.eka.care/api-sdk/hie-cm/sdks/web-sdk/abha-sdk/get-started

Complete implementation guide for the ABHA[Ayushman Bharat Digital Mission] SDK

# ABHA SDK - Implementation

This guide provides everything you need to integrate the ABHA SDK into your application.

## Overview

The ABHA SDK allows you to integrate flows—such as Create ABHA, Login, Profile KYC, Consent Management, and Scan & Share—into your healthcare application, while offering customizable theme options. It provides:

* **Create ABHA**: Create a new ABHA using Mobile or Aadhaar.
* **Login with ABHA**: Login to your exisiting ABHA using PHR Address, ABHA number, Aadhaar number or Mobile number.
* **ABHA Consent Management**: Manage Consent requests raised by healthcare providers to share medical records securely.
* **ABHA Profile KYC**: Get your ABHA address KYC verified.
* **ABHA Scan & Share**: Get your Appointments Booked through ABHA.
* **Customizing the Theme**: Customize the ABHA SDK colors to match your application's branding.

## Installation

### Prerequisites

* A modern web browser.
* Your domain must be whitelisted with Eka Care to avoid CORS(Cross-Origin Resource Sharing) error.
  (Contact Eka Care to request API access and domain whitelisting.)
* A valid HTML container element where the SDK will mount.

### Setup

Add the following HTML and script tags to your webpage:

> [!NOTE]
>
> For staging/dev environments, replace the SDK URLs with:
>
> * **JS:** `https://unpkg.com/@eka-care/abha-stg/dist/sdk/abha/js/abha.js`
> * **CSS:** `https://unpkg.com/@eka-care/abha-stg/dist/sdk/abha/css/abha.css`

```html theme={null}
<!DOCTYPE html>
<html>
  <head>
    <title>ABHA SDK Integration</title>

    <!-- Include ABHA SDK CSS -->
    <link
      rel="stylesheet"
      href="https://unpkg.com/@eka-care/abha/dist/sdk/abha/css/abha.css"
    />
  </head>
  <body>
    <h1>ABHA SDK Demo</h1>

    <!-- Mount Button -->
    <button class="button" onclick="mountABHASDK()">Mount SDK</button>

    <!-- Container for ABHA SDK -->
    <div id="sdk_container"></div>

    <!-- Include ABHA SDK JS -->
    <script
      type="module"
      src="https://unpkg.com/@eka-care/abha/dist/sdk/abha/js/abha.js"
    ></script>

    <script>
      function mountABHASDK() {
        window.initAbhaApp({
          containerId: "sdk_container",
          clientId: "ext",

          // theme object
          theme: {
            // pass only the tokens you want to override
          },

          // data object
          data: {
            // pass the required data as per the flow
          },

          // Success callback
          onSuccess: (params) => {
            console.log(
              "ABHA Registration flow completed successfully:",
              params,
            );
          },

          //KYC Successs callback
          onKYCSuccess: (params) => {
            console.log("ABHA KYC Verified successfully:", params);
          },

          //Consent Successs callback
          onConsentSuccess: (params) => {
            console.log("ABHA Consent flow completed successfully:", params);
          },

          // Scan & Share Success callback
          onAppointmentBookedSuccess: (params) => {
            console.log("Appointment Booked successfully:", params);
          },

          // Skip ABHA callback
          onSkipAbha: (params) => {
            console.log("ABHA flow SKIPPED:", params);
          },

          // Abha Close callback
          onAbhaClose: () => {
            console.log("ABHA SDK closed");
          },

          // Error callback
          onError: (params) => {
            console.error("ABHA SDK failed:", params);
          },
        });
      }
    </script>
  </body>
</html>
```

## Core Functions

### 1. initAbhaApp

Initializes and renders the ABHA SDK in your specified container.

**Parameters:**

| Name | Type | Required | Description |
| - | - | - | - |
| `containerId` | `string` | | The HTML element ID where the SDK will mount. |
| `clientId` | `string` | | Provide clientId as `ext`. |
| `data` | `{` `accessToken: string;` `hipId: string;` `oid?: string;` `identifier?: string;` `identifier_type?: string;` `counter_id?: string;` `consent_id?: string;` `flow?: string;` `orgIconUrl?: string;` `linkToOrgIcon?: string;` `skipABHAEnable?: boolean;` `}` |  Optional | Configuration data for initializing the ABHA flow.  - **accessToken:** Pass the access token you have generated from [Connect Login ](https://developer.eka.care/api-sdk/auth/client-login) API without the word `Bearer`. - **hipId:** Pass the HFR ID you have. - **oid:** Pass oid of patient if available / needed in the flow. - **identifier:** Pass the login identifier value i.e. mobile number / aadhaar number / phr address / abha number. - **identifier\_type:** Pass the type of identifier which you passed in `identifier` key i.e. "mobile" / "aadhaar\_number" / "phr\_address" / "abha\_number" /. If not known pass undefined. - **counter\_id:** Pass the HIP code of the facility you have. - **consent\_id:** Pass the consent\_id of the consent request raised. - **flow:** Pass the type of flow for which you want to use SDK for i.e. `abha-kyc` for KYC flow / `consent` for Consent flow. - **orgIconUrl:** Public CDN URL of the logo of your organisation url should start with https\://. [Example](https://cdn.eka.care/vagus/cl5jgf0u500070shaetqw0r5l.png) - **linkToOrgIcon:** Public CDN URL of the icon representing “Link ABHA to your organisation” url should start with https\://. [Example](https://cdn.eka.care/vagus/cm6agrs5000090tfwfz984x5b.webp) - **skipABHAEnable:** Pass the boolean as true if you want Skip ABHA button to be enabled on login screen.   `keys with ? are optional and needs to be passed as per flow requirement.` |
| `theme` | `object` |  Optional | Color token overrides to match your organisation's design system. All keys are optional — only supply the tokens you want to change. [Refer here](https://developer.eka.care/api-sdk/hie-cm/sdks/web-sdk/abha-sdk/abha-sdk-theme) |
| `onSuccess` | `(params: TOnAbhaSuccessParams) => void` | | Triggered when the user successfully creates or logs in to ABHA. |
| `onKYCSuccess` | `(params: TOnAbhaKycSuccessParams) => void` |  Optional | Triggered when the user KYC verified successfully. |
| `onConsentSuccess` | `(params: TOnAbhaConsentSuccessParams) => void` |  Optional | Triggered when the consent flow completes successfully. |
| `onAppointmentBookedSuccess` | `(params: TOnAbhaSnSAppointmentSuccessParams) => void` | | Triggered when the Appointment is booked and token gets generated successfully. |
| `onSkipAbha` | `(params: TOnSkipABHA) => void` |  Optional | Triggered if the ABHA flow is skipped. |
| `onAbhaClose` | `() => void` | | Triggered when SDK closes. |
| `onError` | `(params: TOnAbhaFailureParams) => void` | | Triggered when an error occurs during the ABHA flow. |

## Callback Parameters

### onSuccess Callback

The onSuccess callback is triggered when the ABHA flow completes successfully.
It returns verified user details and tokens, which can be used to log in or continue the user’s session.

**Callback Signature:**

```typescript theme={null}
onSuccess: (params: TOnAbhaSuccessParams) => void;
```

**Type Definitions**

```typescript theme={null}
type TOnAbhaSuccessParams = {
  response: TAuthVerifyV2Response;
};

type TAuthVerifyV2Response = {
  skip_state: number;
  method: AUTH_METHOD;
  data?: {
    tokens: {
      sess: string;
      refresh: string;
    };
    profile: TProfileRecord;
  };
  txn_id: string;
  error?: {
    code: number;
    message: string;
  };
};

enum AUTH_METHOD {
  EMAIL = 1,
  MOBILE = 2,
  ABHA = 7,
}

type TProfileRecord = {
  fln: string;
  fn: string;
  mn?: string;
  ln?: string;
  gen?: "M" | "F" | "O" | "U" | undefined; // 'male' | 'female' | 'other' | 'unknown'
  dob?: string;
  mobile?: string;
  email?: string;
  uuid?: string;
  bloodgroup?: "" | "A+" | "A-" | "B+" | "B-" | "O+" | "O-" | "AB+" | "AB-";
  pic?: string;
  as?: string;
  "dob-valid"?: boolean;
  "is-d"?: boolean;
  "is-d-s"?: boolean;
  "is-p"?: boolean;
  oid: string;
  at: string;
  type?: 1 | 2 | 3 | 4 | 5 | 6;
  "health-ids"?: Array<string>;
  abha_number?: string;
  kyc_verified?: boolean;
};
```

**Parameters**

| Key | Type | Description |
| - | - | - |
| `response` | `TAuthVerifyV2Response` | The complete ABHA verification response, containing session tokens, user profile, and transaction details. |

**Example:**

```javascript theme={null}
const onSuccess = (params) => {
  console.log("ABHA Success:", params.response);

  const abhaNumber = params.response.data?.profile?.abha_number;
  const userName = params.response.data?.profile?.name;

  alert(`Welcome ${userName}! Your ABHA Number: ${abhaNumber}`);

  // Optionally pass data to native bridge if available
  if (window.EkaAbha) {
    window.EkaAbha.onAbhaSuccess(JSON.stringify(params));
  }
};
```

### onKYCSuccess Callback

The onKYCSuccess callback is triggered when the ABHA KYC flow completes successfully.
It returns a confirmation message indicating that the KYC has been verified.

**Callback Signature:**

```typescript theme={null}
onKYCSuccess: (params: TOnAbhaKycSuccessParams) => void;
```

**Type Definitions**

```typescript theme={null}
type TOnAbhaKycSuccess = string;
```

**Parameters**

| | Type | Description |
| - | - | - |
| `TOnAbhaKycSuccess` | `string` | A confirmation message from SDK post KYC verification |

**Example:**

```javascript theme={null}
const onKYCSuccess = (params) => {
  console.log("KYC verification Success:", params);

  alert("KYC was verified successfully!");

  // Optionally pass data to native bridge if available
  if (window.EkaAbha) {
    window.EkaAbha.onAbhaKYCSuccess(params);
  }
};
```

### onConsentSuccess Callback

The onConsentSuccess callback is triggered when the ABHA Consent flow completes successfully.
It returns a confirmation message indicating that the Consent flow ended successfully.

**Callback Signature:**

```typescript theme={null}
onConsentSuccess: (params: TOnAbhaConsentSuccessParams) => void;
```

**Type Definitions**

```typescript theme={null}
type TOnAbhaConsentSuccessParams = string;
```

**Parameters**

| | Type | Description |
| - | - | - |
| `TOnAbhaConsentSuccessParams` | `string` | A confirmation message from SDK post Consent flow completion |

**Example:**

```javascript theme={null}
const onConsentSuccess = (params) => {
  console.log("Consent Flow completed:", params);

  alert("Consent flow completed successfully!");

  // Optionally pass data to native bridge if available
  if (window.EkaAbha) {
    window.EkaAbha.onAbhaConsentSuccess(params);
  }
};
```

### onAppointmentBookedSuccess Callback

The onAppointmentBookedSuccess callback is triggered when the appointment is booked and token gets generated successfully.
It returns a confirmation message indicating that the Appointment is booked.

**Callback Signature:**

```typescript theme={null}
onAppointmentBookedSuccess: (params: TOnAbhaSnSAppointmentSuccessParams) => void;
```

**Type Definitions**

```typescript theme={null}
type TOnAbhaSnSAppointmentSuccess = string;
```

**Parameters**

| | Type | Description |
| - | - | - |
| `onAppointmentBookedSuccess` | `string` | A confirmation message from SDK post Appointment Token generation |

**Example:**

```javascript theme={null}
const onAppointmentBookedSuccess = (params) => {
  console.log("Appointment Booked successfully!:", params);

  alert("Appointment Booked successfully!");

  // Optionally pass data to native bridge if available
  if (window.EkaAbha) {
    window.EkaAbha.onAppointmentBookedSuccess(params);
  }
};
```

### onSkipAbha Callback

The onSkipAbha callback is triggered when the ABHA SDK flow is skipped. The callback is functional when skipABHAEnable is set to true in the data parameter while initializing the SDK.

**Callback Signature:**

```typescript theme={null}
onSkipAbha: (params: TOnSkipABHA) => void;
```

**Example:**

```javascript theme={null}
const onSkipAbha = (params) => {
  console.log("ABHA SDK Skipped:", params);
};
```

**Type Definitions**

```typescript theme={null}
type IdentifierType =
  | "mobile"
  | "aadhaar_number"
  | "abha_number"
  | "phr_address";

type TOnSkipABHA = {
  identifier?: string;
  identifier_type?: IdentifierType[]; // No default value here
};
```

**Parameters**

| Key | Type | Description |
| - | - | - |
| `identifier` | `string?` | It will be login identifier value filled by user. |
| `identifier_type` | `IdentifierType[]?` | It will be type of login identifier. |

### onAbhaClose Callback

The onAbhaClose callback is triggered when the ABHA SDK flow gets closed.

**Callback Signature:**

```typescript theme={null}
onAbhaClose: () => void;
```

**Example:**

```javascript theme={null}
const onAbhaClose = () => {
  console.log("ABHA SDK Closed");
};
```

### onError Callback

The onError callback is triggered whenever an ABHA flow fails or is interrupted.
It provides details about the failure through structured parameters, allowing you to handle or forward the error appropriately (for example, to native apps or monitoring tools).

**Callback Signature:**

```typescript theme={null}
onError: (params: TOnAbhaFailureParams) => void;
```

**Type Definitions**

```typescript theme={null}
type TOnAbhaFailureParams = {
  error?: string;
  response?: TAuthVerifyV2Response;
};

type TAuthVerifyV2Response = {
  skip_state: number;
  method: AUTH_METHOD;
  data?: {
    tokens: {
      sess: string;
      refresh: string;
    };
    profile: TProfileRecord;
  };
  txn_id: string;
  error?: {
    code: number;
    message: string;
  };
};

enum AUTH_METHOD {
  EMAIL = 1,
  MOBILE = 2,
  ABHA = 7,
}

type TProfileRecord = {
  fln: string;
  fn: string;
  mn?: string;
  ln?: string;
  gen?: "M" | "F" | "O" | "U" | undefined; // 'male' | 'female' | 'other' | 'unknown'
  dob?: string;
  mobile?: string;
  email?: string;
  uuid?: string;
  bloodgroup?: "" | "A+" | "A-" | "B+" | "B-" | "O+" | "O-" | "AB+" | "AB-";
  pic?: string;
  as?: string;
  "dob-valid"?: boolean;
  "is-d"?: boolean;
  "is-d-s"?: boolean;
  "is-p"?: boolean;
  oid: string;
  at: string;
  type?: 1 | 2 | 3 | 4 | 5 | 6;
  "health-ids"?: Array<string>;
  abha_number?: string;
  kyc_verified?: boolean;
};
```

**Parameters**

| Key | Type | Description |
| - | - | - |
| `error` | `string?` | Short description of the failure or error message. |
| `response` | `TAuthVerifyV2Response?` | Partial or full API response object returned from ABHA services. |

**Example:**

```javascript theme={null}
const onError = (params) => {
  console.error("ABHA Error:", params);

  if (params.response?.error?.code === 1001) {
    alert("Authentication failed. Please try again.");
  } else if (params.error === "NETWORK_ERROR") {
    alert("Please check your internet connection.");
  } else {
    alert("Something went wrong. Please retry.");
  }

  // Forward the error to native handler if available
  if (window.EkaAbha) {
    window.EkaAbha.onAbhaFailure(JSON.stringify(params));
  }
};
```

**Suggest Handling**

* Always log the full error response (params) for debugging.
* Display friendly error messages for known error.code values.
* If params.response is present, inspect response.error.message for more detail.
* If integrating with native apps, forward the serialized error object:

```javascript theme={null}
window.EkaAbha.onAbhaFailure(JSON.stringify(params));
```

## Container Styling

Ensure your container has sufficient space:

```html theme={null}
<div
  id="sdk_container"
  style="width: 100%; height: 600px; border: 1px solid #ddd;"
></div>
```

## Troubleshooting

### Common Issues

#### 1. SDK Not Rendering

**Problem**: Nothing appears in the container.

**Solution**:

* Ensure containerId matches an existing HTML element.
* Verify the SDK JS and CSS are correctly loaded.
* Check browser console for errors.

#### 2. APIs Not Being Called

**Problem**: API requests are not triggered after the SDK is mounted.

**Solution**:

* Ensure that the accessToken is passed correctly (do not include the Bearer prefix) and that the token has not expired.
* To prevent CORS-related issues, ensure that your domain is whitelisted.

#### 3. Callback Not Triggered

**Problem**: onSuccess, onError, onKYCSuccess, onConsentSuccess, onAbhaClose isn’t firing.

**Solution**:

* Make sure callbacks are passed as valid functions.
* Avoid race conditions (e.g., calling before SDK fully loads).

#### 4. Styling Issues

**Problem**: SDK content appears misaligned or clipped.

**Solution**:

* Give your container a fixed height (e.g., 600px).
* Ensure no parent element uses overflow: hidden.


# Get Started
Source: https://developer.eka.care/api-sdk/hie-cm/sdks/web-sdk/consent-management/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](/api-sdk/hie-cm/consents/consent-details) to get the approved care contexts, then calls the [Retrieve Health Records API](/api-sdk/health-records/retrieve-health-records) 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](/api-sdk/hie-cm/consents/consent-details) and [Retrieve Health Records API](/api-sdk/health-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.

***

## 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-sdk/hie-cm/consents/consent-details) and [Retrieve Health Records API](/api-sdk/health-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. |

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

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


# Get Started
Source: https://developer.eka.care/api-sdk/hie-cm/sdks/web-sdk/nhpr-sdk/get-started

Complete implementation guide for the NHPR (Health Professional Registry) SDK

# NHPR SDK - Implementation

This guide provides everything you need to integrate the NHPR SDK (M4) into your application.

## Overview

The **NHPR SDK** (M4) is a plug-and-play UI widget that enables your application to onboard doctors onto ABDM's **Health Professional Registry (HPR)** and register their clinic as a **Healthcare Facility Registry (HFR)** entry — all from within your existing web application. It provides:

* **Aadhaar-based identity verification**: Doctor's identity is verified using ABDM's Aadhaar OTP flow.
* **HPR ID creation**: Doctor selects a unique HPR ID, practice type, email, and password.
* **HFR facility registration**: Clinic is registered or linked as an ABDM healthcare facility.
* **Onboarding callbacks**: Your application receives the resulting HPR ID and HFR Facility ID on success.

## Installation

### Prerequisites

* A modern web browser.
* Your domain must be whitelisted with Eka Care to avoid CORS errors. (Contact Eka Care to request API access and domain whitelisting.)
* A valid HTML container element where the SDK will mount.
* A short-lived Bearer access token generated from your backend using the [Connect Login](https://developer.eka.care/api-sdk/auth/client-login) API.

### Setup

Add the following to your webpage:

> [!NOTE]
>
> For staging/dev environments, replace the SDK URLs with:
>
> * **JS:** `https://unpkg.com/@eka-care/abdm-dashboard-stg/dist/sdk/abdm/js/abdm.js`
> * **CSS:** `https://unpkg.com/@eka-care/abdm-dashboard-stg/dist/sdk/abdm/css/abdm.css`

```html theme={null}
<!DOCTYPE html>
<html>
  <head>
    <title>NHPR SDK Integration</title>

    <!-- Include NHPR SDK CSS -->
    <link
      rel="stylesheet"
      href="https://unpkg.com/@eka-care/abdm-dashboard/dist/sdk/abdm/css/abdm.css"
    />
  </head>
  <body>
    <h1>NHPR SDK Demo</h1>

    <!-- Mount Button -->
    <button onclick="mountNHPRSDK()">Start HPR Onboarding</button>

    <!-- Container for NHPR SDK -->
    <div id="abdm-dashboard-root" style="width: 100%; height: 600px;"></div>

    <!-- Include NHPR SDK JS -->
    <script src="https://unpkg.com/@eka-care/abdm-dashboard/dist/sdk/abdm/js/abdm.js"></script>

    <script>
      function mountNHPRSDK() {
        window.abdmDashboardMount("abdm-dashboard-root", {
          // Authentication
          accessToken: "YOUR_ACCESS_TOKEN",
          clientId: "ext",

          // Behavior
          hideEkaSidePanel: false,
          showDashboardOnSuccess: false,

          // Callbacks
          onAbdmMountSuccess: (params) => {
            console.log("NHPR SDK mounted successfully:", params);
          },
          onAbdmOnboardSuccess: (params) => {
            console.log("HPR & HFR onboarding complete:", params);
            // Save params.createdHprId and params.facilityId to your backend
          },
          onAbdmDashboardClose: (params) => {
            console.log("NHPR SDK closed:", params);
          },
          onAbdmDashboardError: (params) => {
            console.error("NHPR SDK error:", params);
          },
        });
      }
    </script>
  </body>
</html>
```

## Core Functions

### 1. mountABDMDashboard

Initializes and renders the NHPR SDK in your specified container.

**Parameters:**

| Name | Type | Required | Description |
| - | - | - | - |
| `elementId` | `string` | | The HTML element ID where the SDK will mount. If the element does not exist, a `<div>` with this ID is created and appended to `document.body`. |
| `accessToken` | `string` | | Short-lived Bearer token for authenticating API calls to Eka's backend. Generate a fresh token from your backend on each widget load. Do not include the `Bearer` prefix. |
| `clientId` | `string` |  Optional | Client identifier for your application. Pass `"ext"` for web integrations. Defaults to `"ext"`. |
| `hideEkaSidePanel` | `boolean` |  Optional | Hide the decorative illustration panel shown on larger screens. Defaults to `false`. Set to `true` when embedding in a narrow modal or a mobile WebView. |
| `showDashboardOnSuccess` | `boolean` |  Optional | If `true`, navigates to the ABDM dashboard after HFR registration is complete. If `false`, the widget unmounts itself after firing `onAbdmOnboardSuccess`. Defaults to `true`. |
| `onAbdmMountSuccess` | `(params: TOnAbdmMountSuccess) => void` |  Optional | Fired immediately after the widget mounts successfully. |
| `onAbdmOnboardSuccess` | `(params: TOnAbdmOnboardSuccess) => void` | | Fired when HPR and HFR registration both complete. Contains the new HPR ID and HFR Facility ID. |
| `onAbdmDashboardClose` | `(params: TOnAbdmDashboardClose) => void` | | Fired when the user closes the widget via the back button or when `unmountABDMDashboard` is called. |
| `onAbdmDashboardError` | `(params: TOnAbdmDashboardError) => void` | | Fired if the widget fails to mount or encounters a fatal error. |

### 2. unmountABDMDashboard

Programmatically unmounts the widget and cleans up the React root.

```js theme={null}
window.abdmDashboardUnmount("abdm-dashboard-root");
```

Returns `true` if the widget was found and unmounted, `false` if no mounted widget was found at the given element ID.

***

## Callback Parameters

### onAbdmMountSuccess Callback

Fired immediately after the widget mounts and renders successfully into the container.

**Callback Signature:**

```typescript theme={null}
onAbdmMountSuccess: (params: TOnAbdmMountSuccess) => void;
```

**Type Definition:**

```typescript theme={null}
type TOnAbdmMountSuccess = {
  clientId?: string;
};
```

**Parameters:**

| Key | Type | Description |
| - | - | - |
| `clientId` | `string?` | The `clientId` passed to `mountABDMDashboard`. |

**Example:**

```javascript theme={null}
const onAbdmMountSuccess = (params) => {
  console.log("NHPR SDK mounted:", params);
  // params.clientId → "ext"

  // Show the container now that the widget is ready
  document.getElementById("abdm-dashboard-root").style.display = "block";
};
```

***

### onAbdmOnboardSuccess Callback

Fired when the full HPR + HFR onboarding flow completes successfully. This is the primary callback — use it to persist the HPR ID and HFR Facility ID to your backend.

**Callback Signature:**

```typescript theme={null}
onAbdmOnboardSuccess: (params: TOnAbdmOnboardSuccess) => void;
```

**Type Definition:**

```typescript theme={null}
type TOnAbdmOnboardSuccess = {
  clientId?: string;
  facilityId?: string;
  createdHprId?: string;
};
```

**Parameters:**

| Key | Type | Description |
| - | - | - |
| `clientId` | `string?` | The `clientId` passed to `mountABDMDashboard`. |
| `facilityId` | `string?` | The HFR Facility ID assigned by ABDM to the registered clinic. Store this against the clinic in your backend. |
| `createdHprId` | `string?` | The doctor's new HPR ID in the format `username@hpr.abdm`. Store this against the doctor in your backend. |

**Example:**

```javascript theme={null}
const onAbdmOnboardSuccess = (params) => {
  console.log("Onboarding complete:", params);

  const { facilityId, createdHprId } = params;

  // Persist to your backend
  fetch("/api/abdm/save-registration", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ facilityId, createdHprId }),
  });

  // Unmount and hide the widget
  window.abdmDashboardUnmount("abdm-dashboard-root");

  // Optionally pass to native bridge if running in a WebView
  if (window.EkaAbdm) {
    window.EkaAbdm.onAbdmOnboardSuccess(JSON.stringify(params));
  }
};
```

***

### onAbdmDashboardClose Callback

Fired when the user explicitly closes the widget (by clicking the back/close button) or when `unmountABDMDashboard` is called programmatically.

**Callback Signature:**

```typescript theme={null}
onAbdmDashboardClose: (params: TOnAbdmDashboardClose) => void;
```

**Type Definition:**

```typescript theme={null}
type TOnAbdmDashboardClose = {
  clientId: string;
};
```

**Parameters:**

| Key | Type | Description |
| - | - | - |
| `clientId` | `string` | The `clientId` passed to `mountABDMDashboard`. Falls back to `"default-client"` if not provided. |

**Example:**

```javascript theme={null}
const onAbdmDashboardClose = (params) => {
  console.log("NHPR SDK closed:", params);

  // Hide or remove the container from the UI
  const container = document.getElementById("abdm-dashboard-root");
  if (container) container.style.display = "none";

  // Optionally pass to native bridge if running in a WebView
  if (window.EkaAbdm) {
    window.EkaAbdm.onAbdmClose(JSON.stringify(params));
  }
};
```

***

### onAbdmDashboardError Callback

Fired if the widget fails to mount or encounters a fatal error during initialisation.

**Callback Signature:**

```typescript theme={null}
onAbdmDashboardError: (params: TOnAbdmDashboardError) => void;
```

**Type Definition:**

```typescript theme={null}
type TOnAbdmDashboardError = {
  clientId?: string;
};
```

**Parameters:**

| Key | Type | Description |
| - | - | - |
| `clientId` | `string?` | The `clientId` passed to `mountABDMDashboard` |

**Example:**

```javascript theme={null}
const onAbdmDashboardError = (params) => {
  console.error("NHPR SDK error:", params);

  alert("Something went wrong while loading the onboarding widget. Please try again.");

  // Forward to native bridge if running in a WebView
  if (window.EkaAbdm) {
    window.EkaAbdm.onAbdmError(JSON.stringify(params));
  }
};
```

**Suggested handling:**

* Always log the full `params` for debugging.
* Display a user-friendly retry prompt — the most common causes are an expired `accessToken` or a network failure.
* Generate a fresh `accessToken` from your backend before retrying `mountABDMDashboard`.

***

## Onboarding Flow (M4)

The widget is a linear multi-step flow. Each step is a full-screen state — the user cannot jump ahead.

### Screen reference

| Step | Screen | What happens |
| - | - | - |
| 1 | **Create** | Doctor enters their 12-digit Aadhaar number. An OTP is dispatched to the Aadhaar-linked mobile on submit. |
| 2 | **Verify OTP** | Doctor enters the OTP received on their Aadhaar-linked mobile number to complete identity verification. |
| 3 | **Setup HPR** | Doctor sets a unique HPR ID (ABDM-suggested IDs are shown as chips), practice type, email, password, and pincode. Real-time availability check runs on HPR ID input. |
| 4 | **HPR Successful** | Confirmation that the HPR ID has been created. The flow auto-advances to clinic verification. |
| 5 | **Verify Clinic** | Doctor selects a suggested ABDM facility or registers a new clinic with type, sub-type, medicine type, and facility details. |
| 6 | **HFR Successful** | HFR registration is confirmed. `onAbdmOnboardSuccess` fires with `createdHprId` and `facilityId`. |

### Practice types

| Code | Name |
| - | - |
| 1 | Modern Medicine |
| 2 | Dentist |
| 3 | Ayurveda |
| 4 | Unani |
| 5 | Siddha |
| 6 | Homeopathy |
| 89 | Sowa-Rigpa |

### HPR password requirements

The widget validates the password live as the doctor types. All rules must pass before the form can be submitted:

* At least 8 characters
* At least one uppercase letter
* At least one lowercase letter
* At least one number
* At least one special character

***

## OTP Auto-Read (Mobile WebView)

If your application embeds the widget in a mobile WebView that supports OTP interception, forward the OTP to the widget:

```js theme={null}
// Call this from your Android/iOS bridge when an OTP SMS is intercepted
window.onOtpAutoRead({ success: true, otp: "123456" });
```

The widget pre-fills the OTP input automatically and does not require the doctor to type it.

***

## Container Styling

Ensure your container has sufficient height for the widget to render correctly:

```html theme={null}
<div
  id="abdm-dashboard-root"
  style="width: 100%; height: 600px; border: 1px solid #ddd;"
></div>
```

For full-screen modal use cases, set the container to `100vw` / `100vh` and pass `hideEkaSidePanel: true` to disable the side illustration panel on smaller viewports.

***

## API Reference

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

| Method | Endpoint | Purpose |
| - | - | - |
| `POST` | `/abdm/v1/hpr/aadhaar/otp` | Initiate Aadhaar OTP for HPR identity verification |
| `POST` | `/abdm/v1/hpr/aadhaar/verify` | Verify the Aadhaar OTP |
| `POST` | `/abdm/v1/hpr/mobile/verify` | Verify the mobile OTP |
| `POST` | `/abdm/v1/hpr/id/available` | Check if a chosen HPR ID is available |
| `POST` | `/abdm/v1/hpr/create` | Create the HPR entry with ID and credentials |
| `POST` | `/abdm/v1/hfr/create` | Register the clinic as a new HFR facility |
| `POST` | `/abdm/v1/hfr/link` | Link the clinic to an existing HFR facility |

**Base URLs:**

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

***

## Troubleshooting

### Common Issues

#### 1. SDK Not Rendering

**Problem**: Nothing appears in the container.

**Solution**:

* Ensure `elementId` matches an existing HTML element ID.
* Verify the SDK JS and CSS files are loaded before calling `mountABDMDashboard`.
* Check the browser console for errors.

#### 2. APIs Not Being Called

**Problem**: API requests are not triggered after the SDK is mounted.

**Solution**:

* Ensure `accessToken` is passed correctly and has not expired — generate a fresh token from your backend on each mount.
* Ensure your domain is whitelisted with Eka Care to prevent CORS errors.

#### 3. Callbacks Not Firing

**Problem**: `onAbdmOnboardSuccess`, `onAbdmDashboardClose`, or `onAbdmDashboardError` are not being called.

**Solution**:

* Confirm callbacks are passed as valid functions, not strings or undefined.
* Avoid calling `unmountABDMDashboard` before the SDK has finished its flow — this will silently stop all further callbacks.

#### 4. Styling Issues

**Problem**: SDK content appears misaligned or clipped.

**Solution**:

* Give your container a fixed height (e.g., `600px`) or `100vh` for full-screen.
* Ensure no parent element applies `overflow: hidden` that would clip the widget.
* Pass `hideEkaSidePanel: true` on narrow viewports (under 768 px).

***

## Frequently Asked Questions

> **What is an HPR ID and why does the doctor need one?**
>
> An HPR (Health Professional Registry) ID is a unique digital identity for healthcare professionals in India's ABDM ecosystem. It is required for a doctor to participate in ABDM-enabled workflows such as linking patient health records and issuing digital prescriptions.

> **What is HFR and do I need it?**
>
> HFR (Healthcare Facility Registry) registers a clinic or hospital within ABDM. It is required for the clinic to act as a Health Information Provider (HIP) and exchange records through the ABDM network. The NHPR SDK handles both HPR and HFR registration in a single flow.

> **What should I do with the HPR ID and Facility ID returned in onAbdmOnboardSuccess?**
>
> Store both in your backend against the respective doctor and clinic records. The `facilityId` is the HFR ID assigned by ABDM to the clinic. The `createdHprId` is the doctor's new HPR ID in the format `username@hpr.abdm`. You will need these IDs for subsequent ABDM API calls.

> **How do I handle the widget in a mobile app WebView?**
>
> Pass `hideEkaSidePanel: true` to collapse the side illustration panel for narrow screens. Wire up your native OTP-intercept handler to call `window.onOtpAutoRead({ success: true, otp: '...' })` so the OTP field is filled automatically.

> **What happens if the doctor already has an HPR ID?**
>
> The current M4 flow creates a new HPR ID via Aadhaar-based identity verification. If the doctor already has an HPR ID registered with ABDM, contact Eka support to enable the existing-HPR linking flow for your integration.


# Init
Source: https://developer.eka.care/api-sdk/hie-cm/session/init

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/session/init
Generate mobile OTP for user session token

## Used in

* [Hold the ABHA Gateway session](/docs/hie-cm/workflows/hold-gateway-session)


# Status
Source: https://developer.eka.care/api-sdk/hie-cm/session/status

api-reference/user-app/abdm-connect/registration.yml GET /abdm/v1/session/status
Status of the user by the session.

X-Pt-Id is necessary to hit this API.

## Used in

* [Hold the ABHA Gateway session](/docs/hie-cm/workflows/hold-gateway-session)


# Verify
Source: https://developer.eka.care/api-sdk/hie-cm/session/verify

api-reference/user-app/abdm-connect/registration.yml POST /abdm/v1/session/verify
Verify mobile OTP and get user session token

## Used in

* [Hold the ABHA Gateway session](/docs/hie-cm/workflows/hold-gateway-session)


# API Reference
Source: https://developer.eka.care/api-sdk/index

Every Eka API, by product family. Each product's reference starts from the link below.

## Clinical AI

> **[Medical Scribe](/api-sdk/scribe/sessions/overview)**
>
> Consultations become structured notes that complete the chart

> **[Medical Document Parsing](/api-sdk/models/medical-document-parsing/introduction)**
>
> Any medical record, in any format, becomes structured data

## ABDM Connect

> **[HIE-CM](/api-sdk/hie-cm/overview)**
>
> ABHA, care contexts, consent and records

> **[NHCX](/api-sdk/nhcx/search-payers)**
>
> Eligibility, pre-auth and insurance claims

> **[UHI](/api-sdk/uhi/blood-bank/state-district)**
>
> Blood bank search and consultations across the network

## Resources

> **[Auth](/api-sdk/auth/getting-started)**
>
> Client credentials, OAuth2 and OIDC


# Delete Document
Source: https://developer.eka.care/api-sdk/models/medical-document-parsing/delete-document

delete /mr/api/v1/docs/{id}
This API is used to delete a document using a document ID.

API to delete a uploaded document from using a `document_id`


# Introduction
Source: https://developer.eka.care/api-sdk/models/medical-document-parsing/introduction



EkaCare’s Medical Document Parsing API offers a comprehensive solution for extracting and structuring data from diverse medical documents, including lab reports, prescriptions, and insurance policies. Explore our APIs here to see how they can add value to your healthcare ecosystem. Learn more about our advanced parsing capabilities, accuracy benchmarks, and detailed technology insights [here](/docs/models/technologies/document-parsing).

**Steps to Use Medical Document Parsing APIs:**

1. [**Authorization**](/api-sdk/auth/client-login): Use the Client Login API to generate an access token. Use this token for authorization in all API requests.
2. [**Upload Medical Records**](/api-sdk/models/medical-document-parsing/upload-report): Upload image or PDF files of medical record following the specified document specs. Upon successful upload, you will receive a `document_id`.
3. **Parsed Report**: Two distinct formats are available to obtain parsed results. Use the document\_id along with the required query parameter to fetch the results. The same API can be utilized to check the parsing status, and a webhook is also available for this purpose.
   * [**Retrieve Parsed Report**](/api-reference/health-ai/medical-document-parsing/retrieve-parsed-report) The response is returned in a structured FHIR format.
   * [**Parsed Report Result API**](/api-sdk/models/medical-document-parsing/parsed-report-result) This endpoint returns a JSON response that includes additional data such as normalized values, document page numbers, eka\_ranges, and other pertinent details not captured in the FHIR object due to its limitations.
4. [**Delete Medical Report**](/api-sdk/models/medical-document-parsing/delete-document): Instantly remove an uploaded document from our system using the Delete Report API by providing its unique `document_id`

Let’s start your journey! If you have any questions or need assistance, please feel free to reach out to our support team at [ekaconnect@eka.care](mailto:ekaconnect@eka.care). We’re here to help!

* Download Postman [**Collection**](https://documenter.getpostman.com/view/27490202/2sAYX6oMgH)
* Download Python [**Notebook**](https://github.com/eka-care/ekacare-api-quickstart)


# Parsed Report Result
Source: https://developer.eka.care/api-sdk/models/medical-document-parsing/parsed-report-result

get /mr/api/v1/docs/{document_id}/result
Use this API with the document_id to fetch results. This endpoint returns a JSON response that includes a detailed and structured parsed report.

* **Processing Time:** Record parsing typically takes 1–2 minutes for documents up to 10 pages and 2–4 minutes for those exceeding 10 pages, depending on the document size.
* **Understanding the Components of Response**
  * ## Lab Report

    ### Lab test

    Every lab test will have:

    * `test_name` : Verbatim as written in the lab report

    * `test_eka_id` : Eka identifier for the test

    * `loinc_id` : LOINC identifier for the test

    * NOTE: we use method agnostic LOINC identifiers in majority of the lab tests. Mapping of all Eka identifiers with LOINC identifiers can be obtained from [here](https://www.notion.so/EkaCare-Lab-report-parsing-details-16f28b1d375d8002918efa88d0d46567?pvs=21).

    ### Lab test data (value | unit | range)

    Lab test observation is parsed and shared in two variants

    ### Non unit-normalised data (`data` )

    This data is not unit-normalised, meaning this is verbatim as written in the report. The keys comprise

    * `value` : value of the test as given in the report
    * `unit` : unit of the test as given in the report, parsed by OCR (Non post processed). NOTE: at times OCR reads 10^3 u/ml as 103u/ml
    * `unit_processed` : unit of the test as given in the report, parsed by OCR and then processed by eka. In the above example 103u/ml  is converted back to 10\*3u/ml after applying post processing
    * `normal_range_report` : normal range parsed object basis the low-high values given in the report
    * `normal_range_eka` : normal range parsed object basis EkaCare’s database considering age / gender information of the person from the report.
    * `unit_eka_id` : Eka id for unit
    * `display_range` : Verbatim range display text (string) parsed from the report.

    ### Unit-Normalised data (`normalised_data` )

    This object contains unit normalised data for Value, Unit and range objects mentioned above. Normalisation is explained in detailed in the subsequent section.

    This object contains all the fields mentioned above except `display_range` and `unit_processed`since that is verbatim and normalisation does not make sense.

    # Normalisation process

    In order to create longitudinal lab investigation trends across lab reports across time, one needs to convert lab values and ranges to a standard unit. For every lab test, EkaCare defines a standard unit (basis highest frequency across millions of records). List of standard units for every test can be found [here](https://www.notion.so/EkaCare-Lab-report-parsing-details-16f28b1d375d8002918efa88d0d46567?pvs=21). Normalisation is process of multiplying values and normal ranges with a factor that converts the numerical results in the report to EkaCare standard unit for that lab test.

    # Range-object

    Range objects contain structured low and high values of the normal range.

    Note that our parsers only structured low-high normal range format. Any other formats such as:

    normal: \< 200
    borderline high: 200-240
    high: 240+

    While this data is available in “display\_range” field in non unit-normalised object as string, we do not parse and structure this kind of structure.

    However, EkaCare ranges in structured formats are available for someone to still interpret the results if need be.

    # PII data

    This section outlines the structure and components of Personally Identifiable Information (PII) as provided within medical documentation. The information captured includes page number, document dates, patient details, and report specifics.

    ### Components of PII Data

    `<unique_file_path>`: A unique identifier representing the file path is utilized to group related PII information. Each file path is mapped to a collection of PII data for different pages in the document..

    * `PageNum`**:** Represents the page number within the document where relevant PII data is found.
    * `DocumentDate`**:** Captures the document date in Unix timestamp format for consistent time-related operations.

    ### **Patient Details**

    * `Name`**:** Verbatim representation of the patient's name as found in the document.
    * `Age`**:** The patient's age is detailed in years, months, and days, providing a comprehensive age identification.
    * `Gender`**:** Captures the patient's gender, e.g., "male" or "female".

    ### **Report Details**

    * `SampleCollectionDate`**:** (only for Lab-reports) The date and time when the sample was collected, in "dd/mm/yyyy hh:mm:ss" format.
    * `SampleReceivedDate`**:** (only for Lab-reports) The date and time when the sample was received, in "dd/mm/yyyy hh:mm:ss" format.
    * `GeneratedDate`**:** (only for Lab-reports) The report generation date and time in "dd/mm/yyyy hh:mm:ss" format.
    * `Doctor`**:** The doctor's name, if available.
    * `Facility`**:** The name of the facility or laboratory where the test was conducted, e.g., "LalPath Labs".


# Upload Report
Source: https://developer.eka.care/api-sdk/models/medical-document-parsing/upload-report

POST /mr/api/v2/docs
Upload the image or PDF file

Upload the image or PDF file following the document specifications below. Ensure you define the document type and tasks you want to process in the query parameters.
**Document Specifications**

* **PDF Documents**: Ensure the file is complete and legible.
* **Images**:
  * Preferred DPI: **150+**
  * Images must be **non-blurred**
  * **Avoid** images with a high degree of **non-linear warping** or **rotation** for optimal processing accuracy.

**File Size Limit**

* Maximum allowed file size: **10 MB**
* **Files larger than 10 MB:** Use the [Request Upload](https://developer.eka.care/api-sdk/health-records/create-overview) flow to upload larger files.


# Link Entity
Source: https://developer.eka.care/api-sdk/models/medical-entity-codification/link-entity

POST /med-link/nel/link
Links a single free-text medical entity to candidate codes from the requested ontology. The `metadata` field carries ontology-specific hints — it is **strongly recommended for LOINC** (a unit can change the linked code) and **optional for medication**. SNOMED CT and ICD-10-CM Comprehend do not use `metadata`.

## About this endpoint

`POST /med-link/nel/link` links a single free-text medical entity to candidate
codes from the requested ontology. Pick the `ontology` and `version` from
[List Registry](/api-sdk/models/medical-entity-codification/registry).

Use the example selector above to see a request and response for each ontology.

## The `metadata` field by ontology

`metadata` carries ontology-specific hints. It changes results for LOINC and
medication, and is ignored by SNOMED CT and ICD-10-CM Comprehend.

### SNOMED CT — `snomed`

No `metadata` required. Send the symptom, finding or disorder as the `query`.
Each result's `metadata` includes a `semantic_tag` (e.g. `finding`, `disorder`).

### LOINC — `loinc`

`metadata` is **strongly recommended** — the lab test name alone is often
ambiguous, and a unit or specimen decides which LOINC code is correct.

| Key | Type | Description |
| - | - | - |
| `unit` | string | Test unit, e.g. `g/dl`, `mg/dl`, `%`. **Most important hint.** |
| `value` | string | Numeric result value. Improves value-type matching. |
| `range` | string | Reference range for the result. |
| `specimen` | string | Specimen type, e.g. `blood`, `urine`. |
| `specimen_text` | string | Free-text specimen description (auto-detected if omitted). |
| `panel_name` | string | Panel name for multi-test panels. |
| `extended_test_name` | string | Extended/alternate test name. |

> [!WARNING]
>
> Without `metadata`, a LOINC query such as `hemoglobin` can link to the wrong
> specimen (e.g. urine instead of blood). Supplying `unit` and `specimen` lets the
> pipeline return `is_linked: true` against the correct code.

### Medication — `medication`

`metadata` is **optional** — it helps resolve ambiguous brand names. The `score`
field is `null`; read `metadata.matching_breakdown` and `metadata.linking_requirements`
on each result instead.

| Key | Type | Description |
| - | - | - |
| `form` | string | Medication form, e.g. `tablet`, `capsule`, `injection`. |
| `generic_name` | string | Generic / salt name of the drug. |
| `dose_unit` | string | Dosage unit, e.g. `mg`, `mcg`, `ml`. |
| `dose_custom` | string | Custom dosage string. |

### ICD-10-CM Comprehend — `icd-10-cm` (`comprehend`)

No `metadata` required. This version uses AWS Comprehend Medical, so it works
well on natural-language clinical text. The response includes a `query_breakdown`
with the detected `entity`, `traits` and `attributes`.

## Reading the response

| Field | Description |
| - | - |
| `results[]` | Candidate codes, ranked by relevance. |
| `results[].term_id` | The ontology code. |
| `results[].is_linked` | `true` when the pipeline is confident of a single correct match. |
| `results[].score` | Relevance/confidence (`null` for medication). |
| `query_breakdown` | How the query was parsed (LOINC, medication, ICD-10-CM Comprehend; `null` for SNOMED CT). |


# Link Entities (Batch)
Source: https://developer.eka.care/api-sdk/models/medical-entity-codification/link-entity-batch

POST /med-link/nel/link/batch
Links up to 5 free-text entities in a single call. All queries in a batch share the same `ontology`, `version`, `top_k` and `metadata`. The response contains one result block per query, in request order.

## About this endpoint

`POST /med-link/nel/link/batch` links up to **5** free-text entities in a single
call. Every query in the batch shares the same `ontology`, `version`, `top_k`
and `metadata`.

The response `results[]` array contains one block per query, in request order —
each block has the same shape as a single
[Link Entity](/api-sdk/models/medical-entity-codification/link-entity) response.

## When to use it

* Coding several entities from the same document (e.g. all symptoms in a note).
* Reducing round-trips when the ontology and `metadata` are identical.

> [!NOTE]
>
> Because `metadata` is shared across the whole batch, group queries that need
> different hints — especially LOINC tests with different units or specimens —
> into separate batches, or use the single
> [Link Entity](/api-sdk/models/medical-entity-codification/link-entity) endpoint.

## Limits

| Constraint | Value |
| - | - |
| Queries per request | 1–5 |
| `top_k` | 1–10 (default 5) |


# List Registry
Source: https://developer.eka.care/api-sdk/models/medical-entity-codification/registry

GET /med-link/registry/
Returns every ontology available for codification, the versions of each ontology, and the active indexes backing them. Use this to discover the exact `ontology` and `version` values to send to the linking endpoints.

## About this endpoint

`GET /med-link/registry/` returns every ontology available for codification,
along with the supported versions of each.

Call it before linking to confirm the exact `ontology` and `version` values to
send to [Link Entity](/api-sdk/models/medical-entity-codification/link-entity) and
[Link Entities (Batch)](/api-sdk/models/medical-entity-codification/link-entity-batch).

## Response fields

| Field | Description |
| - | - |
| `ontologies[]` | Available ontologies, each with its `name` and supported `versions`. |

> [!TIP]
>
> Use the `ontology` + `version` pairs from `ontologies[]` directly as the
> `ontology` and `version` fields in linking requests.


# Python
Source: https://developer.eka.care/api-sdk/models/sdks/backend/report-parsing-sdk

A Python SDK for parsing medical documents using Eka Care APIs

# Overview

[Report Parsing SDK on GitHub](https://github.com/eka-care/reports-parsing-sdk/tree/main/python)

A comprehensive Python SDK for interacting with the Eka Care Medical Records API. This SDK enables you to upload and process medical documents with support for smart report parsing and PII detection.

## Installation

Install from source:

```bash theme={null}
git clone https://github.com/eka-care/reports-parsing-sdk.git
cd reports-parsing-sdk/python
pip install -e .
```

***

## Quick Start

Basic initialization and document processing:

```python theme={null}
from ekacare_sdk import EkaCareSDK

# Initialize the SDK with your credentials
sdk = EkaCareSDK(
    client_id="your_client_id",
    client_secret="your_client_secret"
)

# Process a document
result = sdk.process_document(
    "/path/to/lab_report.jpg",
    task="smart"
)

# Get the document ID from the result
print(f"Document ID: {result['document_id']}")

# Retrieve the processing results
response = sdk.get_document_result(result['document_id'])
print(response['data'])

# Clean up
sdk.close()
```

***

## Configuration

### Environment Variables

Create a `.env` file with your credentials:

```bash theme={null}
EKACARE_CLIENT_ID=your_client_id
EKACARE_CLIENT_SECRET=your_client_secret
EKACARE_BASE_URL=https://api.eka.care
```

### Using Configuration Class

Load settings from environment variables or configure manually:

```python theme={null}
from ekacare_sdk.config import EkaCareConfig

# Load from environment
config = EkaCareConfig.from_env()
sdk = EkaCareSDK(config.client_id, config.client_secret)
```

***

## Features

The SDK provides the following capabilities:

* **Automatic Authentication**: Handles token management automatically
* **Document Processing**: Upload and process medical documents
* **Polling Support**: Built-in polling for asynchronous results
* **Environment Configuration**: Easy setup via environment variables

***

## Task Options

When processing documents, you can specify different task types:

| Task | Description |
| - | - |
| `smart` | Default option - Smart report parsing |
| `pii` | PII (Personally Identifiable Information) detection |
| `both` | Combined smart parsing and PII detection |

Example:

```python theme={null}
# Smart report parsing (default)
result = sdk.process_document("/path/to/report.pdf", task="smart")

# PII detection
result = sdk.process_document("/path/to/report.pdf", task="pii")

# Both smart parsing and PII detection
result = sdk.process_document("/path/to/report.pdf", task="both")
```

***

## API Reference

### Primary Methods

| Method | Description |
| - | - |
| `process_document(file_path, doc_type="lr", task="smart")` | Upload and process a document |
| `get_document_result(document_id)` | Retrieve processing results for a document |


# Java
Source: https://developer.eka.care/api-sdk/models/sdks/backend/report-parsing-sdk-java

A Java Spring Boot SDK for parsing medical documents using Eka Care APIs

# Overview

[Report Parsing SDK on GitHub](https://github.com/eka-care/reports-parsing-sdk/tree/main/java)

A Java Spring Boot SDK for processing medical documents through the Eka Care API. This SDK supports document submission, result polling, and FHIR data extraction.

## Prerequisites

* **JDK 17+** (verify with `java -version`)
* **Maven** (verify with `mvn -version`)
* **IDE**: IntelliJ IDEA, Eclipse, or VS Code with Java extensions
* **Eka Care API Credentials**: Valid client ID and secret

***

## Project Structure

```
ekacare-sdk/
├── src/main/java/com/example/ekacare/
│   ├── sdk/EkaCareSDK.java
│   ├── service/EkaCareService.java
│   └── controller/DocumentController.java
├── src/main/resources/application.properties
└── pom.xml
```

***

## Setup Instructions

### Step 1: Create Spring Boot Project

**Via Spring Initializr:**

* Visit [start.spring.io](https://start.spring.io)
* Select Maven, Java 17, Spring Boot 3.2.0
* Add "Spring Web" dependency
* Generate and extract

**Via IntelliJ IDEA:**
File → New → Project → Spring Initializr → Configure with Java 17 and Spring Boot 3.2.0

### Step 2: Add SDK Files

Copy files from the repository to respective directories:

* `EkaCareSDK.java` → `src/main/java/com/example/ekacare/sdk/`
* `EkaCareService.java` → `src/main/java/com/example/ekacare/service/`
* `application.properties` → `src/main/resources/`
* `pom.xml` → project root

### Step 3: Configure Credentials

Update `application.properties`:

```properties theme={null}
ekacare.client.id=YOUR_CLIENT_ID_HERE
ekacare.client.secret=YOUR_CLIENT_SECRET_HERE
```

### Step 4: Build

```bash theme={null}
mvn clean install
```

***

## Quick Start

### Direct SDK Usage

```java theme={null}
try (EkaCareSDK sdk = new EkaCareSDK("CLIENT_ID", "CLIENT_SECRET")) {
    Map<String, Object> result = sdk.processAndWait(
        "/path/to/document.jpg",
        "smart",
        10,  // poll interval (seconds)
        300  // timeout (seconds)
    );
    Map<String, Object> data = (Map<String, Object>) result.get("data");
    System.out.println("FHIR: " + data.get("fhir"));
}
```

### Spring Boot Service

```java theme={null}
@Component
public class MyDocumentProcessor {
    @Autowired
    private EkaCareService ekaCareService;

    public void process() throws InterruptedException {
        Map<String, Object> result = ekaCareService
            .processDocumentAndWait("/path/to/document.jpg", "smart");
        System.out.println("Result: " + result);
    }
}
```

***

## REST API Endpoints

The SDK provides REST endpoints for document processing:

| Method | Endpoint | Purpose |
| - | - | - |
| POST | `/api/documents/process?task=smart` | Async document submission |
| GET | `/api/documents/{id}/result` | Retrieve processing result |
| POST | `/api/documents/process-sync?task=smart` | Sync processing (waits for completion) |

***

## Task Options

When processing documents, you can specify different task types:

| Task | Description |
| - | - |
| `smart` | Smart report parsing |
| `pii` | PII (Personally Identifiable Information) detection |
| `both` | Combined smart parsing and PII detection |

***

## Example cURL Requests

```bash theme={null}
# Submit document asynchronously
curl -X POST http://localhost:8080/api/documents/process?task=smart \
  -F "file=@/path/to/document.jpg"

# Get processing result
curl http://localhost:8080/api/documents/abc123/result

# Synchronous processing (waits for completion)
curl -X POST http://localhost:8080/api/documents/process-sync?task=smart \
  -F "file=@/path/to/document.jpg"
```

***

## Troubleshooting

| Issue | Solution |
| - | - |
| File Not Found | Use absolute paths or verify relative path correctness |
| Authorization (401) | Validate credentials in properties file |
| Maven Build Fails | Run `mvn clean install -U` |
| Port 8080 In Use | Change in `application.properties`: `server.port=8081` |

### Large File Upload

For large files, increase limits in `application.properties`:

```properties theme={null}
spring.servlet.multipart.max-file-size=50MB
spring.servlet.multipart.max-request-size=50MB
```


# Get Admission Visits
Source: https://developer.eka.care/api-sdk/nhcx/admission-visits

get /abdm/nhcx/v1/records/admission/{admissionId}
Lists an admission's visit ids through the HIP's registered adapter.



# Archive Claim
Source: https://developer.eka.care/api-sdk/nhcx/archive-claim

post /abdm/nhcx/v1/claims/{claimId}/archive
Sets a claim aside so it is not reused. It stays readable. Refused with 400 while a pre-auth is live; cancel it first.



# Get Biometric Consent
Source: https://developer.eka.care/api-sdk/nhcx/biometric-consent

get /abdm/nhcx/v1/claims/{claimId}/biometric-auth/consent
Says whether a captured biometric consent for the stage is still valid, so you can reuse its user_token instead of capturing again.



# Init Biometric Auth
Source: https://developer.eka.care/api-sdk/nhcx/biometric-init

post /abdm/nhcx/v1/claims/{claimId}/biometric-auth/init
Starts a biometric authentication of the claim's beneficiary for the pre-auth or claim stage. auth_mode is FINGERPRINT or IRIS. Discharge is accepted for Claim.



# List Biometric Sessions
Source: https://developer.eka.care/api-sdk/nhcx/biometric-sessions

get /abdm/nhcx/v1/claims/{claimId}/biometric-auth/sessions
Every biometric verify recorded on the claim. Cyclic claims take their cycle_dates from the cycle rows; next_capture_allowed_at is set while the 24 hour gap runs.



# Verify Biometric Auth
Source: https://developer.eka.care/api-sdk/nhcx/biometric-verify

post /abdm/nhcx/v1/claims/{claimId}/biometric-auth/verify
Completes the authentication with the PID block from the RD-service scanner. Send the user_token with auth_type biometric on Submit Pre-auth or Submit Claim. For cyclic procedures send purpose cycle and procedure_code on every treatment visit.



# Cancel Pre-auth
Source: https://developer.eka.care/api-sdk/nhcx/cancel-preauth

post /abdm/nhcx/v1/claims/{claimId}/preauth/cancel
Cancels the claim's active pre-auth. The claim stays open and reusable. The body is optional; without a reason the default is used. The payer answers asynchronously: a 2xx means the request was sent, not approved. Track it with the returned request_id on Get Claim Request.



# Check Eligibility
Source: https://developer.eka.care/api-sdk/nhcx/check-eligibility

post /abdm/nhcx/v1/policies/{policyId}/eligibility
Checks the policy is in force and returns the wallet balance, without creating a claim. cached true means the answer came from the last check; cached false with a request_id means a fresh check went to the payer, so call again shortly.



# Get Claim Payments
Source: https://developer.eka.care/api-sdk/nhcx/claim-payments

get /abdm/nhcx/v1/claims/{claimId}/payments
Every payment notice the payer sent for the claim. Group rows by transaction_ref; a transaction's amount is its latest row's amount, not the sum.



# Get Claim Request
Source: https://developer.eka.care/api-sdk/nhcx/claim-request

get /abdm/nhcx/v1/claims/{claimId}/requests/{correlationId}
One exchange in full: what was sent (request_meta, documents), the parsed payer answer (response_meta, empty while pending) and the per-item verdicts (items).



# Get Claim Request Document
Source: https://developer.eka.care/api-sdk/nhcx/claim-request-document

get /abdm/nhcx/v1/claims/{claimId}/requests/{correlationId}/documents/{docId}
Streams a submitted document's bytes with its own content type.



# Get Claim Requests
Source: https://developer.eka.care/api-sdk/nhcx/claim-requests

get /abdm/nhcx/v1/claims/{claimId}/requests
Every exchange with the payer on this claim, oldest first: eligibility, pre-auth, claim, communication and more, each with its status and outcome.



# Create Claim
Source: https://developer.eka.care/api-sdk/nhcx/create-claim

post /abdm/nhcx/v1/claims
Creates the claim (the case every later call hangs off) and sends the auth-requirements check for the listed procedures. An open claim for the same policy and beneficiary is reused. The payer's per-procedure documents and questionnaires arrive on the coverage_eligibility request in Get Claim Requests.



# Discover Policy
Source: https://developer.eka.care/api-sdk/nhcx/discover-policy

post /abdm/nhcx/v1/coverage/discovery
Asks the payer to find the policy for a member_id and payer_id when Search Policies returns nothing. Poll Policy Discovery Status for the result.



# Policy Discovery Status
Source: https://developer.eka.care/api-sdk/nhcx/discovery-status

get /abdm/nhcx/v1/coverage/discovery/status
Returns status pending until the payer answers, then found with the policy_id and product_id. Branch only on status.



# Get Records Adapter
Source: https://developer.eka.care/api-sdk/nhcx/get-adapter

get /abdm/nhcx/v1/records/adapters
Returns the adapter registered for the HIP in X-Hip-Id. Auth headers are never returned.



# Get Claim
Source: https://developer.eka.care/api-sdk/nhcx/get-claim

get /abdm/nhcx/v1/claims/{claimId}
Claim summary: status, payer references, turn-around deadlines, review path, co-payment and the stages with a saved draft.



# Get Procedure
Source: https://developer.eka.care/api-sdk/nhcx/get-procedure

get /abdm/nhcx/v1/policies/{policyId}/procedures/{procedureCode}
Full catalogue detail for a procedure: flags, costs, caps, mandatory documents and questionnaires. Check a feature's flag before reading its cap; payers publish non-zero caps on procedures where the feature is off.



# List Claims
Source: https://developer.eka.care/api-sdk/nhcx/list-claims

get /abdm/nhcx/v1/claims
Lists claims with their beneficiary.



# List Procedures
Source: https://developer.eka.care/api-sdk/nhcx/list-procedures

get /abdm/nhcx/v1/policies/{policyId}/specialities/{specialityCode}/procedures
Lists the procedures under one speciality of the policy's catalogue.



# List Specialities
Source: https://developer.eka.care/api-sdk/nhcx/list-specialities

get /abdm/nhcx/v1/policies/{policyId}/specialities
Lists the specialities in the policy's procedure catalogue.



# Preview Claim Bundle
Source: https://developer.eka.care/api-sdk/nhcx/preview-claim

post /abdm/nhcx/v1/claims/{claimId}/claim/preview
Takes the same body as Submit Claim and returns the exact FHIR bundle it would send. Nothing is sent or stored.



# Preview Claim Bundle (Full Request)
Source: https://developer.eka.care/api-sdk/nhcx/preview-claim-full

post /abdm/nhcx/v1/claim/preview
Builds a claim FHIR bundle from a full claim request without sending it. Prefer Preview Claim Bundle once the claim exists.



# Preview Pre-auth Bundle
Source: https://developer.eka.care/api-sdk/nhcx/preview-preauth

post /abdm/nhcx/v1/preauth/preview
Builds the pre-auth FHIR bundle from a full request without sending it.



# Refresh Plan
Source: https://developer.eka.care/api-sdk/nhcx/refresh-plan

post /abdm/nhcx/v1/policies/{policyId}/plan/refresh
Requests a fresh procedure catalogue (InsurancePlan) for the policy's product. Poll List Specialities until it is ready.



# Register Records Adapter
Source: https://developer.eka.care/api-sdk/nhcx/register-adapter

post /abdm/nhcx/v1/records/adapters
Registers where your HIS records API lives and how to call it, for the HIP in X-Hip-Id. Each capability is one templated HTTP call with an extract map; flows chain them. The records APIs read visit_ids and fhir from the finished flow.



# Reprocess Claim
Source: https://developer.eka.care/api-sdk/nhcx/reprocess-claim

post /abdm/nhcx/v1/claims/{claimId}/claim/reprocess
One-shot appeal of a rejected claim, or dispute of a claim settled with more than 20% deducted. A dispute needs a document; amount defaults to and cannot exceed the deduction. Get Claim's review_path says when this is allowed. The payer answers asynchronously: a 2xx means the request was sent, not approved. Track it with the returned request_id on Get Claim Request.



# Save Draft
Source: https://developer.eka.care/api-sdk/nhcx/save-draft

put /abdm/nhcx/v1/claims/{claimId}/draft
Saves a partly filled pre-auth or claim form without submitting it. The body is the same one the stage's submit takes, stored as sent. Read it back with Get Claim Request using correlation id draft:Preauth or draft:Claim.



# Search Payers
Source: https://developer.eka.care/api-sdk/nhcx/search-payers

get /abdm/nhcx/v1/payers
Lists payers from the NHCX participant registry. The participant_code is the payer_id used by every later call.



# Search Policies
Source: https://developer.eka.care/api-sdk/nhcx/search-policies

post /abdm/nhcx/v1/policies/search
Finds a beneficiary's policies by mobile number, ABHA number or member ID. A mobile number can return several family members' policies. When nothing comes back, use Policy Discovery.



# Submit Claim
Source: https://developer.eka.care/api-sdk/nhcx/submit-claim

post /abdm/nhcx/v1/claims/{claimId}/claim
Submits the final claim after discharge. request_type is empty for the first submit, QueryResponse to answer a payer query, FollowUp to resubmit a rejected claim. The claimed amount is the sum of itemized_billing. The payer answers asynchronously: a 2xx means the request was sent, not approved. Track it with the returned request_id on Get Claim Request.



# Submit Pre-auth
Source: https://developer.eka.care/api-sdk/nhcx/submit-preauth

post /abdm/nhcx/v1/claims/{claimId}/preauth
Submits a pre-auth for the claim. request_type picks the workflow: InitialRequest, QueryResponse to answer a payer query, FollowUp to resubmit a rejected pre-auth, Enhancement to raise the approved scope. Everything the claim already knows (payer, policy, facility, patient) is filled in for you. The payer answers asynchronously: a 2xx means the request was sent, not approved. Track it with the returned request_id on Get Claim Request.



# Get Visit FHIR
Source: https://developer.eka.care/api-sdk/nhcx/visit-fhir

get /abdm/nhcx/v1/records/visits/{visitId}
Returns a visit's FHIR bundle through the HIP's registered adapter.



# Create or Update Document
Source: https://developer.eka.care/api-sdk/scribe/documents/create-update-document

POST /voice/api/v1/documents
Create a new document on a session (omit `document_id` → `201`), or update an existing one (include `document_id` → `200`) — for example to save a doctor's edits to generated notes. Every response includes a presigned **PUT** URL: upload the document content (markdown) to that URL to store it.


Create a document on a session (omit `document_id` → `201`) or update one (include `document_id` → `200`) — e.g. to save a doctor's edits. The response includes a presigned **PUT** URL — upload the markdown content there:

```bash theme={null}
curl -X PUT "<presigned_url>" -H "Content-Type: text/markdown" --data-binary @note.md
```


# Delete Document
Source: https://developer.eka.care/api-sdk/scribe/documents/delete-document

DELETE /voice/api/v1/documents/{document_id}
Archive (soft-delete) a document. The document disappears from session listings and Get Document returns `404` for it afterwards. Deleting an already-deleted document is a no-op and still returns success.


Archive a document. It disappears from listings and [Get Document](/api-sdk/scribe/documents/get-document) returns `404` afterwards. Idempotent.


# Get Document
Source: https://developer.eka.care/api-sdk/scribe/documents/get-document

GET /voice/api/v1/documents/{document_id}
Fetch a document's metadata and a presigned **GET** URL to download its content (markdown). Use this to retrieve generated notes by `document_id` — e.g. the `document_id` returned by Get Session or Process Template.


Fetch a document's metadata plus a presigned **GET** URL to download its markdown content. Use the `document_id` from [Get Session](/api-sdk/scribe/sessions/get-session) or [Process Template](/api-sdk/scribe/sessions/process-template). Presigned URLs expire — fetch fresh, don't store.


# List Session Documents
Source: https://developer.eka.care/api-sdk/scribe/documents/list-session-documents

GET /voice/api/v1/sessions/{session_id}
Fetch a session's full record — status, patient details, audio quality matrix and, most importantly, the list of **all documents** generated or created on the session (notes, transcripts, custom documents). Set `presigned=true` to include a download URL for each document.


Fetch a session's record with **all its documents** — notes, transcripts, custom docs. Add `?presigned=true` to get a download URL per document.


# Discovery
Source: https://developer.eka.care/api-sdk/scribe/protocol/discovery

GET /voice/v1/.well-known/medscribealliance
Public, unauthenticated endpoint that advertises the service's protocol version, supported authentication methods, audio capabilities, available models and supported languages. Clients should fetch this first and use the returned `models`, `capabilities.audio_formats` and `capabilities.upload_methods` to configure their session. The response is cacheable (`Cache-Control: max-age=10800`).


Public, no-auth endpoint that advertises the service's capabilities: models, audio formats, upload methods and languages. Fetch it once on startup (cacheable for 3 hours) and use it to configure [Create Session](/api-sdk/scribe/sessions/create-session).


# Android SDK
Source: https://developer.eka.care/api-sdk/scribe/sdks/android-sdk



# EkaScribe SDK Documentation

EkaScribe SDK (Voice2Rx) is an Android SDK for voice-based medical transcription and documentation.
It provides real-time voice recording, transcription, and intelligent medical documentation
generation with support for multiple languages and output formats.

**Version:** 3.0.7

**Minimum Android SDK:** 23 (Android 6.0)

***

## 1. Installation

### Add Maven Repository

Add the JitPack repository to your project's `settings.gradle.kts` (or `build.gradle`):

```kotlin theme={null}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        // Add below line to fetch SDK from Jitpack
        maven { url = uri("<https://jitpack.io>") }
    }
}

```

### Add Dependencies

Add the EkaScribe SDK and required networking dependency to your app's `build.gradle.kts`:

```kotlin theme={null}
dependencies {
    implementation("com.github.eka-care:Eka-Scribe-Android:${LATEST_VERSION}")
}

```

### Required Permissions

Add the following permissions to your `AndroidManifest.xml`:

```xml theme={null}
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

**Note:** You must request `RECORD_AUDIO` permission at runtime for Android 6.0 and above.

***

## 2. Initialization

Initialize the SDK in your `Application` class or main `Activity`.

### Step 1: Implement Lifecycle Callbacks

Create a class that implements `Voice2RxLifecycleCallbacks` to handle session events.

```kotlin theme={null}
import com.eka.voice2rx_sdk.sdkinit.Voice2RxLifecycleCallbacks
import com.eka.voice2rx_sdk.common.models.EkaScribeError

class MyVoice2RxCallbacks : Voice2RxLifecycleCallbacks {
    override fun onStartSession(sessionId: String) {
        // Recording started
    }

    override fun onStopSession(sessionId: String, recordedFiles: Int) {
        // Get result when ready after stopping the session
        CoroutineScope(Dispatchers.IO).launch {
            Voice2Rx.pollEkaScribeResult(sessionId = sessionId).onSuccess {
                Log.d(TAG, it.templates.toString())
            }.onFailure {
                Log.d(TAG, "error : ${it.message.toString()}")
            }
        }
    }

    override fun onPauseSession(sessionId: String) {
        // Recording paused
    }

    override fun onResumeSession(sessionId: String) {
        // Recording resumed
    }

    override fun onError(error: EkaScribeError) {
        // Handle error
    }
}

```

### Step 2: Implement TokenStorage

The networking module requires a `TokenStorage` implementation to handle authentication tokens.

```kotlin theme={null}
import com.eka.networking.token.TokenStorage

class MyTokenStorage : TokenStorage {
    override fun getAccessToken(): String {
        return "access_token"
    }

    override fun getRefreshToken(): String {
        return "refresh_token"
    }

    override fun saveTokens(accessToken: String, refreshToken: String) {
        // save tokens
    }

    override fun onSessionExpired() {
        // SessionExpired refresh token expired
    }
}
```

### Step 3: Configure and Initialize

Initialize `Voice2Rx` with `Voice2RxInitConfig` and `NetworkConfig`.

```kotlin theme={null}
import com.eka.voice2rx_sdk.sdkinit.Voice2Rx
import com.eka.voice2rx_sdk.sdkinit.Voice2RxInitConfig
import com.eka.networking.client.NetworkConfig
import com.eka.networking.client.AuthConfig

// 1. Configure Network
val networkConfig = NetworkConfig(
    appId = "your-app-id",
    baseUrl = "<https://api.eka.care/>",
    appVersionName = BuildConfig.VERSION_NAME,
    appVersionCode = BuildConfig.VERSION_CODE,
    isDebugApp = false // false in production environment,
    apiCallTimeOutInSec = 30L,
    headers = mapOf(), // Optional headers
    tokenStorage = MyTokenStorage()
)

// 2. Configure SDK
val config = Voice2RxInitConfig(
    voice2RxLifecycle = MyVoice2RxCallbacks(),
    networkConfig = networkConfig,
)

// 3. Initialize
Voice2Rx.init(config, context)

```

***

## 3. Core API Reference

All main functions are available via the `Voice2Rx` singleton object.

### Recording Control

### `startVoice2Rx`

Starts a new voice recording session.

```kotlin theme={null}
fun startVoice2Rx(
    mode: String = Voice2RxType.CONSULTATION.value, // "consultation" or "dictation"
    patientDetails: PatientDetails? = null,
    outputFormats: List<Template>, // Max 2 formats
    languages: List<String>,       // Max 2 languages
    modelType: String,             // e.g., "pro"
    onError: (EkaScribeError) -> Unit,
    onStart: (String) -> Unit
)

```

**Example:**

```kotlin theme={null}
// Define output templates using Template(templateId, templateName)
val outputFormats = listOf(
    Template(templateId = "19288d2f-81a9-46a6-b804-9651242a9b3e", templateName = "SOAP Note")
)

val languages = listOf("en-IN") // If you're not offering users a language change option in your UI, use "auto_detect" for the best results.

Voice2Rx.startVoice2Rx(
    mode = Voice2RxType.DICTATION.value,
    outputFormats = outputFormats,
    languages = languages,
    modelType = "pro" // or lite for faster results,
    onError = { error -> Log.e("SDK", "Error: ${error.errorDetails.message}") },
    onStart = { sessionId -> Log.d("SDK", "Started: $sessionId") }
)

```

### `pauseVoice2Rx`

Pauses the current recording.

```kotlin theme={null}
Voice2Rx.pauseVoice2Rx()

```

### `resumeVoice2Rx`

Resumes a paused recording.

```kotlin theme={null}
Voice2Rx.resumeVoice2Rx()

```

### `stopVoice2Rx`

Stops the recording and triggers processing.

```kotlin theme={null}
Voice2Rx.stopVoice2Rx()

```

### `isCurrentlyRecording`

Checks if a recording is in progress.

```kotlin theme={null}
val isRecording = Voice2Rx.isCurrentlyRecording()

```

### Data & Results

### `getSessionOutput`

Retrieves the transcription/generated output for a session.

```kotlin theme={null}
suspend fun getSessionOutput(sessionId: String): Result<SessionResult>

```

### `pollEkaScribeResult`

Polls for results, useful for waiting until processing completes.

```kotlin theme={null}
suspend fun pollEkaScribeResult(sessionId: String): Result<SessionResult>

```

### `getHistoryVoice2Rx`

Fetches session history.

```kotlin theme={null}
suspend fun getHistoryVoice2Rx(count: Int? = null): Voice2RxHistoryResponse?

```

### `getFullRecordingFile`

Gets the audio file for a session.

```kotlin theme={null}
fun getFullRecordingFile(sessionId: String): Result<File>

```

### Session Info & Monitoring

### `getSessionUploadInfoAsFlow`

Observe the upload stage of a session (Uploading, Processing, Completed).

```kotlin theme={null}
suspend fun getSessionUploadInfoAsFlow(sessionId: String): Flow<VoiceTransactionStage>?

```

### `getVoiceActivityFlow`

Flow for real-time voice activity (speech detection, amplitude).

```kotlin theme={null}
fun getVoiceActivityFlow(): Flow<VoiceActivityData>?

```

### `getAudioQualityFlow`

Flow for real-time audio quality metrics (STOI, PESQ, SI-SDR).

```kotlin theme={null}
fun getAudioQualityFlow(): Flow<AudioQualityMetrics?>?

```

### Configuration & Templates

### `getTemplates`

Get available output templates.

```kotlin theme={null}
suspend fun getTemplates(): Result<List<TemplateItem>>?

```

### `getUserConfigs`

Get user configuration including supported languages and modes.

```kotlin theme={null}
suspend fun getUserConfigs(): Result<UserConfigs>

```

### `updateUserConfigs`

Update user preferences (selected language, mode, etc.).

```kotlin theme={null}
suspend fun updateUserConfigs(selectedUserPreferences: SelectedUserPreferences): Result<Boolean>

```

***

## 4. Error Handling

Errors are returned via `EkaScribeError`.

**Common Error Codes:**

* `SUPPORTED_OUTPUT_FORMATS_COUNT_EXCEEDED`: Max 2 output formats allowed.
* `SUPPORTED_LANGUAGES_COUNT_EXCEEDED`: Max 2 languages allowed.
* `LANGUAGE_LIST_CAN_NOT_BE_EMPTY`
* `OUTPUT_FORMAT_LIST_CAN_NOT_BE_EMPTY`

**Data Class:**

```kotlin theme={null}
data class EkaScribeError(
    val sessionId: String,
    val errorDetails: EkaScribeErrorDetails, // Contains 'message', 'displayMessage', 'code'
    val voiceError: VoiceError
)

```

## 5. Cleanup

Call `releaseResources()` when the SDK is no longer needed (e.g., in `onDestroy` of your host
Activity/Application).

```kotlin theme={null}
Voice2Rx.releaseResources()

```


# EkaScribe TypeScript SDK
Source: https://developer.eka.care/api-sdk/scribe/sdks/ekascribe-ts-sdk

Record consultations in the browser and get structured medical notes back, with a prebuilt widget and session/document utilities.

Capture and process audio in the browser and generate structured medical documentation through Eka Care's voice transcription service.

`@eka-care/ekascribe-ts-sdk` handles microphone capture, voice-activity detection, chunked upload and session lifecycle for you. It also ships a prebuilt recording **Widget**, **session/document utilities** (history, details, documents), and Eka `env` / `clientId` handling.

## Prerequisites

* Node 14+
* `npm` or `yarn`
* Microphone access via browser permissions
* Stable network connectivity
* An access token from Eka Care

## Installation

```bash theme={null}
npm install @eka-care/ekascribe-ts-sdk
# or
yarn add @eka-care/ekascribe-ts-sdk
```

[npm package →](https://www.npmjs.com/package/@eka-care/ekascribe-ts-sdk)

***

## Integration Guide (Step-by-Step)

### Step 1: Initialize the SDK

The SDK uses a **singleton pattern** — `getEkaScribeInstance()` always returns the same instance for a given `env` + `clientId` combination.

`flavour` and `allianceConfig.baseUrl` are both **required**. `flavour` identifies your app variant on every request — Eka Care issues the value to use. Omitting `baseUrl` throws `[EkaScribe] allianceConfig.baseUrl is required` at runtime.

To use Eka Care's hosted scribe service, set `baseUrl` to:

| Environment | `baseUrl` |
| - | - |
| Production | `https://api.eka.care/voice/v1` |
| Development | `https://api.dev.eka.care/voice/v1` |

```ts theme={null}
import { getEkaScribeInstance } from '@eka-care/ekascribe-ts-sdk';
import type { EkaScribeConfig } from '@eka-care/ekascribe-ts-sdk';

const config: EkaScribeConfig = {
  access_token: '<your_access_token>',
  env: 'PROD',                             // 'PROD' | 'DEV'
  flavour: '<your_client_identifier>',               // required — app variant identifier
  clientId: '<your_client_id>',            // optional
  allianceConfig: {
    baseUrl: 'https://api.eka.care/voice/v1',  // required — PROD; see table above
    useWorker: 'auto',                              // optional: true | false | 'auto'
    debug: false,                                   // optional
  },
  sharedWorkerUrl: workerUrl,              // optional
};

const ekascribe = getEkaScribeInstance(config);
```

> [!WARNING]
>
> **Production APIs require a secure (HTTPS) origin.** They will not work from `http://` or `http://localhost` — an insecure origin fails the CORS preflight (the `authorization` header is rejected).
>
> **Recommended:** use **[ngrok](/docs/scribe/resources/local-development-ngrok)** to tunnel your local server over HTTPS and test against production directly. Alternatively, point at the development `baseUrl` (`https://api.dev.eka.care/voice/v1`) which works from plain `localhost`.

**Singleton behaviour:**

* Calling `getEkaScribeInstance()` again with the same config returns the same instance.
* If `env` or `clientId` changes, the old instance is automatically reset.
* If only `access_token` changes, the token is updated without resetting.
* One active recording at a time. Call `endRecording()` or `cancelSession()` before starting a new one.

### Step 2: Register Callbacks

Register callbacks **before** starting a recording — events fire immediately once recording starts.

> [!NOTE]
>
> `onTokenRequired` must **return** the new token as a string. The handler has a **10 second** timeout.

```ts theme={null}
// Token refresh — called automatically on 401
ekascribe.registerCallback('onTokenRequired', async () => {
  const newToken = await myAuthService.refreshToken();
  return newToken; // return the token string (10s timeout)
});

// Upload progress
ekascribe.registerCallback('onUploadEvent', (event) => {
  if (event.type === 'progress') {
    console.log(`Uploaded ${event.data.successCount}/${event.data.totalCount}`);
  }
});

// Recording state + errors
ekascribe.registerCallback('onRecordingStateChange', (event) => {
  console.log('State:', event.type); // 'started' | 'paused' | 'resumed' | 'ended'
});
ekascribe.registerCallback('onError', (event) => {
  console.error(`[${event.error.code}] ${event.error.message}`);
});
```

See [Callbacks](#callbacks) for the full list and payload shapes.

### Step 3: Start Recording

`startRecordingV2()` creates the session, starts the microphone, and begins chunked upload in one call. It returns `TStartRecordingResponse` — check `error_code`, then read the session id from `txn_id`.

```ts theme={null}
const result = await ekascribe.startRecordingV2({
  templates: ['clinical_notes_template'], // required: template IDs (from getConfig → my_templates)
  sessionMode: 'consultation',         // optional: 'consultation' | 'dictation'
  languageHint: ['en', 'hi'],          // optional: input audio language hints. If you're not offering users a language change option in your UI, use ['auto_detect'] for the best results.
  transcriptLanguage: 'en',            // optional: output transcript language
  model: 'pro',                        // optional: 'pro' | 'lite'
  patientDetails: { name: 'John Doe', age: '45', gender: 'male' }, // optional
});

if (result.error_code) {
  console.error(result.error_code, result.message);
  return;
}

const sessionId = result.txn_id!;
```

> [!NOTE]
>
> Use `clinical_notes_template` for testing, or contact Eka Care to create a custom template for your use case. Call [`ekascribe.sessions.getConfig()`](#account-config-getconfig) to list the templates enabled for your account.

### Step 4: Pause / Resume

Optional, during recording. Pausing stops VAD processing — the mic stays open and no new chunks are created.

```ts theme={null}
ekascribe.pauseRecording();
ekascribe.resumeRecording();
```

### Step 5: End Recording

Stops the microphone, flushes the last audio chunk, waits for uploads, and tells the server the session has ended — which **triggers server-side processing**. On `audio_upload_failed`, retry the failed chunks with `retryUploadRecording()`.

```ts theme={null}
const endResult = await ekascribe.endRecording();

if (endResult.error_code === 'audio_upload_failed') {
  await ekascribe.retryUploadRecording(); // retry the failed chunks
}
```

### Step 6: Poll for Results

`getSessionStatus()` returns an `SDKResult` — check `success` before reading `data`.

```ts theme={null}
const status = await ekascribe.getSessionStatus(sessionId, {
  poll: {
    maxAttempts: 60,
    intervalMs: 2000,
    onProgress: (s) => console.log('Status:', s.status),
  },
});

if (status.success) {
  console.log('Templates:', status.data.templates);
  console.log('Transcript:', status.data.transcript);
}
```

### Step 7: Cancel Instead of End (optional)

Stops recording **without** triggering processing.

```ts theme={null}
await ekascribe.cancelSession();            // current session
await ekascribe.cancelSession('session-id'); // or by id
```

### Step 8: Clean Up

`resetInstance()` tears down the singleton — clears state, destroys the widget, removes callbacks. Call `getEkaScribeInstance()` again afterwards to get a fresh instance.

```ts theme={null}
await ekascribe.resetInstance();
```

### Flow Diagram

```
  getEkaScribeInstance({ env, access_token, allianceConfig })
         │
         ▼
  registerCallback()  ────  Set up event handlers before recording
         │
         ▼
  startRecordingV2()  ────  Creates session → starts mic → begins upload
         │                  Returns { txn_id, error_code }
    pause / resume  ──────  Optional during recording
         │
         ├─── cancelSession()  ──  Stop WITHOUT processing
         ▼
  endRecording()  ────────  Stops mic → flushes audio → ends session → triggers processing
         │                  On 'audio_upload_failed' → retryUploadRecording()
         ▼
  getSessionStatus()  ────  Poll until completed/failed
         │
         ▼
  resetInstance()  ───────  Full teardown
```

### Full Example

```ts theme={null}
import {
  getEkaScribeInstance,
  type EkaScribeConfig,
} from '@eka-care/ekascribe-ts-sdk';

// 1. Initialize
const ekascribe = getEkaScribeInstance({
  access_token: token,
  env: 'PROD',
  flavour: '<your_client_identifier>',
  allianceConfig: { baseUrl: 'https://api.eka.care/voice/v1' },
});

// 2. Callbacks
ekascribe.registerCallback('onTokenRequired', async () => await refreshToken());
ekascribe.registerCallback('onError', (e) => showErrorToast(e.error.message));

// 3. Start
const start = await ekascribe.startRecordingV2({
  templates: ['clinical_notes_template'],
  sessionMode: 'consultation',
  languageHint: ['en'],
});
if (start.error_code) return showError(start.message);
const sessionId = start.txn_id!;

// 4. ...user records (pause/resume optional)...

// 5. End
const end = await ekascribe.endRecording();
if (end.error_code === 'audio_upload_failed') {
  await ekascribe.retryUploadRecording();
}

// 6. Results
const status = await ekascribe.getSessionStatus(sessionId, {
  poll: { maxAttempts: 60, intervalMs: 2000 },
});
if (status.success) displayResults(status.data.templates, status.data.transcript);

// 7. Cleanup on unmount
await ekascribe.resetInstance();
```

***

## Important Notes

* **`flavour` is required.** It identifies your app variant on every request. Eka Care issues the value to use.
* **`allianceConfig.baseUrl` is the root for all API calls.** Session creation, audio upload, status polling — everything uses this URL. It is required; omitting it throws at runtime.
* **`access_token` must be a valid Bearer token.** All API requests include `Authorization: Bearer <token>`. If it expires, register `onTokenRequired` to auto-refresh.
* **Register callbacks before `startRecordingV2()`.** Events fire immediately once recording starts — if callbacks aren't registered, you'll miss upload progress and errors.
* **`endRecording()` triggers server processing.** Use `cancelSession()` instead if you don't want processing to happen.
* **Recording methods and status methods report errors differently.** `startRecordingV2()` / `endRecording()` return an `error_code` field; `getSessionStatus()` returns an `SDKResult` you check with `result.success`.
* **One active recording at a time.** Call `endRecording()` or `cancelSession()` before starting a new one.
* **Microphone permission is requested on `startRecordingV2()`.** If denied, you get the `microphone` error code.
* **`resetInstance()` is a full teardown.** It clears state, destroys the widget and removes callbacks. Call `getEkaScribeInstance()` again afterwards.

***

## Bundler Setup (Vite / Webpack / Next.js)

The SDK uses a SharedWorker for background audio uploads. Modern bundlers handle this automatically.

**Vite** — works out of the box.
**Webpack 5** — works out of the box (`new URL(..., import.meta.url)` is natively supported).

**Next.js** — ensure the SDK is used only on the client:

```tsx theme={null}
'use client';

import { getEkaScribeInstance } from '@eka-care/ekascribe-ts-sdk';
```

**Browser (script tag):**

```html theme={null}
<script type="module">
  import { getEkaScribeInstance } from 'https://cdn.jsdelivr.net/npm/@eka-care/ekascribe-ts-sdk/dist/index.mjs';
</script>
```

**SharedWorker URL** — pass `sharedWorkerUrl` in config. Resolve it with the built-in helper:

```ts theme={null}
import { createWorkerBlobUrl } from '@eka-care/ekascribe-ts-sdk';

const workerUrl = await createWorkerBlobUrl();
const ekascribe = getEkaScribeInstance({ /* ... */ sharedWorkerUrl: workerUrl });
// Remember to URL.revokeObjectURL(workerUrl) when done.
```

***

## Prebuilt Widget (zero-UI recording)

The SDK provides an optional pre-built recording UI injected via Shadow DOM — you write zero UI code.

**Step 1:** Enable the widget in config with session defaults and callbacks:

```ts theme={null}
const ekascribe = getEkaScribeInstance({
  access_token: token,
  env: 'PROD',
  flavour: '<your_client_identifier>',
  allianceConfig: { baseUrl: '...' },
  widget: {
    enabled: true,
    orientation: 'horizontal',          // 'horizontal' | 'vertical'
    zIndex: 9999,                       // optional
    position: { bottom: 20, right: 20 }, // optional
    sessionDefaults: {
      input_language: ['en'],
      output_format_template: [{ template_id: 'clinical_notes_template' }],
      model_type: 'pro',
      mode: 'consultation',
    },
    callbacks: {
      onRecordingStart: ({ txn_id }) => {},
      onRecordingStop: ({ txn_id, duration }) => {},
      onProcessingComplete: ({ txn_id, sessionData }) => {
        // sessionData contains templates, transcript, etc.
      },
      onError: ({ error_code, message }) => {},
    },
  },
});
```

**Step 2:** Call `startForPatient()` per patient — the widget appears and the user drives it (pause, resume, stop). Results arrive via callbacks.

```ts theme={null}
await ekascribe.startForPatient({
  txn_id: 'unique-session-id',
  patient_details: {                  // optional
    username: 'John Doe',
    age: 45,
    biologicalSex: 'M',
  },
  additional_data: {},                // optional
});
```

The widget handles `startRecordingV2()`, `pauseRecording()`, `resumeRecording()`, `endRecording()`, and `getSessionStatus()` internally.

**Widget state flow:**

```
COLLAPSED ──> RECORDING ──> PAUSED ──> RECORDING ──> PROCESSING ──> DONE
     ^             │                                       │           │
     │             └──── (user clicks stop) ───────────────┘           │
     │                                                                 │
     └──────────── (user clicks close) ────────────────────────────────┘
                                                   │
                                               ERROR
```

```ts theme={null}
interface WidgetConfig {
  enabled: boolean;
  theme?: 'light' | 'dark';
  zIndex?: number;
  primaryColor?: string;
  position?: { bottom?: number; right?: number; top?: number; left?: number };
  orientation?: 'horizontal' | 'vertical';
  callbacks?: WidgetCallbacks;
  sessionDefaults: {
    input_language: string[];
    output_format_template: { template_id: string; template_name?: string; template_type?: string }[];
    model_type: string;
    mode: string;
  };
}

interface StartForPatientConfig {
  txn_id: string;
  patient_details?: {
    username?: string;
    age?: number;
    biologicalSex?: string;
    mobile?: string;
  };
  additional_data?: Record<string, unknown>;
}

interface WidgetCallbacks {
  onRecordingStart?: (data: { txn_id: string }) => void;
  onRecordingPause?: (data: { txn_id: string; duration: number }) => void;
  onRecordingResume?: (data: { txn_id: string }) => void;
  onRecordingStop?: (data: { txn_id: string; duration: number }) => void;
  onProcessingStart?: (data: { txn_id: string }) => void;
  onProcessingComplete?: (data: { txn_id: string; sessionData: unknown }) => void;
  onError?: (data: { error_code: string; message: string }) => void;
  onWidgetClose?: (data: { txn_id: string }) => void;
}
```

***

## Session & Document Utilities

Helpers for fetching session history, details, and documents.

### `getSessionHistory(request)`

Fetch previous sessions.

```ts theme={null}
const sessions = await ekascribe.sessions.getSessionHistory({
  txn_count: 10,        // number of sessions to fetch
  oid: 'patient-oid',   // optional: filter by patient oid
});
```

### `getSessionDetails(request)`

Detailed info including documents, context, and presigned URLs.

```ts theme={null}
const details = await ekascribe.sessions.getSessionDetails({
  session_id: 'session-id',
  presigned: true,         // include presigned URLs for documents
});

const doc = details.data?.documents[0];
if (doc?.presigned_url) {
  const response = await fetch(doc.presigned_url);
  const content = await response.json();
}
```

> Presigned URLs are temporary — check `presigned_url_expires_at` (epoch) before using. Call `getDocument({ documentId })` for a fresh URL if expired.

### `getDocument(request)`

Fetch a single document by ID (and a fresh presigned URL).

```ts theme={null}
const doc = await ekascribe.documents.getDocument({ documentId: 'document-id' });
if (doc.data?.presigned_url) {
  const response = await fetch(doc.data.presigned_url);
  const content = await response.json();
}
```

### `convertToTemplate(request)`

Re-run a finished session's transcript through a different template to generate an additional output document. Useful when the clinician wants the same consultation rendered as, say, a prescription after it was first generated as clinical notes.

```ts theme={null}
const result = await ekascribe.documents.convertToTemplate({
  txn_id: 'session-id',        // the session/transaction to re-process
  template_id: 'template-id',  // a template_id from sessions.getConfig().my_templates
});

if (result.success) {
  console.log(result.data.status, result.data.message);
} else {
  console.error(result.error);
}
```

Processing is asynchronous — the call returns once the request is accepted. Poll `sessions.getSessionDetails({ session_id, presigned: true })` to pick up the new document once it is ready.

Response: `SDKResult<ProcessTemplateResponse>`

```ts theme={null}
type SDKResult<T> =
  | { success: true; data: T; httpStatus?: number }
  | { success: false; error: ScribeError };

interface ProcessTemplateResponse {
  session_id: string;
  template_id: string;
  status: string;
  message: string;
}
```

### `convertTranscriptionToTemplate(request)`

Generate a document from a transcript against a template. Unlike `convertToTemplate`, which re-processes a session's own stored transcript server-side, this variant lets you pass a `transcript` string explicitly and pick a `target_language` for the output.

```ts theme={null}
const result = await ekascribe.documents.convertTranscriptionToTemplate({
  txn_id: 'session-id',              // required
  template_id: 'template-id',        // optional: defaults to the session's template
  transcript: 'Doctor: ...',         // optional: omit to use the stored transcript
  target_language: 'en',             // optional: output language
});

if (result.status === 'success') {
  console.log(result.document_id);
} else {
  console.error(result.error?.display_message ?? result.message);
}
```

Request: `TPostV1ConvertToTemplateRequest`

```ts theme={null}
type TPostV1ConvertToTemplateRequest = {
  txn_id: string;
  template_id?: string;
  transcript?: string;
  target_language?: string;
};
```

Response: `TPostV1ConvertToTemplateResponse`

```ts theme={null}
type TPostV1ConvertToTemplateResponse = {
  status: 'success' | 'failed';
  message: string;
  txn_id: string;
  template_id: string;
  document_id: string;
  b_id: string;
  status_code: number;
  msg: string;
  error_code?: ERROR_CODE;
  error?: { code: string; message: string; display_message: string };
};
```

### `addSessionContext(request)`

Attach reference material to a session so note generation can draw on it. Both context keys are optional and can be sent together:

* `past_sessions` — IDs of earlier sessions to carry forward.
* `attachments` — document IDs to pull in. `patient_oid` is optional; pass it to scope the document to a specific patient.

```ts theme={null}
await ekascribe.sessions.addSessionContext({
  txn_id: 'session-id',
  context: {
    past_sessions: ['previous-session-id'],
    attachments: [{ id: 'document-id' }],   // patient_oid optional
  },
});
```

Request: `TPatchSessionContextRequest`

```ts theme={null}
type TPatchSessionContextRequest = {
  txn_id: string;
  context: {
    past_sessions?: string[];
    attachments?: { id: string; patient_oid?: string }[];
  };
};
```

Response: `TPatchSessionContextResponse` — `{ status_code, message?, error_code? }`.

### `removeSessionContext(request)`

Detach context previously added with `addSessionContext`. Takes the same shape; list only the entries you want removed.

```ts theme={null}
await ekascribe.sessions.removeSessionContext({
  txn_id: 'session-id',
  context: {
    past_sessions: ['previous-session-id'],
  },
});
```

Request and response types match `addSessionContext`.

### `deleteSession(request)`

Permanently delete a session and its associated data.

```ts theme={null}
const result = await ekascribe.sessions.deleteSession({ txn_id: 'session-id' });
if (result.status_code === 200) {
  console.log('deleted', result.txn_id);
}
```

> [!WARNING]
>
> Deletion is irreversible — the session's audio, transcript, and generated documents are removed. Use `cancelSession(sessionId)` instead when you only want to stop an in-flight recording without discarding data.

Response: `TDeleteTransactionResponse`

```ts theme={null}
type TDeleteTransactionResponse = {
  status_code: number;
  status?: string;
  txn_id?: string;
  message?: string;
  error_code?: ERROR_CODE;
  error?: { code: string; message: string; display_message?: string };
};
```

### `patchSessionStatus(request, sessionId?)`

Update session properties.

```ts theme={null}
await ekascribe.sessions.patchSessionStatus({
  patient_details: { name: 'Jane Doe', age: '30', gender: 'female' },
  additional_data: { notes: 'Follow-up visit' },
  templates: ['soap', 'prescription'],
}, sessionId);
```

### Account config (`getConfig`)

Call `ekascribe.sessions.getConfig()` to fetch your account config: supported languages, output formats, consultation modes, and `my_templates` (the valid `template_id` values to pass when starting a recording). `clinical_notes_template` is a ready-to-use testing template; contact Eka Care for a custom one.

```ts theme={null}
const config = await ekascribe.sessions.getConfig();
config.data?.my_templates.forEach((t) => console.log(t.id, t.name));
```

Response: `TGetConfigV2Response`

```ts theme={null}
type TGetConfigV2Response = {
  data?: {
    supported_languages: TGetConfigItem[];
    supported_output_formats: TGetConfigItem[];
    consultation_modes: TGetConfigItem[];
    max_selection: {
      supported_languages: number;
      supported_output_formats: number;
      consultation_modes: number;
    };
    settings: TConfigSettings;
    my_templates: { id: string; name: string }[];   // valid template_id values for your account
    user_details: {
      uuid: string;
      fn: string;
      mn: string;
      ln: string;
      dob: string;
      gen: 'F' | 'M' | 'O';
      s: string;
      'w-id': string;
      'w-n': string;
      'b-id': string;
      is_paid_doc: boolean;
      is_eka_doc: boolean;
      oid: string;
    };
    selected_preferences?: TSelectedPreferences;
    clinic_name?: string;
    specialization?: string;
    emr_name?: string;
    microphone_permission_check?: boolean;
    consult_language?: string[];
    contact_number?: string;
    onboarding_step?: string;
    header?: TConfigHeaderFooter;
    footer?: TConfigHeaderFooter;
  };
  message?: string;
  status_code: number;
};
```

### Discovery

`ekascribe.sessions.getDiscoveryDocument()` returns what the server supports — models, languages, upload methods and audio formats.

***

## Pre-recorded Audio Upload

Upload a pre-recorded audio file instead of live recording, for non-real-time flows.

1. Create session via `ekascribe.sessions.createSession()`
2. Upload audio via `processPreRecordedAudio()`
3. End session via `ekascribe.sessions.endSession()`

```ts theme={null}
const result = await ekascribe.processPreRecordedAudio({
  uploadUrl: session.upload_url,       // from createSession response
  audioFile: audioBlob,                // File or Blob
});
```

***

## Authentication

The token you pass at init is used for every request. Two ways to keep it fresh:

**Automatic (recommended)** — register `onTokenRequired`; the SDK calls it on a 401 and retries the failed request:

```ts theme={null}
ekascribe.registerCallback('onTokenRequired', async () => await refreshToken());
```

**Manual** — `updateAuthTokens()` propagates a new token to all internal transports and the worker:

```ts theme={null}
ekascribe.updateAuthTokens({ access_token: 'new-token' });
```

> If you have `onTokenRequired` registered, the SDK handles 401s automatically. You only need `updateAuthTokens()` for proactive token rotation (e.g. before expiry).

***

## Configuration

```ts theme={null}
interface EkaScribeConfig {
  access_token?: string;          // Bearer token for authentication
  env: 'PROD' | 'DEV';           // Environment
  flavour: string;                // Required — app variant identifier issued by Eka Care
  clientId?: string;              // Your client identifier
  mode?: 'http' | 'ipc';         // Transport mode (default: 'http')
  ipcBridge?: IpcBridge;          // Required when mode is 'ipc' (Electron apps)
  enableTracking?: boolean;       // Enable internal analytics tracking
  sharedWorkerUrl?: string;       // URL to worker.bundle.js for background uploads
  allianceConfig?: {
    baseUrl?: string;             // Scribe service URL (required)
    useWorker?: boolean | 'auto'; // SharedWorker: true | false | 'auto' (default: 'auto')
    debug?: boolean;              // Enable debug logging (default: false)
  };
  widget?: WidgetConfig;          // Widget configuration — see Prebuilt Widget
}
```

## Recording Options

Passed to `startRecordingV2()`:

```ts theme={null}
interface StartRecordingV2Options {
  templates: string[];                   // Template IDs for extraction (required)
  model?: string;                        // 'pro' | 'lite'
  languageHint?: string[];               // Language codes for audio input
  transcriptLanguage?: string;           // Language code for transcript output
  uploadType?: string;                   // 'chunked' (default) | 'single'
  sessionMode?: string;                  // 'consultation' | 'dictation'
  patientDetails?: PatientDetails;       // Patient info
}
```

***

## API Reference

### Instance lifecycle

| Method | Returns | Description |
| - | - | - |
| `getEkaScribeInstance(config)` | `EkaScribe` | Get (or create) the singleton instance for an `env` + `clientId`. |
| `resetInstance()` | `Promise<void>` | Full teardown — clears state, destroys the widget, removes callbacks. |

### Recording

| Method | Returns | Description |
| - | - | - |
| `startRecordingV2(options)` | `TStartRecordingResponse` | Create session + start mic + begin upload. |
| `pauseRecording()` | `void` | Pause VAD (mic stays open, no chunks created). |
| `resumeRecording()` | `void` | Resume VAD processing. |
| `endRecording()` | `TEndRecordingResponse` | Stop mic, flush audio, wait for uploads, end session (triggers processing). |
| `retryUploadRecording()` | — | Retry chunks that failed to upload. |
| `processPreRecordedAudio({ uploadUrl, audioFile })` | — | Upload a pre-recorded file instead of live recording. |

### Session

| Method | Returns | Description |
| - | - | - |
| `getSessionStatus(sessionId?, options?)` | `SDKResult<GetSessionStatusResponse>` | Get status. Supports `poll` and `templateId` options. |
| `cancelSession(sessionId?)` | — | Cancel session (stops recorder, no server processing). |
| `sessions.createSession(request)` | — | Create a session without starting a recording. |
| `sessions.endSession()` | — | End a session explicitly (used with pre-recorded audio). |
| `sessions.getSessionHistory(request)` | — | Fetch previous sessions. |
| `sessions.getSessionDetails(request)` | — | Session metadata, documents, presigned URLs. |
| `sessions.patchSessionStatus(request, sessionId?)` | — | Patch session (patient details, templates, etc.). |
| `sessions.getConfig()` | `TGetConfigV2Response` | Account config, including `my_templates`. |
| `sessions.deleteSession(request)` | `TDeleteTransactionResponse` | Permanently delete a session and its data. |
| `sessions.addSessionContext(request)` | `TPatchSessionContextResponse` | Attach past sessions / attachments as context. |
| `sessions.removeSessionContext(request)` | `TPatchSessionContextResponse` | Detach previously added context. |
| `sessions.getDiscoveryDocument()` | — | Server capabilities (models, languages, upload methods). |

### Documents

| Method | Returns | Description |
| - | - | - |
| `documents.getDocument(request)` | `TPostV1DocumentResponse` | Fetch a document by ID with a fresh presigned URL. |
| `documents.convertToTemplate(request)` | `SDKResult<ProcessTemplateResponse>` | Re-process a session's transcript with another template. |
| `documents.convertTranscriptionToTemplate(request)` | `TPostV1ConvertToTemplateResponse` | Generate a document from a supplied transcript, with optional target language. |

### Widget

| Method | Description |
| - | - |
| `startForPatient(config)` | Show the widget and start a session for one patient. Requires `widget.enabled: true`. |

### Auth

| Method | Description |
| - | - |
| `updateAuthTokens({ access_token })` | Update the Bearer token. Propagates to transports and the worker. |

***

## Callbacks

Register with `ekascribe.registerCallback(name, handler)`.

| Callback | Payload | Description |
| - | - | - |
| `onRecordingStateChange` | `RecordingStateChangeEvent` | Recording started, paused, resumed, or ended. |
| `onAudioEvent` | `AudioEvent` | Speech detection, silence warnings, chunk ready. |
| `onUploadEvent` | `UploadEvent` | Upload progress and failures. |
| `onSessionEvent` | `SessionEvent` | Session created, ended, status updates. |
| `onError` | `ErrorEvent` | VAD, worker, transport, or validation errors. |
| `onTokenRequired` | — | 401 received — **return** the new token string (10s timeout). |

### Payload shapes

```ts theme={null}
// onRecordingStateChange
interface RecordingStateChangeEvent {
  type: 'started' | 'paused' | 'resumed' | 'ended';
  timestamp: string;
  data?: any;
}

// onAudioEvent — discriminated union by `type`
type AudioEvent =
  | { type: 'user_speech';      timestamp: string; data: { isSpeaking: boolean } }
  | { type: 'silence_warning';  timestamp: string; data: { durationMs: number } }
  | { type: 'chunk_ready';      timestamp: string; data: { chunkIndex: number; fileName: string; chunkData: Uint8Array[] } }
  | { type: 'frame_processed';  timestamp: string; data: { isSpeech: number; notSpeech: number; frame: Float32Array; duration: number } };

// onUploadEvent
type UploadEvent =
  | { type: 'progress'; timestamp: string; data: { successCount: number; totalCount: number } }
  | { type: 'failed';   timestamp: string; data: { fileName: string; error: string } }
  | { type: 'retry';    timestamp: string; data: { fileName: string; attempt: number } };

// onSessionEvent
type SessionEvent =
  | { type: 'created';        timestamp: string; data: CreateSessionResponse }
  | { type: 'ended';          timestamp: string; data: EndSessionResponse }
  | { type: 'discarded';      timestamp: string; data: { sessionId: string | null; reason: 'cleared' | 'cancelled' | 'reset' } }
  | { type: 'status_update';  timestamp: string; data: GetSessionStatusResponse }
  | { type: 'partial_result'; timestamp: string; data: any };

// onError
interface ErrorEvent {
  type: 'vad_error' | 'worker_error' | 'transport_error' | 'validation_error';
  timestamp: string;
  error: { code: string; message: string; details?: any };
}

// onTokenRequired — return the token, do not call resolve()
type TokenRequiredHandler = () => Promise<string>;
```

***

## Request / Response Types

### Recording responses

```ts theme={null}
interface TStartRecordingResponse {
  txn_id?: string;      // session id — present on success
  error_code?: string;  // see Error Codes below — present on failure
  message?: string;     // human-readable error message
}

interface TEndRecordingResponse {
  error_code?: string;  // e.g. 'audio_upload_failed'
  message?: string;
}
```

### Session

```ts theme={null}
interface CreateSessionResponse {
  session_id: string;
  status: SessionStatus;
  created_at: string;
  expires_at: string;
  upload_url: string;
  patient_details?: PatientDetails;
}

interface EndSessionResponse {
  session_id: string;
  status: SessionStatus;
  message: string;
  audio_files_received: number;
  audio_files: string[];
}

interface GetSessionStatusResponse {
  session_id: string;
  status: SessionStatus;
  created_at: string;
  expires_at?: string | null;
  expired_at?: string | null;
  completed_at?: string | null;
  model_used?: string | null;
  language_detected?: string | null;
  audio_files_received: number;
  audio_files: string[];
  audio_files_processed?: number;
  additional_data: Record<string, any>;
  templates?: TemplateEntry[];           // { [templateId]: { status, data, fhir, error, ... } }
  transcript?: string;
  processing_errors?: ProcessingError[];
  error?: { code: string; message: string; details?: Record<string, any> };
  patient_details?: PatientDetails;
  message?: string;
}

interface PatientDetails {
  oid?: string;
  name?: string;
  age?: string;
  gender?: string;
  mobile?: number;
}

interface PollOptions {
  maxAttempts?: number;
  intervalMs?: number;
  onProgress?: (status: GetSessionStatusResponse) => void;
  signal?: AbortSignal;
}
```

***

## Error Handling

The SDK reports errors two ways, depending on the method.

**Recording methods** (`startRecordingV2`, `endRecording`) return an `error_code` field:

```ts theme={null}
const result = await ekascribe.startRecordingV2({ templates: ['soap'] });

if (result.error_code) {
  console.error(result.error_code, result.message);
  return;
}
```

**Status methods** (`getSessionStatus`) return an `SDKResult<T>` — errors are returned, not thrown:

```ts theme={null}
type SDKResult<T> =
  | { success: true; data: T }
  | { success: false; error: ScribeError };
```

```ts theme={null}
const status = await ekascribe.getSessionStatus(sessionId);

if (!status.success) {
  console.error(status.error.code, status.error.message);
  return;
}

console.log(status.data.transcript);
```

### Error Codes

| Error Code | Description |
| - | - |
| `microphone` | Microphone access error (permission denied or unavailable) |
| `txn_init_failed` | Failed to initialize session |
| `txn_limit_exceeded` | Maximum concurrent sessions exceeded |
| `internal_server_error` | Unexpected server-side error |
| `end_recording_failed` | Failed to end recording |
| `audio_upload_failed` | Audio file upload to server failed |
| `txn_commit_failed` | Commit call failed |
| `txn_status_mismatch` | Invalid operation for current session state |
| `network_error` | Network connectivity issue |
| `unknown_error` | Unclassified error |
| `unauthorized` | Authentication failed (invalid or expired token) |
| `forbidden` | Insufficient permissions |

***

## Deprecated Methods

These methods are from older SDK versions. They still work but are not recommended for new integrations.

| Deprecated Method | Use Instead |
| - | - |
| `initTransaction()` + `startRecording()` | `startRecordingV2()` |
| `getTemplateOutput()` | `getSessionStatus()` with polling |
| `getOutputTranscription()` | `getSessionStatus()` with polling |
| `commitTransactionCall()` | Handled automatically by `endRecording()` |
| `stopTransactionCall()` | Handled automatically by `endRecording()` |

***

## Source and specification

* [EkaScribe TS SDK](https://github.com/eka-care/eka-js-sdk) — source for `@eka-care/ekascribe-ts-sdk`


# iOS SDK
Source: https://developer.eka.care/api-sdk/scribe/sdks/ios-sdk



# EkaScribe iOS SDK

A Swift package for voice-to-prescription functionality with audio recording and real-time transcription capabilities for medical consultation applications.

## Overview

EkaScribe empowers healthcare applications with advanced voice recording and transcription capabilities. It provides a seamless integration for medical consultation workflows, enabling doctors to record patient interactions and automatically generate prescriptions through AI-powered voice analysis.

### Getting Started

1. **Install** the package via Swift Package Manager
2. **Configure** authentication and doctor information at app launch
3. **Initialize** `VoiceToRxViewModel` in your view
4. **Start recording** with your desired templates and languages
5. **Handle results** when processing completes

The SDK requires **iOS 17.0+** and provides a simple, straightforward API for voice-to-prescription functionality.

### Key Features

* &#x20;**Voice Activity Detection (VAD)** - Intelligent audio recording with automatic speech detection
* &#x20;**Real-time Transcription** - Live audio-to-text conversion during consultations
* &#x20;**Medical Context Aware** - Specialized for healthcare terminology and prescription generation
* &#x20;**Session Management** - Complete recording session lifecycle management
* &#x20;**Cloud Integration** - Automatic audio upload and processing
* &#x20;**Template Support** - Customizable output formats (SOAP notes, prescriptions, etc.)

## Table of Contents

* [Requirements](#requirements)
* [Installation](#installation)
* [Integration Guide](#integration-guide)
* [Core Components](#core-components)
* [Configuration](#configuration)
* [Recording Management](#recording-management)
* [Template Management](#template-management)
* [Session History](#session-history)
* [Result Management](#result-management)
* [Error Handling](#error-handling)
* [API Reference](#api-reference)

## Requirements

> **&#x20;Important**: This SDK requires iOS 17.0 or later.

* **iOS**: 17.0+
* **Swift**: 5.9+
* **Xcode**: 15.0+
* **Sdk Version**: 1.3.5+

### System Permissions

Add the following permissions to your app's `Info.plist`:

```xml theme={null}
<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access to record medical consultations</string>
<key>NSLocalNetworkUsageDescription</key>
<string>This app needs network access to upload and process audio recordings</string>
```

## Installation

### Swift Package Manager

Add EkaScribe to your project using Swift Package Manager:

1. In Xcode, select **File → Add Package Dependencies**
2. Enter the repository URL:
   ```
   https://github.com/eka-care/EkaVoiceToRx.git
   ```
   Or use SSH:
   ```
   git@github.com:eka-care/EkaVoiceToRx.git
   ```
3. Choose the version or branch
4. Add to your target

### Package.swift

```swift theme={null}
dependencies: [
    .package(url: "https://github.com/eka-care/EkaVoiceToRx.git", from: "1.3.5")
]
```

### Import Statement

After adding the package, import it in your Swift files:

```swift theme={null}
import EkaVoiceToRx
```

## Integration Guide

Follow these steps to integrate the SDK into your app:

### Step 1: Configure Authentication and Doctor Information

Set up authentication tokens and doctor information when your app launches. This should be done once at app startup:

```swift theme={null}
import SwiftUI
import EkaVoiceToRx

@main
struct YourApp: App {
    init() {
        configureEkaScribe()
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
    
    private func configureEkaScribe() {
        // 1. Set authentication tokens (required)
        AuthTokenHolder.shared.authToken = "your_auth_token"
        AuthTokenHolder.shared.refreshToken = "your_refresh_token"
        AuthTokenHolder.shared.bid = "your_business_id"
        
        // 2. Configure doctor/user information (required)
        let config = V2RxInitConfigurations.shared
        config.clientId = "your_client_id"
        config.ownerName = "Dr. Smith"
        config.ownerOID = "doctor_oid_123"
        config.ownerUUID = "doctor_uuid_456"
    }
}
```

**Important**: Make sure to set authentication tokens and doctor information before making any SDK calls.

### Step 2: Initialize the View Model

Create a `VoiceToRxViewModel` instance in your SwiftUI view or UIKit view controller:

**SwiftUI:**

```swift theme={null}
@StateObject private var viewModel = VoiceToRxViewModel(
    voiceToRxInitConfig: .shared,
    voiceToRxDelegate: nil
)
```

**UIKit:**

```swift theme={null}
private let viewModel = VoiceToRxViewModel(
    voiceToRxInitConfig: .shared,
    voiceToRxDelegate: nil
)
```

### Step 3: Start Recording

Start a recording session with your desired configuration:

#### Parameters

The `startRecording()` method accepts the following parameters:

* **conversationType** (`VoiceConversationType`): The type of conversation (see [Conversation Types](#conversation-types))

* **inputLanguage** (`[InputLanguageType]`): Array of supported languages (see [Input Languages](#input-languages))

* **templates** (`[OutputFormatTemplate]`): Array of output format templates (see [Template Management](#template-management))

* **modelType** (`ModelType`): The AI model to use for processing (see [Model Types](#model-types))

```swift theme={null}
// Your implementation
private func startRecording() async {
    do {
        // 1. Fetch available templates (recommended)
        // See Template Management section for details on getTemplates API
        // VoiceToRxRepo.shared.getTemplates { result in ... }
        
        // 2. Configure templates
        let outputFormat: [OutputFormatTemplate] = [
            OutputFormatTemplate(
                templateID: "template-id-here",
                templateType: .defaultType,
                templateName: "SOAP Notes"
            )
        ]
        
        // 3. Set patient information (if applicable)
        V2RxInitConfigurations.shared.subOwnerOID = patientOID
        V2RxInitConfigurations.shared.subOwnerName = patientName
        
        // 4. Calling SDK function
        try await viewModel.startRecording(
            conversationType: VoiceConversationType.conversation,
            inputLanguage: [InputLanguageType.english, InputLanguageType.hindi], // If you're not offering users a language change option in your UI, use auto_detect for the best results.
            templates: outputFormat,
            modelType: ModelType.lite
        )
        
        // Successfully started recording
    } catch {
        // Handle errors
        await MainActor.run {
            handleRecordingError(error)
        }
    }
}
```

**Note**: It's recommended to use the `getTemplates()` API first to fetch available templates before creating the `OutputFormatTemplate` array. See the [Template Management](#template-management) section for details.

## Core Components

### VoiceToRxViewModel

The central view model that manages the entire voice recording and processing workflow.

```swift theme={null}
public class VoiceToRxViewModel: ObservableObject {
    @Published public var screenState: RecordConsultationState
    
    public init(
        voiceToRxInitConfig: V2RxInitConfigurations,
        voiceToRxDelegate: VoiceToRxDelegate?
    )
}
```

#### Recording States

The `screenState` property tracks the current state of the recording session:

```swift theme={null}
public enum RecordConsultationState {
    case retry                          // Ready to retry after error
    case startRecording                 // Initial state, ready to start
    case listening(conversationType: VoiceConversationType) // Currently recording
    case paused                         // Recording paused
    case processing                     // Processing audio/generating prescription
    case resultDisplay(success: Bool, value: String?)  // Results available
    case deletedRecording              // Recording deleted
}
```

#### Conversation Types

```swift theme={null}
public enum VoiceConversationType: String, CaseIterable {
    case conversation = "consultation"  // Doctor-patient conversation
    case dictation                     // Direct prescription dictation
}
```

#### Model Types

```swift theme={null}
public enum ModelType {
    case pro      // High accuracy model
    case lite     // Faster, lighter model
}
```

#### Input Languages

```swift theme={null}
public enum InputLanguageType {
    case english
    case hindi
    case tamil
    case telugu
    case kannada
    case malayalam
    case bengali
    case gujarati
    case marathi
    case punjabi
    case urdu
    case odia
    case assamese
}
```

## Configuration

### App-Level Setup

Configure the SDK when your app launches. This should be done once at app startup:

```swift theme={null}
import SwiftUI
import EkaVoiceToRx

@main
struct YourApp: App {
    init() {
        configureEkaScribe()
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
    
    private func configureEkaScribe() {
        // 1. Set authentication tokens (required)
        AuthTokenHolder.shared.authToken = KeychainHelper.fetchAuthToken()
        AuthTokenHolder.shared.refreshToken = KeychainHelper.fetchRefreshToken()
        AuthTokenHolder.shared.bid = JWTDecoder.shared.businessId
        
        // 2. Configure doctor/user information (required)
        let config = V2RxInitConfigurations.shared
        config.clientId = "your_client_id"
        config.ownerName = "Dr. Smith"
        config.ownerOID = "doctor_oid_123"
        config.ownerUUID = "doctor_uuid_456"
        
        // 3. Set up data container (optional - only if using SwiftData)
        // config.modelContainer = SwiftDataRepoContext.modelContext.container
    }
}
```

**Important**: Make sure to set authentication tokens and doctor information before making any SDK calls.

### Session-Specific Configuration

Before starting a recording session, configure patient-specific information. This should be done each time you start a new recording:

```swift theme={null}
// Set patient information for the current session (required before recording)
V2RxInitConfigurations.shared.subOwnerOID = selectedPatientOid
V2RxInitConfigurations.shared.subOwnerName = patientName

// Optional: Set appointment ID for context
V2RxInitConfigurations.shared.appointmentID = appointmentID
```

**Note**: Patient information can be set to empty strings if not applicable:

```swift theme={null}
V2RxInitConfigurations.shared.subOwnerOID = ""
V2RxInitConfigurations.shared.subOwnerName = ""
```

### Configuration Properties

```swift theme={null}
public class V2RxInitConfigurations {
    public static let shared: V2RxInitConfigurations
    
    // Doctor/User Information
    public var ownerName: String?          // Doctor name
    public var ownerOID: String?            // Doctor OID
    public var ownerUUID: String?            // Doctor UUID
    public var clientId: String?             // Client identifier
    
    // Patient Information (set per session)
    public var subOwnerOID: String?         // Patient OID
    public var subOwnerName: String?        // Patient name
    
    // Optional Context
    public var appointmentID: String?       // Appointment identifier
    
    // Data Storage
    public var modelContainer: ModelContainer?  // SwiftData container (optional)
}
```

### Authentication

Set authentication tokens before making any SDK calls:

```swift theme={null}
AuthTokenHolder.shared.authToken = "your_auth_token"
AuthTokenHolder.shared.refreshToken = "your_refresh_token"
AuthTokenHolder.shared.bid = "your_business_id"
```

## Recording Management

### Starting Recording

#### Parameters

The `startRecording()` method accepts the following parameters:

* **conversationType** (`VoiceConversationType`): The type of conversation (see [Conversation Types](#conversation-types))

* **inputLanguage** (`[InputLanguageType]`): Array of supported languages (see [Input Languages](#input-languages))

* **templates** (`[OutputFormatTemplate]`): Array of output format templates (see [Template Management](#template-management))

* **modelType** (`ModelType`): The AI model to use for processing (see [Model Types](#model-types))

```swift theme={null}
// Start recording
try await viewModel.startRecording(
conversationType: VoiceConversationType.conversation,
inputLanguage: [InputLanguageType.english, InputLanguageType.hindi],
templates: templates,
modelType: ModelType.lite
 )
```

**Note**: It's recommended to use the `getTemplates()` API first to fetch available templates before creating the `OutputFormatTemplate` array. See the [Template Management](#template-management) section for details.

### Pausing and Resuming

```swift theme={null}
// Pause recording
viewModel.pauseRecording()

// Resume recording
do {
    try viewModel.resumeRecording()
} catch {
    // Handle resume error
    print("Failed to resume: \(error.localizedDescription)")
}
```

### Stopping Recording

```swift theme={null}
// Stop recording and process
Task {
    do {
        try await viewModel.stopRecording()
        // The viewModel will transition to .processing, then .resultDisplay
    } catch {
        // Handle error
        print("Failed to stop recording: \(error.localizedDescription)")
    }
}
```

### Handling Results

Monitor the `screenState` for result availability. Results are automatically provided when processing completes:

```swift theme={null}
case .resultDisplay(success: let success, value: let value):
    if success {
        // Get the result text (base64 encoded)
        let base64EncodedText = value ?? ""
        
        // Decode base64 to get the actual result
        guard let decodedData = Data(base64Encoded: base64EncodedText),
              let resultText = String(data: decodedData, encoding: .utf8) else {
            showError("Failed to decode result")
            return
        }
        
        // Get the session ID for future reference
        let sessionID = viewModel.sessionID?.uuidString ?? ""
        // Display results to user
        showResults(resultText, sessionID: sessionID)
    } else {
        // Handle error
        showError("Failed to process recording")
    }
```

**Note**: The `value` parameter contains base64-encoded formatted output based on your selected template. You need to decode it before displaying to users. For more detailed results including multiple template outputs, use `VoiceToRxRepo.shared.fetchResultStatusResponse()`.

## Template Management

### Fetching Available Templates

Use `VoiceToRxRepo` to fetch available templates:

```swift theme={null}
import EkaVoiceToRx

VoiceToRxRepo.shared.getTemplates { result in
    switch result {
    case .success(let response):
        let templates = response.items
        // Use templates
        break
    case .failure(let error):
        print("Failed to fetch templates: \(error.localizedDescription)")
        break
    }
}
```

### Updating Favorite Templates

Update user's favorite templates configuration:

```swift theme={null}
let templateIDs = ["template-id-1", "template-id-2"]

VoiceToRxRepo.shared.updateConfig(
    templates: templateIDs
) { result in
    switch result {
    case .success:
        print("Templates updated successfully")
    case .failure(let error):
        print("Failed to update: \(error.localizedDescription)")
    }
}
```

### Using Templates in Recording

Pass templates when starting a recording:

```swift theme={null}
// Your implementation
private func startRecordingWithTemplates() async {
    do {
        // 1. Fetch available templates first (recommended)
        // VoiceToRxRepo.shared.getTemplates { result in ... }
        
        // 2. Configure templates
        let templates: [OutputFormatTemplate] = [
            OutputFormatTemplate(
                templateID: "template-id",
                templateType: .defaultType,
                templateName: "Template Name"
            )
        ]
        
        // 3. Calling SDK function
        try await viewModel.startRecording(
            conversationType: VoiceConversationType.conversation,
            inputLanguage: [InputLanguageType.english],
            templates: templates,
            modelType: ModelType.pro
        )
    } catch {
        // Handle error
        await MainActor.run {
            handleError(error)
        }
    }
}
```

## Session History

### Fetching Session History

Retrieve past recording sessions:

```swift theme={null}
VoiceToRxRepo.shared.getEkaScribeHistory { result in
    switch result {
    case .success(let response):
        let sessions = response.data
        // Display sessions
        break
    case .failure(let error):
        print("Failed to fetch history: \(error.localizedDescription)")
        break
    }
}
```

## Result Management

### Fetching Full Result Response

Get the complete result response with selected template outputs:

```swift theme={null}
VoiceToRxRepo.shared.fetchResultStatusResponse(sessionID: sessionID) { result in
    switch result {
    case .success(let response):
        // Note: All values in the response are base64 encoded and need to be decoded before display
        // response.data.templateResults.custom - custom template results (base64 encoded)
        // response.data.templateResults.transcript - transcript results (base64 encoded)
        // response.data.output - general output (base64 encoded)
        // response.data.audioMatrix - audio quality metrics
        
        // Example: Decoding a result value
        if let encodedValue = response.data?.templateResults?.custom?.first?.value,
           let decodedData = Data(base64Encoded: encodedValue),
           let decodedText = String(data: decodedData, encoding: .utf8) {
            // Use decodedText for display
            print("Decoded result: \(decodedText)")
        }
        break
    case .failure(let error):
        print("Failed to fetch response: \(error.localizedDescription)")
        break
    }
}
```

**Note**: The `value` parameter returned by `fetchResultStatus` is base64 encoded and must be decoded before displaying to users.

### Switching Templates

Switch the output format for an existing session:

```swift theme={null}
VoiceToRxRepo.shared.switchTemplate(
    templateID: newTemplateID,
    sessionID: sessionID
) { result in
    switch result {
    case .success(let response):
        // Updated response with new template output
        break
    case .failure(let error):
        print("Failed to switch template: \(error.localizedDescription)")
        break
    }
}
```

### Updating Results

Update edited content back to the server:

```swift theme={null}
let request = UpdateResultRequest(
    // Configure request with updated content
)

VoiceToRxRepo.shared.updateResult(
    sessionID: sessionID,
    request: request
) { result, errorStatus in
    switch result {
    case .success:
        print("Result updated successfully")
    case .failure(let error):
        print("Failed to update: \(error.localizedDescription)")
    }
}
```

## Error Handling

### Common Errors

The SDK provides specific error types:

```swift theme={null}
public enum EkaScribeError: Error {
    case freeSessionLimitReached
    case microphonePermissionDenied
    case microphoneIsInUse
    case vadDetectorFailed
    case noSessionId
    case audioSessionSetupFailed
}
```

### Error Handling Example

Here's a complete example of handling errors when starting a recording:

```swift theme={null}
// Your implementation
private func handleRecording() async {
    do {
        let templates: [OutputFormatTemplate] = [
            // Your templates
        ]
        
        // Calling SDK function
        try await viewModel.startRecording(
            conversationType: VoiceConversationType.conversation,
            inputLanguage: [InputLanguageType.english, InputLanguageType.hindi],
            templates: templates,
            modelType: ModelType.lite
        )
        
        // Successfully started recording
    } catch let error as EkaScribeError {
        // Handle SDK-specific errors
        await MainActor.run {
            switch error {
            case .freeSessionLimitReached:
                // Show upgrade prompt
                showUpgradeAlert()
            case .microphonePermissionDenied:
                // Show permission alert
                showPermissionAlert()
            case .microphoneIsInUse:
                // Show microphone in use alert
                showMicrophoneInUseAlert()
            default:
                // Handle other SDK-specific errors
                showGenericError(error.localizedDescription)
            }
        }
    } catch {
        // Handle generic errors (network, API, etc.)
        await MainActor.run {
            showGenericError(error.localizedDescription)
        }
    }
}
```

## API Reference

### VoiceToRxViewModel

#### Properties

```swift theme={null}
@Published public var screenState: RecordConsultationState
```

#### Methods

```swift theme={null}
// Core recording methods
public func startRecording(
    conversationType: VoiceConversationType,
    inputLanguage: [InputLanguageType],
    templates: [OutputFormatTemplate],
    modelType: ModelType
) async throws

public func stopRecording() async throws
public func pauseRecording()
public func resumeRecording() throws

// Session management
public func deleteRecording(id: UUID)
public func clearSession()
public func retryIfNeeded()
```

### VoiceToRxRepo

#### Template Management

```swift theme={null}
public func getTemplates(completion: @escaping (Result<TemplateResponse, Error>) -> Void)
public func updateConfig(templates: [String], completion: @escaping (Result<Void, Error>) -> Void)
```

#### Session History

```swift theme={null}
public func getEkaScribeHistory(completion: @escaping (Result<ScribeHistoryResponse, Error>) -> Void)
```

#### Result Management

```swift theme={null}
public func fetchResultStatusResponse(
    sessionID: String,
    completion: @escaping (Result<VoiceToRxStatusResponse, Error>) -> Void
)
// Note: All response values are base64 encoded. Decode before displaying.

public func switchTemplate(
    templateID: String,
    sessionID: String,
    completion: @escaping (Result<VoiceToRxStatusResponse, Error>) -> Void
)

public func updateResult(
    sessionID: String,
    request: UpdateResultRequest,
    completion: @escaping (Result<Void, ErrorStatus>) -> Void
)
```

### Configuration Classes

#### V2RxInitConfigurations

```swift theme={null}
public class V2RxInitConfigurations {
    public static let shared: V2RxInitConfigurations
    
    public var modelContainer: ModelContainer?
    public var clientId: String?
    public var ownerName: String?
    public var ownerOID: String?
    public var ownerUUID: String?
    public var subOwnerOID: String?
    public var subOwnerName: String?
    public var appointmentID: String?
}
```

#### AuthTokenHolder

```swift theme={null}
public class AuthTokenHolder {
    public static let shared: AuthTokenHolder
    
    public var authToken: String?
    public var refreshToken: String?
    public var bid: String?
}
```

### Data Models

#### OutputFormatTemplate

```swift theme={null}
public struct OutputFormatTemplate {
    public let templateID: String
    public let templateType: TemplateType
    public let templateName: String
    
    public init(
        templateID: String,
        templateType: TemplateType,
        templateName: String
    )
}
```

#### VoiceToRxStatusResponse

```swift theme={null}
public struct VoiceToRxStatusResponse {
    public let data: VoiceToRxStatusData?
}

public struct VoiceToRxStatusData {
    public let templateResults: TemplateResults?
    public let output: [VoiceToRxOutput]?
    public let audioMatrix: AudioMatrix?
}

public struct TemplateResults {
    public let custom: [VoiceToRxOutput]?
    public let transcript: [VoiceToRxOutput]?
}
```

## Best Practices

### Memory Management

```swift theme={null}
class RecordingViewController: UIViewController {
    private var viewModel: VoiceToRxViewModel?
    
    deinit {
        // Clean up resources
        viewModel?.clearSession()
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        
        // Pause recording when leaving screen
        if case .listening = viewModel?.screenState {
            viewModel?.pauseRecording()
        }
    }
}
```

### State Management

Always observe `screenState` changes to keep your UI in sync:

```swift theme={null}
.onChange(of: viewModel.screenState) { oldState, newState in
    // Update UI based on state
    handleStateChange(newState)
}
```

### Error Handling

Always handle errors from async operations using try-catch:

```swift theme={null}
// Your implementation
private func startRecording() async {
    do {
        let templates: [OutputFormatTemplate] = [
            // Your templates
        ]
        
        // Calling SDK function
        try await viewModel.startRecording(
            conversationType: VoiceConversationType.conversation,
            inputLanguage: [InputLanguageType.english, InputLanguageType.hindi],
            templates: templates,
            modelType: ModelType.lite
        )
        
        // Successfully started recording
    } catch {
        // Handle error appropriately
        await MainActor.run {
            showError(error)
        }
    }
}
```

## Troubleshooting

### Microphone Permission Issues

If microphone permission is denied:

1. Check `Info.plist` has `NSMicrophoneUsageDescription`
2. Request permission programmatically if needed
3. Guide users to Settings if permission was previously denied

### Session Creation Failures

If sessions fail to create:

1. Verify `ownerOID` is set in `V2RxInitConfigurations.shared`
2. Check `AuthTokenHolder.shared.authToken` is valid
3. Ensure network connectivity
4. Check for free session limit if applicable

### Result Not Available

If results are not available after processing:

1. Check `screenState` transitions to `.resultDisplay`
2. Verify session ID is available: `viewModel.sessionID`
3. Use `VoiceToRxRepo.shared.fetchResultStatusResponse` to get full response
4. Check network connectivity for result retrieval


# Java SDK
Source: https://developer.eka.care/api-sdk/scribe/sdks/java-sdk



# Eka Care Ekascribe Java SDK Integration

This guide explains how to integrate the Eka Care Ekascribe Java SDK.

## Overview

Eka Care provides an Ekascribe service that allows you to transcribe audio files into structured medical data. The Java SDK simplifies this integration process.

## Quick Start

The integration process follows these main steps:

1. Set up webhook registration (one-time setup)
2. Install the SDK
3. Implement authentication
4. Upload audio files
5. Process the webhook callback
6. Retrieve and parse the Ekascribe results

## Prerequisites

* Java 8 or higher
* Maven or Gradle for dependency management
* Client credentials (client ID and secret) from Eka Care

## Installation

You can add the Eka Care Java SDK to your project in two ways:

### Option 1: Using dependency management

#### Maven

```xml theme={null}
<dependency>
    <groupId>care.eka</groupId>
    <artifactId>ekacare-java-sdk</artifactId>
    <version>latest-version</version>
</dependency>
```

#### Gradle

```groovy theme={null}
implementation 'care.eka:ekacare-java-sdk:latest-version'
```

### Option 2: Direct download

Download the Eka Java SDK from Maven repository [Here](https://central.sonatype.com/artifact/care.eka/ekacare-java-sdk)

## Available Template IDs

Eka Care supports multiple output templates for different medical documentation needs. Choose the appropriate template ID based on your requirements:

| Template ID | Description | Use Case |
| - | - | - |
| `clinical_notes_template` | Comprehensive clinical notes with structured medical information | General clinical documentation, patient consultations |
| `eka_emr_template` | EMR-compatible format for electronic medical records | Integration with EMR systems |
| `transcript_template` | Basic transcription with minimal structuring | Simple audio-to-text conversion |

## Available model types

| Model Type | Description |
| - | - |
| pro | Our most accurate model |
| lite | More performant model for lower latency |

## Supported Input Languages

Eka Care supports transcription in multiple languages. Specify the appropriate language ID in the `input_language` parameter:

| Language ID | Language Name |
| - | - |
| `en-IN` | English (India) |
| `en-US` | English (United States) |
| `hi` | Hindi |
| `gu` | Gujarati |
| `kn` | Kannada |
| `ml` | Malayalam |
| `ta` | Tamil |
| `te` | Telugu |
| `bn` | Bengali |
| `mr` | Marathi |
| `pa` | Punjabi |

If you're not offering users a language change option in your UI, use `auto_detect` for the best results.

## Step 1: Register Webhook (One-time Setup)

Before using the Ekascribe service, register a webhook to receive notifications when transcription is complete:

```bash theme={null}
curl --request POST \
  --url https://api.eka.care/notification/v1/connect/webhook/subscriptions \
  --header 'Authorization: Bearer <auth_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "event_names": [
      "v2rx.completed"
    ],
    "endpoint": "your-endpoint-url",
    "signing_key": "supersecretkey",
    "protocol": "https"
  }'
```

## Step 2: Authentication

Initialize the client with your credentials and obtain access tokens:

```java theme={null}
import care.eka.EkaCareClient;
import com.fasterxml.jackson.databind.JsonNode;

// Initialize the client
EkaCareClient client = new EkaCareClient("your_client_id", "your_client_secret");

// Login to get tokens
JsonNode tokenResponse = client.getAuth().login();
String accessToken = tokenResponse.get("access_token").asText();
String refreshToken = tokenResponse.get("refresh_token").asText();

// Set access token manually if needed
client.setAccessToken(accessToken);

// Refresh token when needed
JsonNode refreshedTokens = client.getAuth().refreshToken(refreshToken);
String newAccessToken = refreshedTokens.get("access_token").asText();
```

## Step 3: Upload Audio Files

Upload audio files for transcription:

```java theme={null}
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

// Collect all audio files in a list
List<String> audioFiles = new ArrayList<>();
audioFiles.add("<full file path>");
audioFiles.add("<full file path 2>");

// Set your own txn id
String transactionId = "unique_transaction_id";

//Custom keys , you'll get back the exact same in result API
Map<String, Object> extraData = new HashMap<>();
extraData.put("mode", "dictation");
extraData.Put("model_type", "lite");
extraData.put("uhid", "unique_patient_id");
extraData.put("hfid", "unique_health_facility_id");

// Define the output format for the V2RX action
Map<String, Object> outputFormat = new HashMap<>();
outputFormat.put("input_language", Arrays.asList("en-IN", "hi")); // If you're not offering users a language change option in your UI, use "auto_detect" for the best results.

// output template ids
Map<String, Object> templateMap1 = new HashMap<>();
templateMap1.put("template_id", "clinical_notes_template");
templateMap1.put("language_output", "en-IN");
// set true if you need codified data (if out supports that)
templateMap1.put("codification_needed", true);

// Sample second template id
Map<String, Object> templateMap2 = new HashMap<>();
templateMap2.put("template_id", "eka_emr_template");
templateMap2.put("language_output", "en-IN");

outputFormat.put("output_template", Arrays.asList(templateMap1, templateMap2));

// Keep this the same
String action = "ekascribe-v2";

// Upload files
JsonNode responses = client.getV2RX().upload(audioFiles, transactionId, action, extraData, outputFormat);

// Process responses
for (JsonNode response : responses) {
    // Handle response data as needed
}
```

## Step 4: Handle Webhook Callback

When the transcription is complete, Eka Care will send a webhook notification to your registered endpoint. Here's a sample of what you'll receive:

```json theme={null}
{
  "event": "v2rx.completed",
  "data": {
    "transaction_id": "unique_transaction_id",
    "status": "completed",
    "session_id": "unique_transaction_id"
  },
  "timestamp": "2023-07-20T10:30:00Z"
}
```

## Step 5: Retrieve Ekascribe Results

After receiving the webhook notification, retrieve the transcription results:

```java theme={null}
// Get the transactionId from the webhook callback
String transactionId = "unique_transaction_id";  // This comes from the webhook payload
String action = "ekascribe-v2";

// Fetch session status and results
JsonNode sessionStatus = client.getV2RX().getSessionStatus(transactionId, action);

// Sample response structure
'''{
    "data": {
        "output": [
            {
                "template_id": "clinical_notes_template",
                "value": "<base 64 encoded value>",
                "name": "Clinical Notes Template",
                "status": "success",
                "errors": [],
                "warnings": []
            }
        ]
    }
}'''

// Extract and decode the Template data
if (sessionStatus.has("data") &&
        sessionStatus.get("data").has("output") &&
        sessionStatus.get("data").get("output").isArray() &&
        sessionStatus.get("data").get("output").size() > 0) {

    JsonNode outputNode = sessionStatus.get("data").get("output");
    Integer step = 0;
    for (JsonNode node : outputNode) {
        if (node.has("value")) {
            step++;
            String templateId = node.get("template_id").asText();
            String templateName = node.get("name").asText();
            String encodedValue = node.get("value").asText();
            byte[] decodedBytes = Base64.getDecoder().decode(encodedValue);
            String templateJson = new String(decodedBytes);
            System.out.println("Template: " + templateName + " (" + templateId + ")");
            System.out.println("Decoded Data " + step + " :" + templateJson);
        } else {
            System.out.println("No value found in output node "+ step+ " :"+ node.toPrettyString());
        }
    }

}
```

## Complete Example

Here's a complete example integrating all the above steps:

```java theme={null}

import care.eka.EkaCareClient;
import com.fasterxml.jackson.databind.JsonNode;

import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Arrays;
import java.util.Base64;

public class EkascribeIntegrationExample {
    public static void main(String[] args) {
        try {
            // Initialize the client
            EkaCareClient client = new EkaCareClient("your_client_id", "your_client_secret");
            
            // Authenticate
            authenticateClient(client);
            
            // Upload audio files
            String transactionId = "unique_transaction_id";
            String action = "ekascribe-v2";

            uploadAudioFiles(client, transactionId, action);
            
            // NOTE: At this point, wait for the webhook callback
            // This would typically be handled by your web server
            
            // Once webhook is received, fetch results
            // The sessionId would come from the webhook payload
            getTranscriptionResults(client, transactionId, action);
            
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    
    private static void authenticateClient(EkaCareClient client) throws IOException {
        JsonNode tokenResponse = client.getAuth().login();

        // Extras
        System.out.println("Access Token: " + tokenResponse.get("access_token").asText());
        System.out.println("Refresh Token: " + tokenResponse.get("refresh_token").asText());

        client.setAccessToken(tokenResponse.get("access_token").asText());

        // Refresh token when needed
        JsonNode refreshedTokens = client.getAuth().refreshToken(tokenResponse.get("refresh_token").asText());
        
        // Extras
        System.out.println("New Access Token: " + refreshedTokens.get("access_token").asText());
    }
    
    private static void uploadAudioFiles(EkaCareClient client, String transactionId, String action) throws IOException {
        // Collect all audio files in a list
        List<String> audioFiles = new ArrayList<>();
        audioFiles.add("<full file path>");
        audioFiles.add("<full file path 2>");

        Map<String, Object> extraData = new HashMap<>();
        extraData.put("mode", "dictation");
        extraData.Put("model_type", "lite");


        //Custom keys , you'll get back the exact same in result API
        extraData.put("uhid", "unique_patient_id"); 
        extraData.put("hfid", "unique_health_facility_id");

        // Define the output format for the V2RX action
        Map<String, Object> outputFormat = new HashMap<>();
        outputFormat.put("input_language", Arrays.asList("en-IN", "hi")); // If you're not offering users a language change option in your UI, use "auto_detect" for the best results.

        // output template ids
        Map<String, Object> templateMap1 = new HashMap<>();
        templateMap1.put("template_id", "clinical_notes_template");
        templateMap1.put("language_output", "en-IN");
        // set true if you need codified data (if out supports that)
        templateMap1.put("codification_needed", true);
        
        // Sample second template id
        Map<String, Object> templateMap2 = new HashMap<>();
        templateMap2.put("template_id", "eka_emr_template");
        templateMap2.put("language_output", "en-IN");
        
        // Add both templates to the output_template list
        outputFormat.put("output_template", Arrays.asList(templateMap1, templateMap2));
        
        List<JsonNode> responses = client.getV2RX().upload(audioFiles, transactionId, action, extraData, outputFormat);
        System.out.println("Upload Responses: " + responses.toString());
    }
    
    private static void getTranscriptionResults(EkaCareClient client, String sessionId, String action) throws IOException {
        JsonNode sessionStatus = client.getV2RX().getSessionStatus(sessionId, action);
        System.out.println("Session Status: " + sessionStatus.toPrettyString());
        
        if (sessionStatus.has("data") &&
                sessionStatus.get("data").has("output") &&
                sessionStatus.get("data").get("output").isArray() &&
                sessionStatus.get("data").get("output").size() > 0) {

            JsonNode outputNode = sessionStatus.get("data").get("output");
            Integer step = 0;
            for (JsonNode node : outputNode) {
                if (node.has("value")) {
                    step++;
                    String templateId = node.get("template_id").asText();
                    String templateName = node.get("name").asText();
                    String encodedValue = node.get("value").asText();
                    byte[] decodedBytes = Base64.getDecoder().decode(encodedValue);
                    String templateJson = new String(decodedBytes);
                    System.out.println("Template: " + templateName + " (" + templateId + ")");
                    System.out.println("Decoded Data " + step + " :" + templateJson);
                } else {
                    System.out.println("No value found in output node "+ step+ " :"+ node.toPrettyString());
                }
            }

        }
    }
}
```

## Additional Resources

* [Eka Care Java SDK Examples Repository](https://github.com/eka-care/eka-java-sdk-examples/)
* [Eka Care Developer Documentation](https://developer.eka.care/)
* [API Reference for Webhooks](https://developer.eka.care/api-sdk/webhooks/register-webhook)
* [API Reference for Ekascribe](https://developer.eka.care/api-sdk/scribe/sessions/overview)

## Troubleshooting

### Common Errors

1. **Authentication Failed**: Verify your client ID and secret are correct
2. **File Upload Failed**: Ensure file paths are valid and files are readable
3. **Webhook Not Received**: Check your endpoint is publicly accessible and correctly registered

### Support

For additional support, contact the Eka Care developer support team at [support@eka.care](mailto:support@eka.care).


# Python SDK (Deprecated)
Source: https://developer.eka.care/api-sdk/scribe/sdks/python-sdk



> [!WARNING]
>
> This legacy `ekacare` Python SDK is **deprecated**. Use the new
> **[Python SDK (`scribe-python-sdk`)](/api-sdk/scribe/sdks/scribe-python-sdk)**,
> built on the [MedScribeAlliance Protocol](/api-sdk/scribe/sessions/overview),
> for new integrations. This page remains for existing users.

# Eka Care Ekascribe Python SDK Integration

This guide explains how to integrate the Eka Care Ekascribe Python SDK.

## Overview

Eka Care provides an Ekascribe service that allows you to transcribe audio files into structured medical data. The Python SDK simplifies this integration process.

## Quick Start

The integration process follows these main steps:

1. Set up webhook registration (one-time setup)
2. Install the SDK
3. Implement authentication
4. Upload audio files
5. Process the webhook callback
6. Retrieve and parse the Ekascribe results

## Prerequisites

* Python 3.6 or higher
* pip for dependency management
* Client credentials (client ID and secret) from Eka Care

## Installation

You can add the Eka Care Python SDK to your project using pip:

```bash theme={null}
pip install ekacare
```

## Available Template IDs

Eka Care supports multiple output templates for different medical documentation needs. Choose the appropriate template ID based on your requirements:

| Template ID | Description | Use Case |
| - | - | - |
| `clinical_notes_template` | Comprehensive clinical notes with structured medical information | General clinical documentation, patient consultations |
| `eka_emr_template` | EMR-compatible format for electronic medical records | Integration with EMR systems |
| `transcript_template` | Basic transcription with minimal structuring | Simple audio-to-text conversion |

## Available model types

| Model Type | Description |
| - | - |
| pro | Our most accurate model |
| lite | More performant model for lower latency |

## Supported Input Languages

Eka Care supports transcription in multiple languages. Specify the appropriate language ID in the `input_language` parameter:

| Language ID | Language Name |
| - | - |
| `en-IN` | English (India) |
| `en-US` | English (United States) |
| `hi` | Hindi |
| `gu` | Gujarati |
| `kn` | Kannada |
| `ml` | Malayalam |
| `ta` | Tamil |
| `te` | Telugu |
| `bn` | Bengali |
| `mr` | Marathi |
| `pa` | Punjabi |

## Step 1: Register Webhook (One-time Setup)

Before using the Ekascribe service, register a webhook to receive notifications when transcription is complete:

```bash theme={null}
curl --request POST \
  --url https://api.eka.care/notification/v1/connect/webhook/subscriptions \
  --header 'Authorization: Bearer <auth_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "event_names": [
      "v2rx.completed"
    ],
    "endpoint": "your-endpoint-url",
    "signing_key": "supersecretkey",
    "protocol": "https"
  }'
```

## Step 2: Authentication

Initialize the client with your credentials and obtain access tokens:

```python theme={null}
from ekacare import EkaCareClient

# Initialize the client
client = EkaCareClient(
    client_id="your_client_id",
    client_secret="your_client_secret"
)

# Login to get tokens
token_response = client.auth.login()
access_token = token_response["access_token"]
refresh_token = token_response["refresh_token"]

# Set access token manually if needed
client.set_access_token(access_token)

# Refresh token when needed
refreshed_tokens = client.auth.refresh_token(refresh_token)
new_access_token = refreshed_tokens["access_token"]
```

## Step 3: Upload Audio Files

Upload audio files for transcription:

```python theme={null}
# Prepare files and metadata
audio_files = [
    "path/to/audio_file1.mp3",
    "path/to/audio_file2.mp3"
]
# Optional fields transaction_id, extra_data, action
transaction_id = "unique_transaction_id"  
extra_data = {
    "mode": "dictation",
    "model_type": "lite"
}
action = "ekascribe-v2"

# Upload files
responses = client.v2rx.upload(
    file_paths=audio_files, 
    txn_id=transaction_id, 
    action=action, 
    extra_data=extra_data,
    output_format = {
        "input_language": ["en-IN"],
        "output_template": [
            {
                "template_id": "clinical_notes_template",
                "codification_needed": True
            }]
    }
)

# Process responses
for response in responses:
    # Handle response data as needed
    print(response)
```

## Step 4: Handle Webhook Callback

When the transcription is complete, Eka Care will send a webhook notification to your registered endpoint. Here's a sample of what you'll receive:

```json theme={null}
{
  "event": "v2rx.completed",
  "data": {
    "transaction_id": "unique_transaction_id",
    "status": "completed",
    "session_id": "unique_transaction_id"
  },
  "timestamp": "2023-07-20T10:30:00Z"
}
```

## Step 5: Retrieve Ekascribe Results

After receiving the webhook notification, retrieve the transcription results:

```python theme={null}
import base64

# Get the session ID from the webhook callback
session_id = "unique_transaction_id"  # This comes from the webhook payload which equals to transaction_id of Step 3: Upload Audio files 

# Fetch session status and results
action = "ekascribe-v2"
session_data = client.v2rx.get_session_status(session_id, action)


#{
#  "data": {
#    "output": [
#      {
#        "template_id": "clinical_notes_template",
#        "value": "<base 64 encoded value>",
#        "name": "Clinical Notes Template",
#        "status": "success",
#        "errors": [],
#        "warnings": []
#      }
#    ]
#  }
#}

# Extract and decode the Template value
for template_data in session_status.get("data", {}).get("output", []):
    template_id, template_value = template_data.get("template_id"), template_data.get("value")
    decoded_bytes = base64.b64decode(template_value)
    template_json = decoded_bytes.decode('utf-8')
    print(template_json)
```

## Complete Example

Here's a complete example integrating all the above steps:

```python theme={null}
from ekacare import EkaCareClient
import base64
import time

def ekascribe_integration_example():
    try:
        # Initialize the client
        client = EkaCareClient(
            client_id="your_client_id",
            client_secret="your_client_secret"
        )
        
        # Authenticate
        authenticate_client(client)
        
        # Upload audio files
        transaction_id = "unique_transaction_id"
        upload_audio_files(client, transaction_id)
        
        # NOTE: At this point, wait for the webhook callback
        # This would typically be handled by your web server
        
        # Once webhook is received, fetch results
        # The session_id would come from the webhook payload
        session_id = transaction_id         # "session_id_from_webhook"
        get_transcription_results(client, session_id)
        
    except Exception as e:
        print(f"Error: {str(e)}")

def authenticate_client(client):
    token_response = client.auth.login()
    client.set_access_token(token_response["access_token"])

def upload_audio_files(client, transaction_id):
    audio_files = [
        "path/to/audio1.mp3",
        "path/to/audio2.mp3"
    ]
    
    extra_data = {
        "mode": "dictation",
        "model_type": "lite"
    }

    action = "ekascribe-v2"

    
    
    responses = client.v2rx.upload(
    file_paths=audio_files, 
    txn_id=transaction_id, 
    action=action, 
    extra_data=extra_data,
    output_format = {
        "input_language": ["en-IN"],
        "output_template": [
            {
                "template_id": "clinical_notes_template",
                "codification_needed": True
            }]
    }
)
    
    return responses

def get_transcription_results(client, session_id):
    action = "ekascribe-v2"
    session_status = client.v2rx.get_session_status(session_id, action)
    
    if "data" in session_status and "output" in session_status["data"] and "fhir" in session_status["data"]["output"]:
        encoded_fhir = session_status["data"]["output"]["fhir"]
        decoded_bytes = base64.b64decode(encoded_fhir)
        fhir_json = decoded_bytes.decode('utf-8')
        return fhir_json
    else:
        # Handle non-completed status
        return None

if __name__ == "__main__":
    ekascribe_integration_example()
```

The uploader automatically:

* Determines appropriate upload method based on file size
* Uses multipart upload for large files (>100MB)
* Detects content types from file extensions
* Groups related files with transaction IDs

## Additional Resources

* [Eka Care Python SDK Examples Repository](https://github.com/eka-care/ekapython-sdk-example)
* [Eka Care Python Webhook Documentation](https://github.com/eka-care/ekapython-webhook-sdk)
* [Eka Care Developer Documentation](https://developer.eka.care/)
* [API Reference for Webhooks](https://developer.eka.care/api-sdk/webhooks/register-webhook)
* [API Reference for Ekascribe](https://developer.eka.care/api-sdk/scribe/sessions/overview)

## Troubleshooting

### Common Errors

1. **Authentication Failed**: Verify your client ID and secret are correct
2. **File Upload Failed**: Ensure file paths are valid and files are readable
3. **Webhook Not Received**: Check your endpoint is publicly accessible and correctly registered
4. **Import Errors**: Make sure you've installed all necessary dependencies

### Support

For additional support, contact the Eka Care developer support team at [support@eka.care](mailto:support@eka.care).


# Python SDK
Source: https://developer.eka.care/api-sdk/scribe/sdks/scribe-python-sdk

Turn medical audio into structured notes in a few lines of Python — the MedScribeAlliance Protocol SDK.

> [!NOTE]
>
> This is the **new** EkaScribe Python SDK (`scribe-python-sdk`), built on the
> **[MedScribeAlliance Protocol](/api-sdk/scribe/sessions/overview)**.
> It replaces the legacy [`ekacare` Python SDK](/api-sdk/scribe/sdks/python-sdk),
> which is now deprecated.

Give it medical audio (a consultation or dictation) and get back structured template
results — SOAP notes, medication lists, EMR-ready documents. The SDK handles auth,
sessions, voice-activity detection, upload, and result polling for you.

```python theme={null}
from scribe_sdk import ScribeClient

with ScribeClient() as client:
    s = client.create_session()
    client.upload_audio_file(s.session_id, "visit.wav")
    result = client.wait_for_results(s.session_id)
    print(result.templates)
```

That snippet is a **full** transcription-to-notes round trip. Everything below is detail.

***

## Integrate in 60 seconds

**1. Install**

Install directly from the Git repository (not yet on PyPI):

```bash theme={null}
pip install "scribe-python-sdk[audio] @ git+https://github.com/eka-care/scribe-python-sdk.git"
# or, with uv:  uv add "scribe-python-sdk[audio] @ git+https://github.com/eka-care/scribe-python-sdk.git"
```

The `[audio]` extra adds local file decoding + mic capture. Omit it (drop `[audio]`)
if you only send raw PCM you already have.

**2. Set credentials**

Create a `.env` file next to your script (it's auto-loaded):

```bash .env theme={null}
SCRIBE_ENV=prod                                  # "dev" -> api.dev.eka.care
SCRIBE_CLIENT_ID=your-client-id
SCRIBE_CLIENT_SECRET=your-client-secret
SCRIBE_DEFAULT_TEMPLATES=eka_emr_template,clinical_notes_template
```

> [!NOTE]
>
> Get your `client_id` / `client_secret` from Eka Care. They live **only** in the
> environment — the SDK refuses to read them from a config file, so they never leak
> into source control.

**3. Run**

Run the snippet at the top of this page. Done — no other setup. The SDK auto-loads
`.env`, logs in, picks the right host from `SCRIBE_ENV`, and applies
`SCRIBE_DEFAULT_TEMPLATES` so you don't repeat them on every call.

***

## The three ways to send audio

Pick whichever fits your input. They all finish the same way: `wait_for_results(session_id)`.

**A file (simplest)**

```python theme={null}
from scribe_sdk import ScribeClient

with ScribeClient() as client:
    s = client.create_session()
    client.upload_audio_file(s.session_id, "visit.wav")   # decode + VAD locally, upload
    result = client.wait_for_results(s.session_id)
    print(result.status, result.templates)
```

Accepts `.wav / .mp3 / .m4a / .webm / .ogg` — a path or raw `bytes`.

**Raw PCM**

Already have 16-bit mono PCM (e.g. captured from a mic)? Skip decoding:

```python theme={null}
from scribe_sdk import ScribeClient

with ScribeClient() as client:
    s = client.create_session()
    client.upload_pcm(s.session_id, pcm_bytes, sample_rate=16000)
    result = client.wait_for_results(s.session_id)
```

**Live streaming (WebSocket)**

Real-time audio over a WebSocket. Streaming is **async-only**:

```python theme={null}
from scribe_sdk import AsyncScribeClient

async with AsyncScribeClient() as client:
    async with await client.open_stream() as stream:
        async for frame in mic_frames():       # raw 16-bit LE PCM, mono, 16 kHz
            await stream.send_audio(frame)
        await stream.stop()                    # flush + end the session
    result = await client.wait_for_results(stream.session_id)
```

> [!NOTE]
>
> Everything except streaming has both a sync (`ScribeClient`) and async
> (`AsyncScribeClient`) flavor with identical method names — just add `await`.

That's the whole surface: **`create_session` → send audio → `wait_for_results`**.

***

## Reading the result

`wait_for_results()` returns a `SessionStatusResponse`:

```python theme={null}
result = client.wait_for_results(s.session_id)

result.status        # "completed" | "partial" | "failed" | "expired" | ...
result.transcript    # full transcript text
result.templates     # list of {template_id: {...}} — one entry per generated document
```

`templates` is a **list** of single-key dicts (one template can yield several documents),
so iterate it like this:

```python theme={null}
for doc in result.templates:
    for template_id, payload in doc.items():
        print(template_id, payload["status"])
        print(payload.get("data"))      # the structured note for this template
```

***

## Full working example: FastAPI relay

A browser can't hold your `client_id` / `secret`, so the common pattern is a thin server
that uses the SDK. Copy this into `server.py` and run `uvicorn server:app` — it exposes
start / upload / poll endpoints your frontend can call.

```python server.py theme={null}
from fastapi import FastAPI, UploadFile, HTTPException
from contextlib import asynccontextmanager
from scribe_sdk import AsyncScribeClient


@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.scribe = AsyncScribeClient()      # reads .env once
    app.state.chunks = {}
    yield
    await app.state.scribe.aclose()


app = FastAPI(lifespan=lifespan)


@app.post("/api/sessions")
async def start():
    s = await app.state.scribe.create_session()
    app.state.chunks[s.session_id] = 0
    return {"session_id": s.session_id}


@app.post("/api/sessions/{sid}/audio")
async def add_audio(sid: str, file: UploadFile):
    if sid not in app.state.chunks:
        raise HTTPException(404, "start a session first")
    data = await file.read()
    n = await app.state.scribe.upload_audio_file(
        sid, data, start_index=app.state.chunks[sid], end_session=False
    )
    app.state.chunks[sid] += n
    return {"chunks_uploaded": n}


@app.post("/api/sessions/{sid}/end")
async def end(sid: str):
    total = app.state.chunks.pop(sid, 0)
    await app.state.scribe.end_session(sid, audio_files_sent=total)
    return {"ok": True}


@app.get("/api/sessions/{sid}/results")
async def results(sid: str):
    status = await app.state.scribe.sessions.get(sid)   # poll this every ~1s from the browser
    return status.model_dump(exclude_none=True)
```

The official repo ships this plus a browser UI, a CLI, and a server-side script under
`examples/`.

***

## How it works

The SDK speaks the **MedScribeAlliance Protocol** and always runs voice-activity
detection (VAD) **on your machine** — only speech-bounded audio is sent, never an
un-VADded whole file. Both upload modes follow the same lifecycle:

**1. Create session**

`create_session()` → `POST /voice/v1/sessions`. Returns a `session_id` used by every
later call. For streaming it also returns a `wss://` URL.

**2. Send audio**

Chunked upload POSTs speech chunks; streaming sends PCM frames over the WebSocket.
Audio lands in storage but isn't processed yet.

**3. End session**

`end_session()` (or streaming's `stop()`) → `POST /voice/v1/sessions/{id}/end`. This
is the single trigger that commits the session and starts transcription. For
streaming, closing the socket alone does **not** finalize — `stop()` always calls
`end` for you.

**4. Poll results**

`wait_for_results(session_id)` → `GET /voice/v1/sessions/{id}` until a terminal status,
then returns the `templates`.

Your business id (`b_id`) is derived from your token automatically — you never configure it.

***

## Configuration

Everything has a sensible default; only credentials are required. Resolution order
(highest wins): **explicit kwargs › environment / `.env` › config file › defaults**.

### Environment variables

| Variable | Purpose |
| - | - |
| `SCRIBE_CLIENT_ID` / `SCRIBE_CLIENT_SECRET` | Credentials (**env-only**). |
| `SCRIBE_ENV` | `prod` (default → `api.eka.care`) or `dev` (→ `api.dev.eka.care`). |
| `SCRIBE_DEFAULT_TEMPLATES` | Comma-separated templates used when you don't pass `templates=`. |
| `SCRIBE_DEFAULT_MODEL` | `lite` (default) or `pro`. |
| `SCRIBE_BASE_URL` / `SCRIBE_AUTH_BASE_URL` | Override hosts directly (wins over `SCRIBE_ENV`). |

### Pass config inline (instead of env)

```python theme={null}
client = ScribeClient(
    env="dev",
    default_templates=["clinical_notes_template"],
    default_model="pro",
    client_id="...",          # or leave to the environment
    client_secret="...",
)
```

### Per-call overrides

`create_session()` accepts the same options when you want to override config for one session:

```python theme={null}
s = client.create_session(
    templates=["eka_emr_template", "clinical_notes_template"],  # up to 2
    model="pro",
    session_mode="consultation",        # or "dictation" (default)
    language_hint=["en", "hi"],
    patient_details={"name": "...", "oid": "..."},
)
```

***

## Reference

### Templates

| Template ID | Description |
| - | - |
| `clinical_notes_template` | Comprehensive structured clinical notes. |
| `eka_emr_template` | EMR-compatible format for electronic medical records. |
| `transcript_template` | Basic transcription with minimal structuring. |

### Models

| Model | Description |
| - | - |
| `pro` | Most accurate. |
| `lite` | Lower latency (default). |

### Languages (`language_hint`)

`en`, `hi`, `gu`, `kn`, `ml`, `ta`, `te`, `bn`, `mr`, `pa` (ISO 639-1 codes).

***

## Troubleshooting

> **login failed: 404 PROFILE\_NOT\_FOUND / 400 pwd mismatch**
>
> Your `client_id` / `client_secret` are wrong for the selected environment. Check
> `SCRIBE_ENV` matches where the credentials were issued (`dev` vs `prod`).

> **No templates specified and no default\_templates configured**
>
> Set `SCRIBE_DEFAULT_TEMPLATES` (or pass `templates=[...]` to `create_session`).

> **ModuleNotFoundError on file upload / mic capture**
>
> Install with the audio extra:
> `pip install "scribe-python-sdk[audio] @ git+https://github.com/eka-care/scribe-python-sdk.git"`.
> It's only needed for local decoding/VAD — raw-PCM and streaming work without it.

For help, contact **[support@eka.care](mailto:support@eka.care)**.


# MedScribe Alliance SDK (TypeScript)
Source: https://developer.eka.care/api-sdk/scribe/sdks/ts-sdk

Record in the browser and get structured medical notes back — the open MedScribe Alliance Protocol SDK for TypeScript.

Capture and process audio in the browser and generate structured medical documentation through Eka Care's voice transcription service.

`med-scribe-alliance-ts-sdk` is the open-source [MedScribe Alliance SDK](https://github.com/eka-care/medScribeAlliance-ts-sdk). It gives you a `ScribeClient` that speaks the MedScribe Alliance protocol directly: discovery, recording, chunked upload, session lifecycle, output retrieval.

## Prerequisites

* Node 14+
* `npm` or `yarn`
* Microphone access via browser permissions
* Stable network connectivity
* An access token from Eka Care

## Installation

```bash theme={null}
npm install med-scribe-alliance-ts-sdk
```

Peer dependencies (installed automatically):

* `@ricky0123/vad-web` — Voice Activity Detection
* `@breezystack/lamejs` — MP3 encoding
* `zod` — Schema validation

[npm package →](https://www.npmjs.com/package/med-scribe-alliance-ts-sdk)

***

## Integration Guide (Step-by-Step)

### Step 1: Create the Client

The `baseUrl` is **required** — every API call (session creation, upload, status polling) goes through it. If you leave it out, the SDK throws `allianceConfig.baseUrl is required` at runtime.

To use Eka Care's hosted scribe service, use:

| Environment | `baseUrl` |
| - | - |
| Production | `https://api.eka.care/voice/v1` |
| Development | `https://api.dev.eka.care/voice/v1` |

```ts theme={null}
import { ScribeClient } from 'med-scribe-alliance-ts-sdk';

const client = new ScribeClient({
  baseUrl: 'https://api.eka.care/voice/v1', // PROD — see table above
  accessToken: 'your-bearer-token',
  debug: true, // optional: logs SDK activity to console
});
```

> [!WARNING]
>
> **Production APIs require a secure (HTTPS) origin.** They will not work from `http://` or `http://localhost` — an insecure origin fails the CORS preflight (the `authorization` header is rejected).
>
> **Recommended:** Use **[ngrok](/docs/scribe/resources/local-development-ngrok)** to give your local server a public HTTPS URL and test against the production `baseUrl` directly.
>
> Alternatively, point at the **staging `baseUrl`** (`https://api.dev.eka.care/voice/v1`) which works from plain `localhost`.

### Step 2: Initialize (Discovery)

`init()` fetches the discovery document from the server. This tells the SDK what the server supports (models, languages, upload methods, audio formats, etc.).

```ts theme={null}
const initResult = await client.init();
if (!initResult.success) {
  console.error('Init failed:', initResult.error.message);
  return;
}
```

> `startRecording()` calls `init()` automatically if not already initialized. You can skip this step if you go directly to recording.

### Step 3: Register Callbacks

Register callbacks **before** starting a recording. These are how you receive events from the SDK.

```ts theme={null}
// Upload progress
client.registerCallback('onUploadEvent', (event) => {
  if (event.type === 'progress') {
    console.log(`Uploaded ${event.data.successCount}/${event.data.totalCount}`);
  }
});

// Recording state changes
client.registerCallback('onRecordingStateChange', (event) => {
  console.log('Recording state:', event.type); // 'started' | 'paused' | 'resumed' | 'ended'
});

// Errors (VAD failures, network issues, validation)
client.registerCallback('onError', (event) => {
  console.error(`[${event.error.code}] ${event.error.message}`);
});

// Auto token refresh on 401
client.registerCallback('onTokenRequired', async (event) => {
  const newToken = await refreshMyAuthToken();
  event.resolve(newToken);
});
```

### Step 4: Start Recording

Creates a session, starts the microphone, and begins chunked upload in one call.

```ts theme={null}
const result = await client.startRecording({
  templates: ['clinical_notes_template'], // required: template IDs for extraction
  sessionMode: 'consultation',   // optional: 'consultation' | 'dictation'
  transcriptLanguage: 'en',      // optional: language code for transcript output
  languageHint: ['en', 'hi'],    // optional: language codes for audio input. If you're not offering users a language change option in your UI, use ['auto_detect'] for the best results.
  patientDetails: {              // optional
    name: 'John Doe',
    age: '45',
    gender: 'male',
  },
  additionalData: {},            // optional: any extra data for the session
  txnId: 'your-transaction-id',  // optional: external transaction ID
});

if (!result.success) {
  console.error('Failed to start:', result.error.message);
  return;
}

const sessionId = result.data.session_id;
```

> [!NOTE]
>
> Use `clinical_notes_template` for testing, or contact Eka Care to create a custom template for your use case.

#### Pause / Resume

```ts theme={null}
client.pauseRecording();  // pauses VAD — mic stays open, no new chunks created
client.resumeRecording(); // resumes VAD processing
```

### Step 5: End Recording

Stops the microphone, flushes the last audio chunk, waits for all uploads to complete, and tells the server the session has ended (triggers server-side processing).

```ts theme={null}
const stopResult = await client.endRecording();

if (stopResult.success) {
  console.log(`${stopResult.data.totalFiles} files uploaded`);
  console.log(`${stopResult.data.failedUploads.length} failed`);
}
```

### Step 6: Poll for Results

After ending the recording, poll the server until processing is complete.

```ts theme={null}
const abortController = new AbortController();

const status = await client.getSessionStatus(sessionId, {
  poll: {
    maxAttempts: 60,
    intervalMs: 2000,
    signal: abortController.signal, // optional: abort polling early
    onProgress: (s) => {
      console.log(`Status: ${s.status}`);
      if (s.templates) {
        console.log('Templates:', s.templates);
      }
    },
  },
});

if (status.success) {
  console.log('Final status:', status.data.status);
  console.log('Templates:', status.data.templates);
  console.log('Transcript:', status.data.transcript);
}
```

### Step 7: Clean Up

```ts theme={null}
await client.reset(); // stops recording if active, clears all state and caches
```

### Flow Diagram

```
  new ScribeClient({ baseUrl, accessToken })
         │
         ▼
      init()  ──────────  Fetches discovery (auto-called by startRecording)
         │
         ▼
  registerCallback()  ──  Set up event handlers before recording
         │
         ▼
  startRecording()  ────  Creates session → starts mic → begins upload
         │
    pause / resume  ────  Optional during recording
         │
         ▼
  endRecording()  ──────  Stops mic → flushes audio → ends session → triggers processing
         │
         ▼
  getSessionStatus()  ──  Poll until completed/failed
         │
         ▼
  Read results  ────────  templates, transcript, errors
```

***

## Important Notes

* **`baseUrl` is the root for all API calls.** Session creation, audio upload, status polling — everything uses this URL. Make sure it's correct and accessible.
* **`accessToken` must be a valid Bearer token.** All API requests include `Authorization: Bearer <token>`. If it expires, register `onTokenRequired` to auto-refresh.
* **Register callbacks before `startRecording()`.** Events fire immediately once recording starts — if callbacks aren't registered, you'll miss upload progress and errors.
* **`endRecording()` triggers server processing.** Once you call it, the server begins processing the uploaded audio. Use `cancelSession()` instead if you don't want processing to happen.
* **`cancelSession()` does NOT trigger processing.** It stops the recorder locally, cleans up state, and tells the server the session is cancelled. No `endSession` call is made to the backend.
* **All async methods return `SDKResult<T>`, never throw.** Always check `result.success` before accessing `result.data`. Errors are in `result.error`.
* **The SDK validates inputs against the discovery document.** If the server doesn't support an upload type, language, or model you requested, you'll get a `ValidationError` before the API call is made.
* **SharedWorker is optional.** If you provide `workerScriptUrl`, the SDK offloads MP3 compression and upload to a SharedWorker. If the worker fails to load, it silently falls back to main-thread processing.
* **Microphone permission is requested on `startRecording()`.** The browser will prompt the user for mic access. If denied, you'll get an error via `onError` callback.
* **`reset()` is a full teardown.** It destroys the transport, clears discovery cache, removes all callbacks, and sets the client back to uninitialized state. You'll need to call `init()` (or `startRecording()`) again after reset.
* **Polling supports `AbortSignal`.** Pass `signal` in poll options to cancel polling early (e.g. when the user navigates away).

***

## Other Operations

### Cancel a Session

Stops the recorder locally **without** triggering server-side processing, then tells the server the session is cancelled.

```ts theme={null}
await client.cancelSession(); // cancels the current active session
await client.cancelSession('specific-session-id'); // or by ID
```

### Update a Session (Patch)

Update session properties after creation.

```ts theme={null}
await client.updateSession({
  patient_details: { name: 'Jane Doe', age: '30', gender: 'female' },
  additional_data: { notes: 'Follow-up visit' },
  templates: ['soap', 'prescription'],
});
```

### Two-Step Flow (Create Session + Record Separately)

```ts theme={null}
// Step 1: Create session
const session = await client.createSession({
  templates: ['soap'],
  upload_type: 'chunked',
  communication_protocol: 'http',
  session_mode: 'consultation',
});

if (!session.success) return;

// Step 2: Start recording with the existing session
await client.startRecordingWithSession(session.data);
```

### Get Status for a Specific Template

```ts theme={null}
const status = await client.getSessionStatus(sessionId, {
  templateId: 'soap',
});
```

### Retry Failed Uploads

```ts theme={null}
if (client.hasFailedUploads()) {
  const retryResult = await client.retryFailedUploads();
  console.log(`Retried: ${retryResult.data.retried}, Succeeded: ${retryResult.data.succeeded}`);
}
```

### Update Auth Token

```ts theme={null}
client.setAccessToken('new-bearer-token');
```

***

## Configuration

```ts theme={null}
interface ScribeSDKConfig {
  /** Base URL of the scribe service (required) */
  baseUrl: string;

  /** Bearer token for authentication */
  accessToken?: string;

  /** Transport mode: 'direct' (HTTP) or 'ipc' (Electron). Default: 'direct' */
  mode?: 'direct' | 'ipc';

  /** IPC bridge — required when mode is 'ipc' */
  ipcTransport?: IpcBridge;

  /** SharedWorker: true (require), false (disable), 'auto' (detect). Default: 'auto' */
  useWorker?: boolean | 'auto';

  /** URL to worker.bundle.js. Use getWorkerUrl() to resolve. */
  workerScriptUrl?: string;

  /** Enable debug logging. Default: false */
  debug?: boolean;

  /** Auto-fetch discovery document on init. Default: true */
  autoDiscovery?: boolean;
}
```

## Recording Options

```ts theme={null}
interface RecordingOptions {
  templates: string[];                   // Template IDs for extraction (required)
  model?: string;                        // Model ID from discovery
  languageHint?: string[];               // Language codes for audio input
  transcriptLanguage?: string;           // Language code for transcript output
  uploadType?: string;                   // 'chunked' | 'single' | 'stream' (default: 'chunked')
  communicationProtocol?: string;        // 'http' | 'websocket' (default: 'http')
  additionalData?: Record<string, any>;  // Extra data for the session
  deviceId?: string;                     // Specific microphone device ID
  sessionMode?: string;                  // 'consultation' | 'dictation'
  patientDetails?: PatientDetails;       // Patient info
  txnId?: string;                        // External transaction ID
}
```

## API Reference

### Lifecycle

| Method | Returns | Description |
| - | - | - |
| `init()` | `SDKResult<void>` | Fetch discovery document. Called automatically by `startRecording`. |
| `reset()` | `Promise<void>` | Stop recording, clear all state and caches. |

### Recording

| Method | Returns | Description |
| - | - | - |
| `startRecording(options)` | `SDKResult<CreateSessionResponse>` | Create session + start mic + begin upload. |
| `startRecordingWithSession(session, options?)` | `SDKResult<void>` | Attach recorder to an existing session. |
| `pauseRecording()` | `void` | Pause VAD (mic stays open, no chunks created). |
| `resumeRecording()` | `void` | Resume VAD processing. |
| `endRecording()` | `SDKResult<StopRecordingResult>` | Stop mic, flush audio, wait for uploads, end session. |
| `isRecording()` | `boolean` | Whether a recording is active. |
| `isRecordingPaused()` | `boolean` | Whether the active recording is paused. |
| `retryFailedUploads()` | `SDKResult<RetryUploadResult>` | Retry uploads that failed during the last recording. |
| `hasFailedUploads()` | `boolean` | Whether there are retryable failed uploads. |

### Session

| Method | Returns | Description |
| - | - | - |
| `createSession(request)` | `SDKResult<CreateSessionResponse>` | Create a session without starting a recording. |
| `getSessionStatus(sessionId?, options?)` | `SDKResult<GetSessionStatusResponse>` | Get status. Supports `poll` and `templateId` options. |
| `getCurrentSession()` | `CreateSessionResponse \| null` | Get the active session if any. |
| `updateSession(request, sessionId?)` | `SDKResult<PatchSessionResponse>` | Patch session (patient details, status, etc.). |
| `cancelSession(sessionId?)` | `SDKResult<PatchSessionResponse>` | Cancel session (stops recorder, no server processing). |

### Discovery

| Method | Returns | Description |
| - | - | - |
| `getDiscoveryDocument()` | `DiscoveryDocument \| null` | Raw discovery document. |
| `getDiscoveryConfig()` | `SDKResult<ResolvedConfig>` | Resolved config from discovery. |
| `refreshDiscovery()` | `SDKResult<ResolvedConfig>` | Force-refresh discovery. |

### Auth

| Method | Description |
| - | - |
| `setAccessToken(token)` | Update Bearer token. Propagates to transport, recorder, and worker. |

### Callbacks

Register with `client.registerCallback(name, handler)`, remove with `client.removeCallback(name, handler)`.

| Callback | Payload | Description |
| - | - | - |
| `onRecordingStateChange` | `RecordingStateChangeEvent` | Recording started, paused, resumed, or ended. |
| `onAudioEvent` | `AudioEvent` | Speech detection, silence warnings, chunk ready. |
| `onUploadEvent` | `UploadEvent` | Upload progress and failures. |
| `onSessionEvent` | `SessionEvent` | Session created, ended, status updates. |
| `onError` | `ErrorEvent` | VAD, worker, transport, or validation errors. |
| `onTokenRequired` | `TokenRequiredEvent` | 401 received — call `event.resolve(newToken)` to retry. |

#### Payload Shapes

```ts theme={null}
// onRecordingStateChange
interface RecordingStateChangeEvent {
  type: 'started' | 'paused' | 'resumed' | 'ended';
  timestamp: string;
  data?: any;
}

// onAudioEvent — discriminated union by `type`
type AudioEvent =
  | { type: 'user_speech';      timestamp: string; data: { isSpeaking: boolean } }
  | { type: 'silence_warning';  timestamp: string; data: { durationMs: number } }
  | { type: 'chunk_ready';      timestamp: string; data: { chunkIndex: number; fileName: string; chunkData: Uint8Array[] } }
  | { type: 'frame_processed';  timestamp: string; data: { isSpeech: number; notSpeech: number; frame: Float32Array; duration: number } };

// onUploadEvent
type UploadEvent =
  | { type: 'progress'; timestamp: string; data: { successCount: number; totalCount: number } }
  | { type: 'failed';   timestamp: string; data: { fileName: string; error: string } }
  | { type: 'retry';    timestamp: string; data: { fileName: string; attempt: number } };

// onSessionEvent
type SessionEvent =
  | { type: 'created';        timestamp: string; data: CreateSessionResponse }
  | { type: 'ended';          timestamp: string; data: EndSessionResponse }
  | { type: 'discarded';      timestamp: string; data: { sessionId: string | null; reason: 'cleared' | 'cancelled' | 'reset' } }
  | { type: 'status_update';  timestamp: string; data: GetSessionStatusResponse }
  | { type: 'partial_result'; timestamp: string; data: any };

// onError
interface ErrorEvent {
  type: 'vad_error' | 'worker_error' | 'transport_error' | 'validation_error';
  timestamp: string;
  error: { code: string; message: string; details?: any };
}

// onTokenRequired — call event.resolve(newToken) to retry the failed request
interface TokenRequiredEvent {
  resolve: (newToken: string) => void;
}
```

## Request / Response Types

#### Session

```ts theme={null}
interface CreateSessionRequest {
  templates: string[];
  upload_type: string;                   // 'chunked' | 'single' | 'stream'
  communication_protocol: string;        // 'http' | 'websocket'
  model?: string;
  language_hint?: string[];
  transcript_language?: string;
  additional_data?: Record<string, any>;
  session_mode?: string;                 // 'consultation' | 'dictation'
  patient_details?: PatientDetails;
  session_id?: string;                   // optional client-supplied ID
}

interface CreateSessionResponse {
  session_id: string;
  status: SessionStatus;
  created_at: string;
  expires_at: string;
  upload_url: string;
  patient_details?: PatientDetails;
}

interface PatchSessionRequest {
  user_status?: string;
  processing_status?: string;
  patient_details?: PatientDetails;
  additional_data?: Record<string, any>;
  language_hint?: string[];
  transcript_language?: string;
  templates?: string[];
}

interface PatchSessionResponse {
  session_id: string;
  status: string;
  message: string;
}

interface EndSessionResponse {
  session_id: string;
  status: SessionStatus;
  message: string;
  audio_files_received: number;
  audio_files: string[];
}

interface GetSessionStatusResponse {
  session_id: string;
  status: SessionStatus;
  created_at: string;
  expires_at?: string | null;
  expired_at?: string | null;
  completed_at?: string | null;
  model_used?: string | null;
  language_detected?: string | null;
  audio_files_received: number;
  audio_files: string[];
  audio_files_processed?: number;
  additional_data: Record<string, any>;
  templates?: TemplateEntry[];           // { [templateId]: { status, data, fhir, error, ... } }
  transcript?: string;
  processing_errors?: ProcessingError[];
  error?: { code: string; message: string; details?: Record<string, any> };
  patient_details?: PatientDetails;
  message?: string;
}

interface ProcessTemplateResponse {
  session_id: string;
  template_id: string;
  status: string;
  message: string;
}

interface PatientDetails {
  oid?: string;
  name?: string;
  age?: string;
  gender?: string;
  mobile?: number;
}
```

#### Recording

```ts theme={null}
interface StopRecordingResult {
  failedUploads: string[];
  totalFiles: number;
}

interface EndRecordingResult extends StopRecordingResult {
  sessionEnded: boolean;
  endSessionResponse?: EndSessionResponse;
}

interface RetryUploadResult {
  retried: number;
  succeeded: number;
  stillFailed: string[];
}

interface PollOptions {
  maxAttempts?: number;
  intervalMs?: number;
  onProgress?: (status: GetSessionStatusResponse) => void;
  signal?: AbortSignal;
}
```

## Error Handling

All public async methods return `SDKResult<T>` — errors are returned, not thrown:

```ts theme={null}
type SDKResult<T> =
  | { success: true; data: T }
  | { success: false; error: ScribeError };
```

```ts theme={null}
const result = await client.startRecording({ templates: ['soap'] });

if (!result.success) {
  console.error(result.error.code, result.error.message);
  return;
}

// result.data is typed as CreateSessionResponse
console.log(result.data.session_id);
```

### Error Classes

| Error | HTTP | Description |
| - | - | - |
| `ScribeError` | — | Base error class |
| `ValidationError` | 400 | Invalid request or config |
| `AuthenticationError` | 401 | Auth failed (after token refresh attempt) |
| `ForbiddenError` | 403 | Access denied |
| `SessionNotFoundError` | 404 | Session doesn't exist |
| `SessionExpiredError` | 410 | Session expired |
| `RateLimitError` | 429 | Rate limit exceeded |
| `DiscoveryError` | — | Discovery fetch/parse failed |
| `TransportError` | — | Network / IPC failure |
| `WorkerError` | — | SharedWorker failure |
| `UploadError` | — | Audio upload failure |

## SharedWorker Support

The SDK offloads MP3 compression and upload to a SharedWorker for better main-thread performance. The worker is bundled separately as `dist/worker.bundle.js`.

### Setup

```ts theme={null}
import { ScribeClient, getWorkerUrl } from 'med-scribe-alliance-ts-sdk';

const client = new ScribeClient({
  baseUrl: 'https://api.example.com',
  workerScriptUrl: getWorkerUrl(), // or a custom path
});
```

### Serving the Worker

The worker file must be served as a static asset:

**Copy to your public directory:**

```bash theme={null}
cp node_modules/med-scribe-alliance-ts-sdk/dist/worker.bundle.js public/
```

**Or use a CDN blob URL (avoids same-origin restrictions):**

```ts theme={null}
import { createWorkerBlobUrl } from 'med-scribe-alliance-ts-sdk';

const workerUrl = await createWorkerBlobUrl();
const client = new ScribeClient({
  baseUrl: '...',
  workerScriptUrl: workerUrl,
});
```

**Or set a global override:**

```ts theme={null}
window.__MEDSCRIBE_WORKER_URL__ = '/assets/worker.bundle.js';
```

If the SharedWorker fails to initialize, the SDK silently falls back to main-thread compression and upload.

## Electron / IPC Mode

For Electron apps where network requests must go through the main process:

```ts theme={null}
import { ScribeClient, TransportMode } from 'med-scribe-alliance-ts-sdk';

const client = new ScribeClient({
  baseUrl: 'https://api.example.com',
  mode: TransportMode.IPC,
  ipcTransport: {
    send: (request) => ipcRenderer.send('scribe-request', request),
    onResponse: (handler) => ipcRenderer.on('scribe-response', (_, res) => handler(res)),
  },
});
```

IPC mode always uses main-thread compression (SharedWorker can't access the IPC bridge).

***

## Source and specification

* [MedScribe Alliance Protocol](https://github.com/MedScribeAlliance/scribe-emr-protocol) — the open protocol this SDK implements
* [MedScribe Alliance TS SDK](https://github.com/eka-care/medScribeAlliance-ts-sdk) — source for `med-scribe-alliance-ts-sdk`


# Create Session
Source: https://developer.eka.care/api-sdk/scribe/sessions/create-session

POST /voice/v1/sessions
Create a new scribing session. Returns a `session_id` that must be used in every subsequent call (audio upload, end session, status polling) and an `upload_url` to which audio is sent. Only `upload_type` is required — use `single` (one audio file, max 10 MB via the API; for larger recordings use the SDKs, which chunk automatically) unless you need chunked or streaming upload. The communication protocol is derived from `upload_type` by the server: `single`/`chunked` → http, `stream` → websocket.


Create a scribing session. Only `upload_type` is required — use `single` for the simplest flow (one audio file). Save the returned `session_id` for all subsequent calls.

> [!NOTE]
>
> `single` uploads are capped at **10 MB** — for larger recordings use `chunked` or an [SDK](/docs/scribe/quickstart#prefer-an-sdk). The communication protocol is derived automatically: `single`/`chunked` → http, `stream` → websocket (returns a `wss://` `upload_url`).

**Next:** [Upload Audio](/api-sdk/scribe/sessions/upload-audio) → [End Session](/api-sdk/scribe/sessions/end-session) → [Get Session](/api-sdk/scribe/sessions/get-session).


# End Session
Source: https://developer.eka.care/api-sdk/scribe/sessions/end-session

POST /voice/v1/sessions/{session_id}/end
Finalize the session and start asynchronous processing. After this call no further audio uploads are accepted. The server collects and orders all uploaded chunks, commits the session, and queues it for transcription and template extraction. Poll `GET /voice/v1/sessions/{session_id}` (or use a webhook) to retrieve results once processing completes.


Lock the session and start processing — no body required. After this call no more audio is accepted.

On `202 Accepted`, poll [Get Session](/api-sdk/scribe/sessions/get-session) (or use a [webhook](/api-sdk/webhooks/getting-started)) until the results are ready.


# Get Session Audio
Source: https://developer.eka.care/api-sdk/scribe/sessions/get-audio

GET /voice/v1/sessions/{session_id}/audio
Fetch the complete recording of a session as a presigned download URL (single combined MP3). Available for businesses with full-audio access enabled — contact support to enable it for your workspace. The combined audio is prepared in the background after End Session; until it is ready this endpoint returns `404 audio_not_available`, so retry after a short delay. The recording is retained for 24 hours after the consultation by default (configurable per business) and is deleted after that — call this API within that window and download the audio via the returned presigned URL. Presigned URLs also expire — fetch a fresh URL when needed, don't store it.


Fetch the complete recording of a session as a presigned download URL (single combined MP3). Requires full-audio access enabled for your business — contact support to enable it. The audio is combined in the background after [End Session](/api-sdk/scribe/sessions/end-session); until it's ready this returns `404 audio_not_available`, so retry after a short delay.

> [!WARNING]
>
> Session audio is retained for **24 hours after the consultation** by default (configurable per business) and is deleted after that. Call this API within that window and download the recording via the returned presigned URL. Presigned URLs also expire — fetch fresh, don't store.


# Get Session
Source: https://developer.eka.care/api-sdk/scribe/sessions/get-session

GET /voice/v1/sessions/{session_id}
Retrieve the current status of a session and, once processing finishes, its transcript and structured template results. The **HTTP status code** signals progress: `202` still processing, `200` completed, `206` completed with partial results, `410` expired, `404` not found. After calling End Session, poll this endpoint at ~1-second intervals until the status is no longer `202`.


Poll this after [End Session](/api-sdk/scribe/sessions/end-session) at \~1-second intervals. **The HTTP status code is the signal:**

| Status | Meaning |
| - | - |
| `202` | Still processing — keep polling |
| `200` | Done — `transcript` + `templates` (with `document_id` per template) in the body |
| `206` | Done, but some templates failed |
| `410` | Session expired |

Pass `?document_id=<id>` to return only that document's result — e.g. a `document_id` from [Process Template](/api-sdk/scribe/sessions/process-template). Prefer not to poll? Register a [webhook](/api-sdk/webhooks/register-webhook).


# Get Sessions
Source: https://developer.eka.care/api-sdk/scribe/sessions/get-sessions

GET /voice/api/v2/transaction/history
List past sessions for the authenticated user, newest first. Cancelled and archived sessions are excluded. Pass `count` to cap the number of sessions returned. Pass `oid` to fetch sessions of a specific patient instead (up to 10 by default — override with `count`).


List past sessions for the authenticated user, newest first — useful for building a session-history screen. Cancelled and archived sessions are excluded.

Two ways to use it:

* **User history** (default) — all sessions created by the calling user. Pass `count` to cap how many are returned.
* **Patient history** — pass `?oid=<patient_oid>` to fetch sessions of a specific patient (up to 10 by default — override with `count`).

Each item's `txn_id` is the session ID — use it with [Get Session](/api-sdk/scribe/sessions/get-session), [Get Session Audio](/api-sdk/scribe/sessions/get-audio) or [List Session Documents](/api-sdk/scribe/documents/list-session-documents).


# Sessions Overview
Source: https://developer.eka.care/api-sdk/scribe/sessions/overview

Session-based voice capture and transcription — the core EkaScribe flow

A **session** ties audio capture, processing and results together under one `session_id`. Base path: `/voice/v1` on `https://api.eka.care`. All endpoints except Discovery need `Authorization: Bearer YOUR_ACCESS_TOKEN` ([get a token](/docs/scribe/authenticate-and-try)).

```
1. Create Session   POST /voice/v1/sessions                        → session_id, upload_url
2. Send audio       POST /voice/v1/sessions/{id}/audio/{file}     (single/chunked, HTTP)
                    or wss://… WebSocket                           (stream)
3. End Session      POST /voice/v1/sessions/{id}/end               → 202, processing starts
4. Get Session      GET  /voice/v1/sessions/{id}                  (poll ~1s until ≠202)
                    → transcript + structured notes per template
```

| API | Endpoint |
| - | - |
| [Create Session](/api-sdk/scribe/sessions/create-session) | `POST /voice/v1/sessions` |
| [Upload Audio](/api-sdk/scribe/sessions/upload-audio) | `POST /voice/v1/sessions/{session_id}/audio/{file_sequence}` |
| [Stream Audio](/docs/scribe/sessions/stream-audio) | `wss://…` (from `upload_url`) |
| [End Session](/api-sdk/scribe/sessions/end-session) | `POST /voice/v1/sessions/{session_id}/end` |
| [Get Session](/api-sdk/scribe/sessions/get-session) | `GET /voice/v1/sessions/{session_id}` |
| [Update Session](/api-sdk/scribe/sessions/update-session) | `PATCH /voice/v1/sessions/{session_id}` |
| [Upload Transcript](/api-sdk/scribe/sessions/upload-transcript) | `POST /voice/api/v1/transaction/{session_id}/convert-to-template` |
| [Process Template](/api-sdk/scribe/sessions/process-template) | `POST /voice/v1/sessions/{session_id}/process/template/{template_id}` |

Already have the transcript? [Upload Transcript](/api-sdk/scribe/sessions/upload-transcript) is an optional alternative to steps 2–3 — post the transcript and a `template_id` straight to the session, then poll Get Session for the structured note.

Also see [Templates](/api-sdk/scribe/templates/create-template) (define note formats) and [Documents](/api-sdk/scribe/documents/create-update-document) (read and edit generated notes).


# Process Template
Source: https://developer.eka.care/api-sdk/scribe/sessions/process-template

POST /voice/v1/sessions/{session_id}/process/template/{template_id}
After a session ends, generate another document from it for the given template. Every template processed — via Create Session `templates` or this API — creates a document, listed in the session's documents. The call is asynchronous: it returns `202` with a new `document_id`; fetch it with Get Session `?document_id=...` or Get Document once its status is `success`.


After a session ends, generate another document from it for any `template_id`. Returns `202` with a new `document_id`.

> [!NOTE]
>
> **Every template processed creates a document** — whether passed in [Create Session](/api-sdk/scribe/sessions/create-session) `templates` or via this API. All of them appear in [List Session Documents](/api-sdk/scribe/documents/list-session-documents), and each can be fetched with [Get Session](/api-sdk/scribe/sessions/get-session) `?document_id=<id>` or [Get Document](/api-sdk/scribe/documents/get-document).


# Update Session
Source: https://developer.eka.care/api-sdk/scribe/sessions/update-session

PATCH /voice/v1/sessions/{session_id}
Update a session's metadata before it is committed. Use this to attach or correct `patient_details`, change the requested `templates`, adjust `language_hint`, or switch `session_mode` / `model`. `session_mode` and `model` can only be changed while the session is still open (before End Session) — attempting to change them afterwards returns `409`. Unknown fields are rejected.


Update session metadata — `patient_details`, `templates`, `language_hint`, etc. Send only the fields you want to change.

> [!NOTE]
>
> `session_mode` and `model` can only be changed **before** [End Session](/api-sdk/scribe/sessions/end-session) — afterwards the call returns `409`.


# Upload Audio
Source: https://developer.eka.care/api-sdk/scribe/sessions/upload-audio

POST /voice/v1/sessions/{session_id}/audio/{file_sequence}
Upload audio as a raw binary body. For `single` uploads (the default upload type), send one complete recording (max 10 MB) and the server performs Voice Activity Detection (VAD) chunking inline — for larger recordings use `chunked` uploads or the SDKs. For `chunked` uploads, call this repeatedly with sequentially numbered filenames (`audio_0.webm`, `audio_1.webm`, ...); the server stores each chunk by its sequence number. The audio content type is detected automatically from the file extension; set the `Content-Type` header only to override it.


Send audio as a **raw binary body** (not multipart, not JSON). `single`: call once with the complete file (≤10 MB) as `audio_0.webm`. `chunked`: call once per chunk, incrementing the sequence (`audio_0.webm`, `audio_1.webm`, …).

> [!WARNING]
>
> This endpoint can't be tried from the browser — the docs playground can't send raw binary bodies. Use the cURL below (or any HTTP client) instead; every other EkaScribe endpoint works in the playground.

> [!NOTE]
>
> No `Content-Type` header needed — it's detected from the `file_sequence` extension (`.webm`, `.mp3`, `.wav`, `.ogg`, `.m4a`, `.mp4`).

```bash theme={null}
curl -X POST "https://api.eka.care/voice/v1/sessions/{session_id}/audio/audio_0.mp3" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data-binary "@/path/to/consultation.mp3"
```

When all audio is uploaded, call [End Session](/api-sdk/scribe/sessions/end-session). For real-time streaming use [Stream Audio](/docs/scribe/sessions/stream-audio) instead.


# Upload Transcript
Source: https://developer.eka.care/api-sdk/scribe/sessions/upload-transcript

POST /voice/api/v1/transaction/{session_id}/convert-to-template
**Optional.** Use this only if you already have the transcript and do not want EkaScribe to transcribe audio for you. Instead of uploading audio files, create a session, POST your transcript here along with the `template_id` you want it structured into, then poll Get Session for the structured result.

The call is asynchronous: it returns `202` with a `document_id` and `status: in-progress`. Fetch the structured note with `GET /voice/v1/sessions/{session_id}` (optionally `?document_id=<document_id>`) or Get Document once its status is `success`.

You may also omit `template_id` and send `target_language` instead to translate the transcript (or the session's stored transcript) into another language.


**This API is optional.** Use it only when you already have the transcript and don't need EkaScribe to transcribe audio for you. Instead of uploading audio, you post the transcript text plus the `template_id` you want it structured into, and EkaScribe returns the structured note.

The flow is three calls — no audio upload, no [End Session](/api-sdk/scribe/sessions/end-session):

```
1. Create Session     POST /voice/v1/sessions                                     → session_id
2. Upload Transcript  POST /voice/api/v1/transaction/{session_id}/convert-to-template
                      { "transcript": "...", "template_id": "..." }               → 202, document_id
3. Get Session        GET  /voice/v1/sessions/{session_id}                        (poll ~1s until ≠202)
                      → structured note for that template
```

```bash theme={null}
curl -X POST "https://api.eka.care/voice/api/v1/transaction/{session_id}/convert-to-template" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transcript": "Doctor: What brings you in today?\nPatient: I have had a dry cough and mild fever for three days.",
    "template_id": "clinical_notes_template"
  }'
```

> [!NOTE]
>
> The call is asynchronous — it returns `202` with a `document_id`. Poll [Get Session](/api-sdk/scribe/sessions/get-session) (optionally `?document_id=<id>`) or [Get Document](/api-sdk/scribe/documents/get-document) until the document's status is `success`.

> [!NOTE]
>
> If you omit `template_id`, the template requested in [Create Session](/api-sdk/scribe/sessions/create-session) (`templates`) is used. To structure the same transcript into more templates later, call [Process Template](/api-sdk/scribe/sessions/process-template) — each one creates its own document.

Sending `target_language` instead of `template_id` translates the transcript into that language (`eng`, `hi`, `ta`, `te`, `bn`, `mr`, `gu`, `kn`, `ml`, `pa`, `as`) rather than structuring it into a template.


# Create Template
Source: https://developer.eka.care/api-sdk/scribe/templates/create-template

POST /voice/api/v1/template
Create a custom note template. Describe the exact structure, sections and style you want in `desc` using plain text or markdown — for example "SOAP note with Subjective, Objective, Assessment, Plan; use bullet points; include a medication table". EkaScribe uses this description as the authoring instruction when generating notes. Pass the returned `template_id` in Create Session (`templates`) or Process Template.


Create a custom note template: just a `title` and a `desc` describing your format in plain text or markdown (sections, bullets, tables, tone). Always pass `section_ids: []`.

```json theme={null}
{
  "title": "Cardiology OPD Note",
  "desc": "## Chief Complaint\n## History\n## Examination (bullets, vitals table)\n## Plan (numbered, with follow-up date)",
  "section_ids": []
}
```

Use the returned `template_id` in [Create Session](/api-sdk/scribe/sessions/create-session) or [Process Template](/api-sdk/scribe/sessions/process-template).


# Delete Template
Source: https://developer.eka.care/api-sdk/scribe/templates/delete-template

DELETE /voice/api/v1/template/{template_id}
Archive (soft-delete) a custom template. The template stops appearing in List Templates and can no longer be used for new sessions; notes already generated with it are unaffected.


Archive a custom template. It disappears from [List Templates](/api-sdk/scribe/templates/list-templates) and can't be used for new sessions; existing notes are unaffected.


# List Templates
Source: https://developer.eka.care/api-sdk/scribe/templates/list-templates

GET /voice/api/v1/template
List every template available to your workspace — Eka's default templates (e.g. `clinical_notes_template`, `transcript_template`) plus any custom templates you created. The full template object is returned for each entry, so this is also the read path for a single template: filter the response by `id`.


List all templates available to your workspace — Eka defaults (`"default": true`, e.g. `clinical_notes_template`) plus your custom ones. Full objects are returned, so filter by `id` to read a single template.


# Update Template
Source: https://developer.eka.care/api-sdk/scribe/templates/update-template

PATCH /voice/api/v1/template/{template_id}
Update a custom template's title or description. Only the fields you send are changed. Default (Eka-provided) templates cannot be modified.


Update a custom template's `title` or `desc` — only the fields you send are changed. Eka default templates cannot be modified.


# Ekascribe
Source: https://developer.eka.care/api-sdk/sdks/sdks/android/ekascribe



# EkaScribe SDK Documentation

EkaScribe SDK (Voice2Rx) is an Android SDK for voice-based medical transcription and documentation.
It provides real-time voice recording, transcription, and intelligent medical documentation
generation with support for multiple languages and output formats.

**Version:** 3.0.7

**Minimum Android SDK:** 23 (Android 6.0)

***

## 1. Installation

### Add Maven Repository

Add the JitPack repository to your project's `settings.gradle.kts` (or `build.gradle`):

```kotlin theme={null}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        // Add below line to fetch SDK from Jitpack
        maven { url = uri("<https://jitpack.io>") }
    }
}

```

### Add Dependencies

Add the EkaScribe SDK and required networking dependency to your app's `build.gradle.kts`:

```kotlin theme={null}
dependencies {
    implementation("com.github.eka-care:Eka-Scribe-Android:${LATEST_VERSION}")
}

```

### Required Permissions

Add the following permissions to your `AndroidManifest.xml`:

```xml theme={null}
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

**Note:** You must request `RECORD_AUDIO` permission at runtime for Android 6.0 and above.

***

## 2. Initialization

Initialize the SDK in your `Application` class or main `Activity`.

### Step 1: Implement Lifecycle Callbacks

Create a class that implements `Voice2RxLifecycleCallbacks` to handle session events.

```kotlin theme={null}
import com.eka.voice2rx_sdk.sdkinit.Voice2RxLifecycleCallbacks
import com.eka.voice2rx_sdk.common.models.EkaScribeError

class MyVoice2RxCallbacks : Voice2RxLifecycleCallbacks {
    override fun onStartSession(sessionId: String) {
        // Recording started
    }

    override fun onStopSession(sessionId: String, recordedFiles: Int) {
        // Get result when ready after stopping the session
        CoroutineScope(Dispatchers.IO).launch {
            Voice2Rx.pollEkaScribeResult(sessionId = sessionId).onSuccess {
                Log.d(TAG, it.templates.toString())
            }.onFailure {
                Log.d(TAG, "error : ${it.message.toString()}")
            }
        }
    }

    override fun onPauseSession(sessionId: String) {
        // Recording paused
    }

    override fun onResumeSession(sessionId: String) {
        // Recording resumed
    }

    override fun onError(error: EkaScribeError) {
        // Handle error
    }
}

```

### Step 2: Implement TokenStorage

The networking module requires a `TokenStorage` implementation to handle authentication tokens.

```kotlin theme={null}
import com.eka.networking.token.TokenStorage

class MyTokenStorage : TokenStorage {
    override fun getAccessToken(): String {
        return "access_token"
    }

    override fun getRefreshToken(): String {
        return "refresh_token"
    }

    override fun saveTokens(accessToken: String, refreshToken: String) {
        // save tokens
    }

    override fun onSessionExpired() {
        // SessionExpired refresh token expired
    }
}
```

### Step 3: Configure and Initialize

Initialize `Voice2Rx` with `Voice2RxInitConfig` and `NetworkConfig`.

```kotlin theme={null}
import com.eka.voice2rx_sdk.sdkinit.Voice2Rx
import com.eka.voice2rx_sdk.sdkinit.Voice2RxInitConfig
import com.eka.networking.client.NetworkConfig
import com.eka.networking.client.AuthConfig

// 1. Configure Network
val networkConfig = NetworkConfig(
    appId = "your-app-id",
    baseUrl = "<https://api.eka.care/>",
    appVersionName = BuildConfig.VERSION_NAME,
    appVersionCode = BuildConfig.VERSION_CODE,
    isDebugApp = false // false in production environment,
    apiCallTimeOutInSec = 30L,
    headers = mapOf(), // Optional headers
    tokenStorage = MyTokenStorage()
)

// 2. Configure SDK
val config = Voice2RxInitConfig(
    voice2RxLifecycle = MyVoice2RxCallbacks(),
    networkConfig = networkConfig,
)

// 3. Initialize
Voice2Rx.init(config, context)

```

***

## 3. Core API Reference

All main functions are available via the `Voice2Rx` singleton object.

### Recording Control

### `startVoice2Rx`

Starts a new voice recording session.

```kotlin theme={null}
fun startVoice2Rx(
    mode: String = Voice2RxType.CONSULTATION.value, // "consultation" or "dictation"
    patientDetails: PatientDetails? = null,
    outputFormats: List<Template>, // Max 2 formats
    languages: List<String>,       // Max 2 languages
    modelType: String,             // e.g., "pro"
    onError: (EkaScribeError) -> Unit,
    onStart: (String) -> Unit
)

```

**Example:**

```kotlin theme={null}
// Define output templates using Template(templateId, templateName)
val outputFormats = listOf(
    Template(templateId = "19288d2f-81a9-46a6-b804-9651242a9b3e", templateName = "SOAP Note")
)

val languages = listOf("en-IN")

Voice2Rx.startVoice2Rx(
    mode = Voice2RxType.DICTATION.value,
    outputFormats = outputFormats,
    languages = languages,
    modelType = "pro" // or lite for faster results,
    onError = { error -> Log.e("SDK", "Error: ${error.errorDetails.message}") },
    onStart = { sessionId -> Log.d("SDK", "Started: $sessionId") }
)

```

### `pauseVoice2Rx`

Pauses the current recording.

```kotlin theme={null}
Voice2Rx.pauseVoice2Rx()

```

### `resumeVoice2Rx`

Resumes a paused recording.

```kotlin theme={null}
Voice2Rx.resumeVoice2Rx()

```

### `stopVoice2Rx`

Stops the recording and triggers processing.

```kotlin theme={null}
Voice2Rx.stopVoice2Rx()

```

### `isCurrentlyRecording`

Checks if a recording is in progress.

```kotlin theme={null}
val isRecording = Voice2Rx.isCurrentlyRecording()

```

### Data & Results

### `getSessionOutput`

Retrieves the transcription/generated output for a session.

```kotlin theme={null}
suspend fun getSessionOutput(sessionId: String): Result<SessionResult>

```

### `pollEkaScribeResult`

Polls for results, useful for waiting until processing completes.

```kotlin theme={null}
suspend fun pollEkaScribeResult(sessionId: String): Result<SessionResult>

```

### `getHistoryVoice2Rx`

Fetches session history.

```kotlin theme={null}
suspend fun getHistoryVoice2Rx(count: Int? = null): Voice2RxHistoryResponse?

```

### `getFullRecordingFile`

Gets the audio file for a session.

```kotlin theme={null}
fun getFullRecordingFile(sessionId: String): Result<File>

```

### Session Info & Monitoring

### `getSessionUploadInfoAsFlow`

Observe the upload stage of a session (Uploading, Processing, Completed).

```kotlin theme={null}
suspend fun getSessionUploadInfoAsFlow(sessionId: String): Flow<VoiceTransactionStage>?

```

### `getVoiceActivityFlow`

Flow for real-time voice activity (speech detection, amplitude).

```kotlin theme={null}
fun getVoiceActivityFlow(): Flow<VoiceActivityData>?

```

### `getAudioQualityFlow`

Flow for real-time audio quality metrics (STOI, PESQ, SI-SDR).

```kotlin theme={null}
fun getAudioQualityFlow(): Flow<AudioQualityMetrics?>?

```

### Configuration & Templates

### `getTemplates`

Get available output templates.

```kotlin theme={null}
suspend fun getTemplates(): Result<List<TemplateItem>>?

```

### `getUserConfigs`

Get user configuration including supported languages and modes.

```kotlin theme={null}
suspend fun getUserConfigs(): Result<UserConfigs>

```

### `updateUserConfigs`

Update user preferences (selected language, mode, etc.).

```kotlin theme={null}
suspend fun updateUserConfigs(selectedUserPreferences: SelectedUserPreferences): Result<Boolean>

```

***

## 4. Error Handling

Errors are returned via `EkaScribeError`.

**Common Error Codes:**

* `SUPPORTED_OUTPUT_FORMATS_COUNT_EXCEEDED`: Max 2 output formats allowed.
* `SUPPORTED_LANGUAGES_COUNT_EXCEEDED`: Max 2 languages allowed.
* `LANGUAGE_LIST_CAN_NOT_BE_EMPTY`
* `OUTPUT_FORMAT_LIST_CAN_NOT_BE_EMPTY`

**Data Class:**

```kotlin theme={null}
data class EkaScribeError(
    val sessionId: String,
    val errorDetails: EkaScribeErrorDetails, // Contains 'message', 'displayMessage', 'code'
    val voiceError: VoiceError
)

```

## 5. Cleanup

Call `releaseResources()` when the SDK is no longer needed (e.g., in `onDestroy` of your host
Activity/Application).

```kotlin theme={null}
Voice2Rx.releaseResources()

```


# Get Blood Banks
Source: https://developer.eka.care/api-sdk/uhi/blood-bank/get-blood-banks

api-reference/user-app/abdm-connect/registration.yml GET /abdm/uhi/v1/blood-bank/search/{request_id}
User can get blood banks.

## Used in

* [Search blood banks over UHI](/docs/uhi/workflows/blood-bank-search)


# Search Blood Banks
Source: https://developer.eka.care/api-sdk/uhi/blood-bank/state-district

api-reference/user-app/abdm-connect/registration.yml POST /abdm/uhi/v1/blood-bank/search
User can search blood banks using State & District wise.

## Used in

* [Search blood banks over UHI](/docs/uhi/workflows/blood-bank-search)


# Developer tools
Source: https://developer.eka.care/developer-tools

APIs, SDKs, MCP servers and webhooks for every Eka product, in one place.

## API reference

> **[Medical Scribe](/api-sdk/scribe/sessions/overview)**
>
> Consultations become structured notes that complete the chart

> **[Medical Document Parsing](/api-sdk/models/medical-document-parsing/introduction)**
>
> Any medical record, in any format, becomes structured data

> **[HIE-CM](/api-sdk/hie-cm/overview)**
>
> ABHA, care contexts, consent and records

> **[NHCX](/api-sdk/nhcx/search-payers)**
>
> Eligibility, pre-auth and insurance claims

> **[UHI](/api-sdk/uhi/blood-bank/state-district)**
>
> Blood bank search and consultations across the network

> **[Auth](/api-sdk/auth/getting-started)**
>
> Client credentials, OAuth2 and OIDC

## SDKs

> **[Medical Scribe](/api-sdk/scribe/sdks/ekascribe-ts-sdk)**
>
> Consultations become structured notes that complete the chart

> **[Medical Document Parsing](/api-sdk/models/sdks/backend/report-parsing-sdk)**
>
> Any medical record, in any format, becomes structured data

> **[HIE-CM](/api-sdk/hie-cm/sdks/web-sdk/abha-sdk/get-started)**
>
> ABHA, care contexts, consent and records

> **[Auth](/api-sdk/auth/sdks/python-sdk)**
>
> Client credentials, OAuth2 and OIDC

## MCP servers

> **[Eka MCP Server](/docs/emr/build-with-ai/mcp-server/introduction)**
>
> Connect your agent to Eka EMR: patients, appointments and prescriptions

> **[MedAI Tools MCP Server](/docs/datasets/build-with-ai/mcp-server/introduction)**
>
> Ground your agent in Indian drugs, treatment protocols, pharmacology and clinical calculators

> **[ABDM Connect MCP Server](https://github.com/eka-care/eka-abdm-connect-mcp)**
>
> ABHA creation, login and profile for ABDM Milestone 1

## Webhooks

> **[Medical Document Parsing](/docs/models/medical-document-parsing/smart-report-webhook)**
>
> Any medical record, in any format, becomes structured data

> **[HIE-CM](/docs/hie-cm/phr/webhooks)**
>
> ABHA, care contexts, consent and records

> **[UHI](/docs/uhi/webhooks/search-doctors)**
>
> Blood bank search and consultations across the network


# Bring Your Own Auth (BYOA)
Source: https://developer.eka.care/docs/auth/byoa

Authenticate your own users to EkaCare agents with a short-lived JWT signed by your shared secret (JWE optional)

## Overview

**Bring Your Own Auth (BYOA)** lets you authenticate your own users to EkaCare agents without an OIDC
flow. Your backend builds a short-lived token containing the user's identity, secures it with your
shared secret, and sends it to EkaCare — which looks up your secret by its **Key ID**, verifies the
token, and trusts the claims inside.

BYOA supports two token formats:

* **Signed JWT (JWS)** — **the default**. The claims are signed (HS256) with your shared secret. The
  payload is readable but tamper-proof. Lighter and simpler — use this unless you have a specific
  reason not to.
* **Encrypted JWE** — an optional, heavier alternative where the claims are *encrypted*. Use it only
  when the token travels somewhere it could be logged or inspected (e.g. a URL query parameter) **and**
  carries genuinely sensitive data. See [Encrypted Token (JWE)](#encrypted-token-jwe).

> [!NOTE]
>
> Both formats use the **same shared secret and Key ID** from the same BYOA credential. The `kid` header
> tells EkaCare which secret to use; the token format (signed vs encrypted) is detected automatically.

**Use BYOA when** your client has no OIDC/OAuth flow and you want to pass user data (mobile, name, etc.)
to EkaCare from your own backend.

***

## JWT or JWE?

> [!TIP]
>
> **Default to a signed JWT.** Reach for JWE only when **both** of these are true:
>
> 1. The token is sent somewhere observable — most commonly a **URL query parameter** (which can be
>    logged by proxies, servers, and browser history), rather than a header or request body, **and**
> 2. The payload contains **highly sensitive information** that must not be readable in transit.
>
> If you're passing the token in a header, request body, or the widget's `auth-token` attribute — which
> is the normal case — **use a JWT**. It's lighter, easier to debug, and just as secure against
> tampering.

| | Signed JWT (JWS) — default | Encrypted JWE |
| - | - | - |
| Claims visibility | Readable (base64), signed | Encrypted |
| Weight / complexity | Lighter, simpler | Heavier |
| Tamper protection | Yes | Yes |
| When to use | Almost always | Sensitive data on query params |

***

## Before You Begin

Create a BYOA credential in the [Eka Developer Console](https://console.eka.care). You will need:

* **Key ID** — the public identifier for your credential (e.g. `byoa_xxxxxxxxxxxxxxxx`); goes in the
  token's `kid` header.
* **Shared secret** — used to sign (JWT) or encrypt (JWE) the token. Shown only once at creation.
* **Issuer** — the issuer URL you registered on the credential; the token's `iss` claim must match it
  exactly.

> [!WARNING]
>
> The shared secret is shown only once. Store it securely on your backend and never expose it in
> client-side code. If it is lost or leaked, revoke the credential and create a new one.

***

## How It Works

**1. Create a credential**

In the [Eka Developer Console](https://console.eka.care) (BYOA → Create) you get a **Key ID** and a
**shared secret**. The secret is shown only once — copy it immediately.

**2. Build the claims**

On your backend, assemble the user's identity claims (see [Token Structure](#token-structure)).

**3. Sign as a JWT**

Sign the claims with your shared secret using **HS256**, with the protected header `kid` set to your
Key ID. (Or, for the sensitive-query-param case, [encrypt as a JWE](#encrypted-token-jwe).)

**4. Send it**

Hand the token to your embedded MedAssist widget — via the `auth-token` attribute or
`EkaMedAssist.init({ authToken })`. See [Send the Token](#send-the-token).

**5. EkaCare verifies**

EkaCare looks up your secret and registered issuer by the `kid`, verifies the signature, and trusts
the verified claims.

***

## Token Structure

The `x-auth-token` is a compact **JWT** (JWS) with a signed header and a payload of claims.

### Header

```json theme={null}
{ "kid": "byoa_xxxxxxxxxxxxxxxx", "alg": "HS256", "typ": "JWT" }
```

* `kid` — your credential's Key ID.
* `alg` — `HS256` (HMAC-SHA256; the shared secret is the signing key).
* `typ` — `JWT`.

### Payload claims

**iss** `string` *required*

Your issuer — must exactly match the issuer registered on your credential.

**aud** `string` *required*

Intended audience. Always `https://eka.care`.

**sub** `string`

Subject — your stable user identifier (partner user id). Leave it empty (`""`) if you identify users
only by mobile number (e.g. WhatsApp), where the `mobile` claim is the identifier instead.

**mobile** `string`

The user's mobile number, with country code.

**iat** `number` *required*

Issued-at time, in epoch seconds (UTC).

**exp** `number` *required*

Expiry time, in epoch seconds. Keep it short — `iat + 300` (about 5 minutes).

**jti** `string`

Recommended. A unique ID per request so EkaCare can reject replays of the same token.

Example payload:

```json theme={null}
{
  "iss": "https://partner.example.com",
  "aud": "https://eka.care",
  "sub": "partner_user_12345",
  "mobile": "+919876543210",
  "iat": 1749600000,
  "exp": 1749600300,
  "jti": "b3f1c2a4-9e5d-4c8b-a1f2-0d7e6c5b4a39"
}
```

> [!NOTE]
>
> The shared secret is a base64url-encoded 32-byte key. Decode it to 32 raw bytes before using it as the
> HS256 HMAC signing key.

***

## Generate the Token

Build the claims and sign them as a JWT with your shared secret (`HS256`, header `kid`). The shared
secret is base64url-decoded to a 32-byte key.

```python Python theme={null}
import base64
import time
import uuid
import jwt  # PyJWT


def mint_partner_token() -> str:
    # Provided by Eka
    kid    = "byoa_xxxxxxxxxxxxxxxx"
    secret = "dGVzdHNlY3JldGtleWZvcmp3ZXRlc3QxMjM0NTY3ODk"

    # base64url-decode the secret to 32 raw bytes (the HMAC key)
    raw = base64.urlsafe_b64decode(secret + "==")

    # Your values
    now = int(time.time())
    claims = {
        "iss":    "https://partner.example.com",
        "aud":    "https://eka.care",
        "sub":    "partner_user_12345",  # leave "" if you only have mobile
        "mobile": "+919876543210",
        "iat":    now,
        "exp":    now + 300,
        "jti":    str(uuid.uuid4()),
    }

    return jwt.encode(claims, raw, algorithm="HS256", headers={"kid": kid})


token = mint_partner_token()
print(token)
```

```javascript Node.js theme={null}
import { SignJWT } from 'jose';
import { randomUUID } from 'crypto';

async function mintPartnerToken() {
    const kid = "byoa_xxxxxxxxxxxxxxxx";
    const secret = "dGVzdHNlY3JldGtleWZvcmp3ZXRlc3QxMjM0NTY3ODk";

    // base64url-decode the secret to 32 raw bytes (the HMAC key)
    const key = Buffer.from(secret, "base64url");

    const now = Math.floor(Date.now() / 1000);

    return await new SignJWT({
        sub: "partner_user_12345",  // leave "" if you only have mobile
        mobile: "+919876543210",
    })
        .setProtectedHeader({ alg: "HS256", kid })
        .setIssuer("https://partner.example.com")
        .setAudience("https://eka.care")
        .setIssuedAt(now)
        .setExpirationTime(now + 300)
        .setJti(randomUUID())
        .sign(key);
}

mintPartnerToken()
    .then(token => {
        console.log("\nGenerated JWT:\n");
        console.log(token);
    })
    .catch(console.error);
```

```go Go theme={null}
package main

import (
	"encoding/base64"
	"fmt"
	"time"

	"github.com/golang-jwt/jwt/v5"
	"github.com/google/uuid"
)

func mintPartnerToken() (string, error) {
	kid := "byoa_xxxxxxxxxxxxxxxx"
	secret := "dGVzdHNlY3JldGtleWZvcmp3ZXRlc3QxMjM0NTY3ODk"

	// base64url-decode the secret to 32 raw bytes (the HMAC key)
	key, err := base64.RawURLEncoding.DecodeString(secret)
	if err != nil {
		return "", err
	}

	now := time.Now().Unix()
	claims := jwt.MapClaims{
		"iss":    "https://partner.example.com",
		"aud":    "https://eka.care",
		"sub":    "partner_user_12345", // leave "" if you only have mobile
		"mobile": "+919876543210",
		"iat":    now,
		"exp":    now + 300,
		"jti":    uuid.NewString(),
	}

	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
	token.Header["kid"] = kid
	return token.SignedString(key)
}

func main() {
	token, err := mintPartnerToken()
	if err != nil {
		panic(err)
	}

	fmt.Println(token)
}
```

```java Java theme={null}
import org.jose4j.jws.JsonWebSignature;
import org.jose4j.jws.AlgorithmIdentifiers;
import org.jose4j.jwt.JwtClaims;
import org.jose4j.keys.HmacKey;

import java.util.Base64;

public class GenerateJWT {

    public static void main(String[] args) throws Exception {

        String kid = "byoa_xxxxxxxxxxxxxxxx";
        String secret = "dGVzdHNlY3JldGtleWZvcmp3ZXRlc3QxMjM0NTY3ODk";

        // base64url-decode the secret to 32 raw bytes (the HMAC key)
        byte[] keyBytes = Base64.getUrlDecoder().decode(secret);

        JwtClaims claims = new JwtClaims();
        claims.setIssuer("https://partner.example.com");
        claims.setAudience("https://eka.care");
        claims.setSubject("partner_user_12345"); // leave "" if you only have mobile
        claims.setClaim("mobile", "+919876543210");
        claims.setIssuedAtToNow();
        claims.setExpirationTimeMinutesInTheFuture(5);
        claims.setGeneratedJwtId();

        JsonWebSignature jws = new JsonWebSignature();
        jws.setPayload(claims.toJson());
        jws.setKey(new HmacKey(keyBytes));
        jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.HMAC_SHA256);
        jws.setKeyIdHeaderValue(kid);

        System.out.println(jws.getCompactSerialization());
    }
}
```

***

## Send the Token

The **MedAssist widget** is EkaCare's embeddable chat widget. Copy its embed snippet from your agent's
**Widget** tab in the [Developer Console](https://console.eka.care) (or see the
[widget quickstart](/docs/agents/synapse/embed/quickstart)), then add the token to it.

![The Widget tab in the EkaCare Developer Console, showing the embed code to copy](https://mintcdn.com/ekacare/WPS74CI10j1wFPau/images/widget-tab.png?fit=max\&auto=format\&n=WPS74CI10j1wFPau\&q=85\&s=c12a6e11b590bcd4d48c6ee20c8c165f)

There are two ways to pass the token:

```html Custom element theme={null}
<eka-medassist-widget
  agent-id="YOUR_AGENT_ID"
  auth-token="COMPACT_JWT">
</eka-medassist-widget>

<script
  src="https://cdn.jsdelivr.net/npm/@eka-care/medassist-widget-embed@latest/dist/index.js"
  async
></script>
```

```html JavaScript theme={null}
<eka-medassist-widget agent-id="YOUR_AGENT_ID"></eka-medassist-widget>
<script
  src="https://cdn.jsdelivr.net/npm/@eka-care/medassist-widget-embed@latest/dist/index.js"
  async
></script>

<script>
  window.EkaMedAssist.init({
    agentId: "YOUR_AGENT_ID",
    authToken: "COMPACT_JWT",
  });
</script>
```

* **Custom element** — set the `auth-token` attribute on the `<eka-medassist-widget>` element. Best
  when you can render the token into the page server-side. See the
  [widget quickstart](/docs/agents/synapse/embed/quickstart).
* **JavaScript** — pass `authToken` to `EkaMedAssist.init()`. Best when the token is dynamic (e.g.
  minted per logged-in user at runtime). See the
  [JavaScript API](/docs/agents/synapse/embed/javascript-api).

***

## How EkaCare Verifies

When EkaCare receives the token, it:

1. Reads the `kid` from the token header and looks up the matching **shared secret** and registered
   **issuer**.
2. Verifies the JWT signature with your secret (or decrypts it, if it's a JWE).
3. Verifies the claims — `iss` matches the registered issuer, `aud` is `https://eka.care`, and `iat`
   and `exp` are within the allowed window. If you include a `jti`, it must not have been seen before
   (replay protection).

If any check fails, the request is rejected.

***

## Encrypted Token (JWE)

> [!NOTE]
>
> JWE is an **optional alternative to the default signed JWT**. It's heavier than a JWT. Only use it when
> the token is sent somewhere observable — most commonly a **URL query parameter** (which can be logged
> by proxies, servers, and browser history) — **and** its payload holds highly sensitive information that
> must not be readable in transit. Otherwise, use a [signed JWT](#generate-the-token).

A JWE carries the **same claims** as the JWT above ([Token Structure](#token-structure)) and uses the
**same Key ID and shared secret** — the payload is *encrypted* instead of signed.

### Header

```json theme={null}
{ "kid": "byoa_xxxxxxxxxxxxxxxx", "alg": "dir", "enc": "A256GCM" }
```

* `kid` — your credential's Key ID.
* `alg` — `dir` (the shared secret is used directly as the encryption key).
* `enc` — `A256GCM` (content encryption).

> [!NOTE]
>
> The shared secret is a base64url-encoded 32-byte key. Decode it to 32 raw bytes before using it as the
> `A256GCM` content-encryption key.

### Generate the JWE

Build the claims, encrypt them as a JWE with your shared secret (`alg: dir`, `enc: A256GCM`, header
`kid`), and serialize to compact form. The shared secret is base64url-decoded to a 32-byte key.

```python Python theme={null}
import base64
import time
import orjson
from jwcrypto import jwe, jwk

def mint_partner_token() -> str:
    # Provided by Eka
    kid    = "byoa_xxxxxxxxxxxxxxxx"
    secret = "dGVzdHNlY3JldGtleWZvcmp3ZXRlc3QxMjM0NTY3ODk"

    # Your values
    now = int(time.time())
    claims = {
        "iss":    "https://partner.example.com",
        "aud":    "https://eka.care",
        "sub":    "partner_user_12345",
        "mobile": "+919876543210",
        "iat":    now,
        "exp":    now + 300,
    }

    # Build key
    padded  = secret + "=" * (-len(secret) % 4)
    raw     = base64.urlsafe_b64decode(padded)
    k_b64   = base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
    jwk_key = jwk.JWK(kty="oct", k=k_b64)

    # Encrypt
    token_obj = jwe.JWE(
        plaintext=orjson.dumps(claims),
        protected=orjson.dumps({"alg": "dir", "enc": "A256GCM", "kid": kid}).decode(),
    )
    token_obj.add_recipient(jwk_key)
    return token_obj.serialize(compact=True)


token = mint_partner_token()
print(token)
```

```javascript Node.js theme={null}
import { CompactEncrypt } from 'jose';

async function mintPartnerToken() {
    const kid = "byoa_xxxxxxxxxxxxxxxx";
    const secret = "dGVzdHNlY3JldGtleWZvcmp3ZXRlc3QxMjM0NTY3ODk";

    const now = Math.floor(Date.now() / 1000);

    const claims = {
        iss: "https://partner.example.com",
        aud: "https://eka.care",
        sub: "partner_user_12345",
        mobile: "+919876543210",
        iat: now,
        exp: now + 300,
    };

    const key = Buffer.from(secret, "base64url");

    const token = await new CompactEncrypt(
        Buffer.from(JSON.stringify(claims))
    )
        .setProtectedHeader({
            alg: "dir",
            enc: "A256GCM",
            kid,
        })
        .encrypt(key);

    return token;
}

mintPartnerToken()
    .then(token => {
        console.log("\nGenerated JWE:\n");
        console.log(token);
    })
    .catch(console.error);
```

```go Go theme={null}
package main

import (
	"encoding/base64"
	"encoding/json"
	"fmt"
	"time"

	jose "github.com/go-jose/go-jose/v4"
)

func mintPartnerToken() (string, error) {
	kid := "byoa_xxxxxxxxxxxxxxxx"
	secret := "dGVzdHNlY3JldGtleWZvcmp3ZXRlc3QxMjM0NTY3ODk"

	now := time.Now().Unix()

	claims := map[string]interface{}{
		"iss":    "https://partner.example.com",
		"aud":    "https://eka.care",
		"sub":    "partner_user_12345",
		"mobile": "+919876543210",
		"iat":    now,
		"exp":    now + 300,
	}

	payload, err := json.Marshal(claims)
	if err != nil {
		return "", err
	}

	key, err := base64.RawURLEncoding.DecodeString(secret)
	if err != nil {
		return "", err
	}

	encrypter, err := jose.NewEncrypter(
		jose.A256GCM,
		jose.Recipient{
			Algorithm: jose.DIRECT,
			Key:       key,
		},
		(&jose.EncrypterOptions{}).WithHeader("kid", kid),
	)
	if err != nil {
		return "", err
	}

	obj, err := encrypter.Encrypt(payload)
	if err != nil {
		return "", err
	}

	return obj.CompactSerialize()
}

func main() {
	token, err := mintPartnerToken()
	if err != nil {
		panic(err)
	}

	fmt.Println(token)
}
```

```java Java theme={null}
import org.jose4j.jwe.JsonWebEncryption;
import org.jose4j.jwe.ContentEncryptionAlgorithmIdentifiers;
import org.jose4j.jwe.KeyManagementAlgorithmIdentifiers;
import org.jose4j.keys.AesKey;

import java.util.Base64;

public class GenerateJWE {

    public static void main(String[] args) throws Exception {

        String kid = "byoa_xxxxxxxxxxxxxxxx";
        String secret = "dGVzdHNlY3JldGtleWZvcmp3ZXRlc3QxMjM0NTY3ODk";

        long now = System.currentTimeMillis() / 1000;

        String payload = String.format("""
        {
          "iss":"https://partner.example.com",
          "aud":"https://eka.care",
          "sub":"partner_user_12345",
          "mobile":"+919876543210",
          "iat":%d,
          "exp":%d
        }
        """, now, now + 300);

        byte[] keyBytes = Base64.getUrlDecoder().decode(secret);
        AesKey key = new AesKey(keyBytes);

        JsonWebEncryption jwe = new JsonWebEncryption();

        jwe.setPayload(payload);
        jwe.setAlgorithmHeaderValue(
                KeyManagementAlgorithmIdentifiers.DIRECT);

        jwe.setEncryptionMethodHeaderParameter(
                ContentEncryptionAlgorithmIdentifiers.AES_256_GCM);

        jwe.setKeyIdHeaderValue(kid);
        jwe.setKey(key);

        String token = jwe.getCompactSerialization();

        System.out.println(token);
    }
}
```

EkaCare detects the JWE format automatically, looks up your secret by `kid`, decrypts it, and verifies
the same claims as a JWT.

***

## Best Practices

> [!WARNING]
>
> * Generate tokens **server-side only** — never ship the shared secret to a browser or mobile app.
> * Prefer a **signed JWT**; reach for JWE only for sensitive data on query parameters.
> * Keep `exp` short (\~5 minutes) and use a fresh `jti` for every request.
> * Rotate by revoking the credential and creating a new one, then update your agents to the new Key ID.


# Glossary
Source: https://developer.eka.care/docs/auth/glossary

The terms used in the Auth docs, what each one means, and the page where you meet it.

The terms you meet in the Auth docs. Follow the link in the last column to see a term in context.

| Term | What it means | Where it is used |
| - | - | - |
| Client credentials | The `client_id` and `client_secret` you create in the Eka Developer Console. You exchange them for an access token, and you keep them secret at all times. | [Authorization](/api-sdk/auth/getting-started) |
| Access token | The token you get from Connect Login and send on every API request. A `401 Unauthorized` means it has expired. | [Connect Login](/api-sdk/auth/client-login) |
| Refresh token | The token Connect Login returns with the access token. You use it to get a new access token after a `401`. | [Connect Refresh](/api-sdk/auth/refresh-token-v2) |
| Long-lived access token | An access token for server-to-server calls between trusted systems. You use it when you do not want to manage token refresh. | [Authorization](/api-sdk/auth/getting-started#long-lived-access-token) |

For terms from every Eka product, see the [Eka glossary](/docs/get-started/glossary).


# Invite flow
Source: https://developer.eka.care/docs/auth/invite-flow



## Overview

The **Invite Flow** allows workspace admins to onboard users into thier workspace using an invite link generated from the **Eka Developer Console**.

## Creating an Invite Link

**1. Open the Eka Developer Console**

[Click here to visit Eka Developer Console](https://console.eka.care).

> [!NOTE]
>
> You must be an Admin to create invites.

**2. Navigate to Invites**

From the left sidebar, click on **Invites**.

![Developer Console with Invites highlighted](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/docs/auth/images/invite-flow/invite-left-side-panel.png)

**3. Create Invite Link**

Click on **Create Invite Link**. Once created, an invite link is generated.

![Developer Console with Invites highlighted](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/docs/auth/images/invite-flow/create-invite.png)

![Developer Console with Invites highlighted](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/docs/auth/images/invite-flow/copy-invite-link.png)

> [!NOTE]
>
> Copy the link before leaving the page as it will not be shown again.

> [!NOTE]
>
> Invite links grant access to a specific product and workspace.
> Do **not** share an invite link with anyone other than the intended recipient.

***

## Consuming an Invite Link

Once generated, the invite link can be shared with the user via email, chat, or any external channel.

Once an invite link is created and shared, the invited user can join the workspace by opening the link.
The system ensures the user is authenticated before granting workspace access.

***

## Invite Authentication Flow

**1. Open the Invite Link**

The user clicks the invite link shared with them and the user is redirected to the authentication flow.

**2. Choose Sign-Up or Login Method**

On the authentication screen, the user can choose their preferred method to continue.

Eka supports multiple options such as:

* Google
* Apple
* Email Address
* Username

In this guide, we’ll walk through the flow using **Email Address**.

![Eka sign-up options screen](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/docs/auth/images/eka-sign-up-options.png)

**3. Enter Email Address**

The user enters their email address and clicks **Submit**.

![Eka enter email](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/docs/auth/images/enter-email.png)

**4. Verify Email Using OTP**

A one-time password (OTP) is sent to the user’s email address.

The user enters the OTP and clicks **Confirm** to continue authentication.

![OTP verification screen](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/docs/auth/images/verify-otp.png)

**5. Set Up Profile Details (New Users Only)**

Users are prompted to set up their profile.

![OTP verification screen](https://mintlify.s3.us-west-1.amazonaws.com/ekacare/docs/auth/images/invite-flow/setup-profile.png)

After entering the profile details, click **Next** to continue.

**6. Invite Validation and Consumption**

After successful authentication and profile setup, invite is consumed and workspace access is granted to the user.

**7. Redirect to Product**

Once the invite is successfully consumed, the user is redirected automatically.

The redirection is based on the invite configuration and includes:

* The **target product** (for example, EMR)
* The **specific workspace** for which the invite was created

This ensures the user lands directly in the correct product context
without requiring any additional product selection.


# Authentication
Source: https://developer.eka.care/docs/datasets/build-with-ai/mcp-server/authentication

Configure authentication for MedAI Tools — open mode for development, EkaCare OAuth for production.

MedAI Tools supports two modes depending on your deployment:

> **Open Mode**
>
> **For development and internal use**
>
> No authentication configuration required. All tools are accessible without credentials.

> **EkaCare OAuth**
>
> **For production and partner deployments**
>
> Authenticate via Eka's OIDC provider (`accounts.eka.care`). Required for the hosted remote server at `medai-tools.eka.care`.

***

## Open Mode (Default)

If you start the server without any auth environment variables, it runs in open mode — no login required. You'll see this in the logs:

```
INFO: Running without auth
```

This is suitable for local development, internal networks, or trusted environments where access is controlled at the network level.

***

## EkaCare OAuth Mode

For production deployments or when using the hosted server at `https://medai-tools.eka.care/mcp`, authentication is handled via EkaCare's OIDC provider.

### How It Works

There are two authentication paths:

1. **Full OIDC Flow** — for external clients (Claude, ChatGPT, Cursor). Your AI client opens a browser window to `accounts.eka.care`, you log in, and the client receives an access token automatically.

2. **Direct Eka Token** — for internal integrations. Pass a raw Eka API token via the `Authorization` header. The server validates it against `api.eka.care` and caches the result in Redis (5-minute TTL for valid tokens, 30-second TTL for invalid ones).

### Self-hosted OAuth Setup

To enable EkaCare OAuth on your own instance, set the following environment variables:

| Variable | Required | Description |
| - | - | - |
| `FASTMCP_SERVER_AUTH_EKACARE_BASE_URL` | Yes | Public URL of your server instance (e.g. `https://medai.yourdomain.com`) |
| `FASTMCP_SERVER_AUTH_EKACARE_CLIENT_ID` | Yes | OAuth client ID issued by Eka |
| `FASTMCP_SERVER_AUTH_EKACARE_CLIENT_SECRET` | Yes | OAuth client secret |
| `FASTMCP_SERVER_AUTH_EKACARE_CLIENT_STORAGE_BE` | No | Redis URL for token caching (e.g. `redis://localhost:6379/0`) — improves validation performance |

Add to your `.env` file:

```bash .env theme={null}
FASTMCP_SERVER_AUTH_EKACARE_BASE_URL=https://medai.yourdomain.com
FASTMCP_SERVER_AUTH_EKACARE_CLIENT_ID=your_client_id
FASTMCP_SERVER_AUTH_EKACARE_CLIENT_SECRET=your_client_secret
FASTMCP_SERVER_AUTH_EKACARE_CLIENT_STORAGE_BE=redis://localhost:6379/0
```

> [!WARNING]
>
> Never commit `.env` files or credentials to version control. Use `.gitignore` to exclude them, and use separate credentials for development and production.

### Token Caching with Redis

Redis is optional but recommended for production. Without it, every tool call triggers a live token validation request to `api.eka.care`. With Redis:

* Valid tokens are cached for **5 minutes**
* Invalid/expired tokens are cached for **30 seconds** (prevents hammering the auth API)

***

## Getting OAuth Credentials

To obtain a Client ID and Secret for a self-hosted deployment, contact:

**[ekaconnect@eka.care](mailto:ekaconnect@eka.care)**

Include:

* Your organization name
* Deployment URL (the `BASE_URL` you plan to use)
* Intended use case

***

> [!NOTE]
>
> For the hosted server (`https://medai-tools.eka.care/mcp`), authentication is managed by Eka — you only need an Eka account. OAuth credentials are only needed for self-hosted deployments.


# MedAI Tools MCP Server
Source: https://developer.eka.care/docs/datasets/build-with-ai/mcp-server/introduction

Ground your AI assistant in verified Indian medical data — drug search, treatment protocols, pharmacology, and 403 clinical calculators.

**Model Context Protocol (MCP)** is an open standard that lets AI assistants connect directly to external data and tools. The MedAI Tools MCP server gives Claude, ChatGPT, Cursor, and any MCP-compatible client access to curated Indian medical knowledge-bases and clinical calculators — without copy-pasting, manual lookup, or context-switching.

While frontier AI models perform well in general medical contexts, their responses often lack grounding in India-specific data: branded drug names, Indian formulary guidelines, and published Indian treatment protocols. MedAI Tools bridges that gap.

***

## What's Available

> **Indian Branded Drug Search**
>
> Look up any of 500,000+ Indian branded drugs by brand name, generic composition, or dosage form. Returns manufacturer, strength, and composition details.

> **Treatment Protocol Search**
>
> Search 180+ published treatment protocols from ICMR, RSSDI, ADA, WHO, ESH, KDIGO, AHA, IPS, and other authoritative bodies.

> **Pharmacology Details**
>
> Query the National Formulary of India (2011) for any generic drug — indications, dosage, contraindications, adverse effects, and pregnancy safety category.

> **Medical Calculator List**
>
> Browse 403 clinical calculators across 26 categories (cardiovascular, hematology, pediatric, and more). Step 1 of 3 in the calculator workflow.

> **Medical Calculator Input**
>
> Retrieve the exact input schema for any calculator — parameter names, types, and constraints. Step 2 of 3.

> **Medical Calculator Output**
>
> Execute a calculator with validated inputs and receive clinical results: risk scores, derived values, and interpretations. Step 3 of 3.

***

## Key Benefits

* **Medical accuracy** — responses grounded in verified, published medical data rather than AI's implicit training knowledge
* **India-specific** — 500K+ Indian branded drugs, Indian formulary, and Indian/international guidelines relevant to Indian practice
* **Reduced hallucinations** — drug names, dosages, and protocol details come from curated sources, not generated text
* **Not medical advice**: results are information for a clinician to check before any clinical use
* **Open standard** — works with any MCP-compatible client: Claude, ChatGPT, Cursor, VS Code, Windsurf, and more

***

## Get Started

> **[Quickstart](/docs/datasets/build-with-ai/mcp-server/quickstart)**
>
> Connect to the hosted server in minutes — no installation needed. Or self-host with Docker.

> **[Tool Reference](/docs/datasets/build-with-ai/mcp-server/tools)**
>
> Full parameter reference for all 6 tools, with examples and the medical calculator workflow.

> **[Authentication](/docs/datasets/build-with-ai/mcp-server/authentication)**
>
> Configure EkaCare OAuth for production deployments, or run open mode for development.

***

> [!NOTE]
>
> **Questions?** Email us at [ekaconnect@eka.care](mailto:ekaconnect@eka.care)


# Quickstart
Source: https://developer.eka.care/docs/datasets/build-with-ai/mcp-server/quickstart

Connect your AI client to MedAI Tools in minutes using the hosted server.

**Server URL:** `https://medai-tools.eka.care/mcp`

> [!NOTE]
>
> **Prerequisite:** An active Eka account. On first connect, your AI client will open a browser window for OAuth login. Contact **[ekaconnect@eka.care](mailto:ekaconnect@eka.care)** to get access.

Pick your AI client and follow the steps:

**Claude Desktop**

### Claude Desktop (Paid / Pro)

**1. Open Settings**

In Claude Desktop, click **Settings** → **Connectors** → **Add custom connector**

**2. Enter server details**

* Name: `MedAI Tools`
* URL: `https://medai-tools.eka.care/mcp`

**3. Add and authenticate**

Click **Add**, then sign in with your Eka account when prompted.

### Claude Desktop (Free)

Free tier doesn't have the Connectors UI. Use `mcp-remote` as a bridge:

**1. Open config**

Go to **Settings** → **Developer** → **Edit Config**

**2. Add this configuration**

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "medai-tools": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://medai-tools.eka.care/mcp"]
    }
  }
}
```

Config location: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)

**3. Save and restart**

Save the file, restart Claude Desktop, then authenticate when the browser opens.

**Claude Code**

Add to your Claude Code settings:

```json ~/.claude/settings.json theme={null}
{
  "mcpServers": {
    "medai-tools": {
      "type": "url",
      "url": "https://medai-tools.eka.care/mcp"
    }
  }
}
```

Or run from the terminal:

```bash theme={null}
claude mcp add medai-tools --transport http https://medai-tools.eka.care/mcp
```

**ChatGPT**

**Requirements:** ChatGPT with a paid plan (remote MCP connectors are not available on the Free tier).

**1. Go to Settings**

Open [chatgpt.com](https://chatgpt.com) → click your profile → **Settings**

**2. Enable developer mode**

Navigate to **Apps and Connectors** → toggle on **Developer mode**

**3. Create connector**

Click **Create app**:

* Name: `MedAI Tools`
* URL: `https://medai-tools.eka.care/mcp`

**4. Authenticate**

Click **Create** and sign in with your Eka account when the OAuth window appears.

**Cursor**

**1. Open MCP settings**

Press `Cmd/Ctrl + Shift + P` → **Cursor Settings** → **Tools & MCP** → **New MCP Server**

**2. Add configuration**

```json theme={null}
{
  "mcpServers": {
    "medai-tools": {
      "url": "https://medai-tools.eka.care/mcp"
    }
  }
}
```

**3. Connect**

Click **Connect**, then sign in with your Eka account.

**VS Code**

**Requirements:** VS Code 1.95+ with GitHub Copilot

**1. Open Command Palette**

Press `Cmd/Ctrl + Shift + P` → **MCP: Add Server** → **HTTP**

**2. Enter details**

* URL: `https://medai-tools.eka.care/mcp`
* Name: `medai-tools`

**3. Authenticate**

VS Code will prompt you to sign in with your Eka account.

Or add directly to settings:

```json settings.json theme={null}
{
  "mcp": {
    "servers": {
      "medai-tools": {
        "type": "http",
        "url": "https://medai-tools.eka.care/mcp"
      }
    }
  }
}
```

***

## Verify the Connection

Once connected, test with a prompt in your AI client:

```text theme={null}
Search for Dolo 650 in the Indian drug database
```

You should see the AI call `indian_branded_drug_search` and return drug details including generic composition and manufacturer.

***

## Self-hosted (Partners Only)

The MedAI Tools server source is available to Eka partners. Self-hosting requires Python 3.13+, Docker, AWS Bedrock access, and Eka OAuth credentials.

Contact **[ekaconnect@eka.care](mailto:ekaconnect@eka.care)** to request source access and setup documentation.

***

> [!NOTE]
>
> **Need an Eka account?** Contact **[ekaconnect@eka.care](mailto:ekaconnect@eka.care)** to get started.


# Tool Reference
Source: https://developer.eka.care/docs/datasets/build-with-ai/mcp-server/tools

Complete reference for all 6 MedAI Tools — parameters, return values, and usage examples.

MedAI Tools exposes 6 tools through the MCP interface. The first three are standalone lookups; the last three form a sequential workflow for running clinical calculators.

***

## `indian_branded_drug_search`

Search a database of 500,000+ Indian branded drugs by brand name, generic composition, or dosage form.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `drug_name` | string | No | Brand name to search (e.g. `"Dolo 650"`) |
| `form` | string | No | Dosage form (e.g. `"Tablet"`, `"Syrup"`, `"Injection"`) |
| `generic_names` | string | No | Comma-separated generic names (e.g. `"Paracetamol"` or `"Amoxicillin, Clavulanic Acid"`) |
| `volumes` | string | No | Strength or volume (e.g. `"650"`, `"500mg"`) |

At least one parameter should be provided. Returns a JSON list of matching drugs with brand name, generic composition, manufacturer, and available forms.

**Example:**

```text theme={null}
Search for Indian brands containing Metformin 500mg in tablet form
→ Calls: indian_branded_drug_search(generic_names="Metformin", volumes="500", form="Tablet")
```

***

## `indian_treatment_protocol_search`

Access published treatment protocols and clinical guidelines from Indian and international medical bodies.

**Available publishers include:** ICMR, RSSDI, ADA, WHO, ESH, KDIGO, AHA, IPS, and more.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `intent` | string | Yes | `"publishers"` to list all available guideline sources, or `"search"` to retrieve protocols |
| `queries` | list | No | Required when `intent="search"`. List of objects: `{"query": "...", "publisher": "..."}` |

Returns:

* For `intent="publishers"`: Text listing all available publishers
* For `intent="search"`: Protocol document pages as base64-encoded JPEG images

**Example:**

```text theme={null}
Step 1 — List available publishers:
→ Calls: indian_treatment_protocol_search(intent="publishers")

Step 2 — Search for a specific guideline:
→ Calls: indian_treatment_protocol_search(
    intent="search",
    queries=[{"query": "Type 2 diabetes management", "publisher": "RSSDI"}]
  )
```

***

## `indian_pharmacology_details`

Look up drug information from the National Formulary of India (2011). Covers indications, dosage, contraindications, adverse effects, and pregnancy safety.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `query` | string | No | Generic drug name(s). Supports compound generics with `+` separator (e.g. `"Rifampicin + Isoniazid"`) |

Returns a JSON list of pharmacology entries matching the query.

**Example:**

```text theme={null}
Get pharmacology details for a combination antibiotic
→ Calls: indian_pharmacology_details(query="Amoxicillin + Clavulanic Acid")
```

***

## Medical Calculator Workflow

The three calculator tools form a sequential 3-step workflow:

```
Step 1: medical_calculator_list    → Find the right calculator by browsing categories
Step 2: medical_calculator_input   → Get the exact input schema for that calculator
Step 3: medical_calculator_output  → Execute the calculator with validated inputs
```

### Available Categories

> **View all 26 categories (403 calculators total)**
>
> | Category | Calculators |
> | - | - |
> | Cardiovascular System | 38 |
> | Gynecology & Pregnancy | 35 |
> | Dietary | 31 |
> | Dosage | 27 |
> | Hematology | 26 |
> | Body Measurements | 22 |
> | Electrolytes & Fluids | 22 |
> | Urology & Nephrology | 19 |
> | Pulmonary | 19 |
> | Addiction Medicine | 17 |
> | Intensive & Emergency Care | 16 |
> | COVID-19 Vaccine | 16 |
> | Pediatric | 15 |
> | Other | 15 |
> | Epidemiology | 13 |
> | Diabetes | 10 |
> | Digestive System | 9 |
> | Geriatric Medicine | 9 |
> | BMI | 7 |
> | Metabolic Disorders | 7 |
> | Sleep | 6 |
> | Percentile | 6 |
> | Pediatric Dosage | 6 |
> | Psychiatry & Psychology | 5 |
> | Radiology | 4 |
> | Army | 3 |

***

### `medical_calculator_list`

Browse available calculators by category.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `intent` | string | Yes | `"categories"` to list all 26 categories, or `"calculators"` to list calculators in a specific category |
| `category` | string | No | Required when `intent="calculators"`. Category name (e.g. `"cardiovascular_system_calculators"`) |

***

### `medical_calculator_input`

Get the input schema for a specific calculator before executing it.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `calculator_name` | string | Yes | The calculator's `name` or `normalized_name` from the list step |

Returns a JSON schema describing all required and optional input fields with types and constraints.

***

### `medical_calculator_output`

Execute a calculator with validated input data.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `calculator_name` | string | Yes | The calculator's `name` or `normalized_name` |
| `input_data` | object | Yes | Input values conforming to the schema from the input step |

Returns the calculation result: numerical values, risk scores, derived metrics, and clinical interpretations.

***

### Worked Example: BMI Calculator

**1. Find the calculator**

```text theme={null}
→ Calls: medical_calculator_list(intent="categories")
# Returns list of 26 categories

→ Calls: medical_calculator_list(intent="calculators", category="bmi_calculators")
# Returns BMI calculators including "BMI Calculator – Body Mass Index"
# normalized_name: "bmi_calculator_body_mass_index"
```

**2. Get the input schema**

```text theme={null}
→ Calls: medical_calculator_input(calculator_name="bmi_calculator_body_mass_index")
```

Returns:

```json theme={null}
{
  "weight": { "type": "number", "description": "Body weight", "required": true },
  "height": { "type": "number", "description": "Height", "required": true },
  "weight_unit": { "type": "string", "enum": ["kg", "lbs"], "required": true },
  "height_unit": { "type": "string", "enum": ["cm", "in"], "required": true }
}
```

**3. Execute and get results**

```text theme={null}
→ Calls: medical_calculator_output(
    calculator_name="bmi_calculator_body_mass_index",
    input_data={
      "weight": 70,
      "height": 175,
      "weight_unit": "kg",
      "height_unit": "cm"
    }
  )
```

Returns:

```json theme={null}
{
  "bmi": 22.9,
  "category": "Normal weight",
  "healthy_range": "18.5 – 24.9"
}
```

***

> [!NOTE]
>
> For questions about specific tools or data coverage, contact **[ekaconnect@eka.care](mailto:ekaconnect@eka.care)**.


# Authentication
Source: https://developer.eka.care/docs/emr/build-with-ai/mcp-server/authentication

Securely connect your AI assistant to Eka.care

## Overview

Eka.care MCP supports two authentication methods to fit different integration needs:

> **OIDC Flow (Recommended)**
>
> **Best for:** Healthcare providers and clinics
>
> Auto-authenticate with your Eka.care account. No manual credential management needed.

> **Client Credentials**
>
> **Best for:** Third-party integrations
>
> Use API credentials (Client ID, Secret, API Key) for programmatic access.

***

## Method 1: OIDC Flow (Auto-Authentication)

This is the **easiest and most secure** method. Your AI assistant authenticates using your Eka.care login, just like logging into the dashboard.

### How It Works

**1. You start your MCP client**

Claude Desktop or any MCP-compatible client

**2. MCP initiates OIDC flow**

Opens a secure browser window

**3. You log in to Eka.care**

Use your existing Eka.care credentials

**4. Connection established**

Your AI assistant now has secure access

![OIDC Authentication Flow](https://mintcdn.com/ekacare/0oeGZ1h1B_twJ0YO/images/OIDC.png?fit=max\&auto=format\&n=0oeGZ1h1B_twJ0YO\&q=85\&s=6234b25999da11a680bafcdaebc3d9c7)

## Method 2: Client Credentials

Use this method if you have API credentials (Client ID, Client Secret, API Key) from the Eka.care team.

### How It Works

Your MCP server authenticates directly with Eka.care APIs using:

* **Client ID**: Your application identifier
* **Client Secret**: Secret key for authentication
* **API Key**: to connect to a specefic workspace from your client\_id / client\_secret

### Setup Client Credentials

**1. Get your credentials:**

Get your client id and client secret from Eka developer [console](https://console.eka.care/api-keys/)

* Client ID
* Client Secret

If you are a standalone devleoper and wish to access workspaces of Eka Users you can either implement OIDC ( Oauth ) flow or get API Key from users workspace [Hub](https://hub.eka.care/account/account/apitoken/)

* API Key

For any issues you can contact **[ekaconnect@eka.care](mailto:ekaconnect@eka.care)** and request:

**2. Configure your `.env` file:**

```bash .env theme={null}
# API Configuration
EKA_API_BASE_URL=https://api.eka.care

# Client Credentials
EKA_CLIENT_ID=your_client_id_here
EKA_CLIENT_SECRET=your_client_secret_here
EKA_API_KEY=your_api_key_here

# Server Settings (optional)
EKA_MCP_SERVER_HOST=localhost
EKA_MCP_SERVER_PORT=8000
EKA_LOG_LEVEL=INFO
```

> [!WARNING]
>
> **Security Best Practices:**
>
> * Never commit credentials to version control
> * Use `.gitignore` to exclude `.env` file
> * Rotate credentials periodically
> * Use different credentials for development and production

**3. Update Claude Desktop config:**

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "eka-care": {
      "command": "/full/path/to/.venv/bin/python",
      "args": ["-m", "eka_mcp_sdk.server"],
      "env": {
        "EKA_CLIENT_ID": "your_client_id_here",
        "EKA_CLIENT_SECRET": "your_client_secret_here",
        "EKA_API_KEY": "your_api_key_here",
        "EKA_API_BASE_URL": "https://api.eka.care"
      }
    }
  }
}
```

**4. Test your connection:**

```bash theme={null}
# Start the MCP server
eka-mcp-server
```

You should see:

```
INFO: Authentication successful
INFO: MCP Server running on http://localhost:8000
```

### Credential Management Tips

> **How to test credentials**
>
> **Quick test with curl:**
>
> ```bash theme={null}
> curl -X POST https://api.eka.care/api/v1/auth/token \
>   -H "Content-Type: application/json" \
>   -H "X-API-KEY: your_api_key" \
>   -d '{
>     "client_id": "your_client_id",
>     "client_secret": "your_client_secret",
>     "grant_type": "client_credentials"
>   }'
> ```
>
> Should return an access token if credentials are valid.

> **Token expiration**
>
> **Automatic refresh:** The MCP server automatically refreshes tokens before they expire.
>
> **Default expiration:** Tokens typically last 1 hour and are refreshed automatically.
>
> **No action needed:** You don't need to manually manage token lifecycle.

> **Multiple environments**
>
> **Development:**
>
> ```bash .env.development theme={null}
> EKA_CLIENT_ID=dev_client_id
> EKA_CLIENT_SECRET=dev_client_secret
> EKA_API_KEY=dev_api_key
> EKA_API_BASE_URL=https://api-dev.eka.care
> ```
>
> **Production:**
>
> ```bash .env.production theme={null}
> EKA_CLIENT_ID=prod_client_id
> EKA_CLIENT_SECRET=prod_client_secret
> EKA_API_KEY=prod_api_key
> EKA_API_BASE_URL=https://api.eka.care
> ```

> **Credential rotation**
>
> **When to rotate:**
>
> * Every 90 days (recommended)
> * If credentials may be compromised
> * When team members leave
>
> **How to rotate:**
>
> 1. Contact [ekaconnect@eka.care](mailto:ekaconnect@eka.care) for new credentials
> 2. Update your `.env` file
> 3. Restart the MCP server
> 4. Update Claude Desktop config if needed

***

> [!NOTE]
>
> **Need Credentials?** Contact **[ekaconnect@eka.care](mailto:ekaconnect@eka.care)** with:
>
> * Your organization name
> * Integration type (OIDC or Client Credentials)
> * Use case description
> * Expected API usage volume


# Eka MCP Server
Source: https://developer.eka.care/docs/emr/build-with-ai/mcp-server/introduction

Give your AI assistant direct access to Eka.care — book appointments, manage patients, create prescriptions, and more.

![MCP Overview](https://mintcdn.com/ekacare/0oeGZ1h1B_twJ0YO/images/eka-remote-mcp.png?fit=max\&auto=format\&n=0oeGZ1h1B_twJ0YO\&q=85\&s=dee202ae115fb0235d70f654c3a08b5f)

**Model Context Protocol (MCP)** is an open standard that lets AI assistants like Claude connect directly to your applications and data. Eka's MCP server exposes your EMR — patients, appointments, prescriptions, doctor and clinic data — so your AI can act on it, not just talk about it.

Instead of copy-pasting patient names or manually creating appointments, just ask your AI assistant and it handles it end-to-end.

***

## Choose Your Setup

> **[Remote MCP](/docs/emr/build-with-ai/mcp-server/remote-mcp)**
>
> **Recommended for most users**
>
> Hosted at `mcp.eka.care`. No installation needed — just add the URL to your AI client and sign in with your Eka.care account.

> **[Local MCP SDK](/docs/emr/build-with-ai/mcp-server/local-mcp)**
>
> **For developers and custom deployments**
>
> Self-hosted Python package. Use API credentials to connect, ideal for automation, offline access, or building your own integrations.

| | Remote MCP | Local MCP SDK |
| - | :- | :- |
| Hosted | Eka.care cloud (`mcp.eka.care`) | Your own machine |
| Auth | Eka.care account (OAuth login) | Client ID + Secret |
| Install | None | `pip install` |
| Best for | Doctors, clinics, quick setup | Developers, custom apps |

***

## What Can You Do?

Once connected, just talk to your AI assistant in plain language:

```text Example prompts theme={null}
"Book an appointment for Raj Kumar with Dr. Singh tomorrow at 10 AM"

"Show me all appointments for this afternoon"

"Search for patient Priya Sharma and update her mobile number"
```

> **Patient Management**
>
> Search and retrieve patient records, add new patients, update information, and view complete medical history.

> **Appointment Management**
>
> Check available slots, book, reschedule, or cancel appointments, and view appointment history.

> **Doctor & Clinic Operations**
>
> Retrieve doctor profiles, access clinic information, and view available services.

For the full list of available tools, see [Supported Tools](/docs/emr/build-with-ai/mcp-server/supported-tools).

***

> [!NOTE]
>
> **Questions?** Email us at [ekaconnect@eka.care](mailto:ekaconnect@eka.care)


# Local MCP SDK
Source: https://developer.eka.care/docs/emr/build-with-ai/mcp-server/local-mcp

Self-host the Eka MCP server on your own machine using API credentials.

The Local MCP SDK runs the Eka MCP server as a process on your machine. Your AI client talks to it over stdio — no network exposure, no OAuth browser flow. Credentials are passed via environment variables.

**Use this when you:**

* Are building a custom integration or automation pipeline
* Need to run offline or in a controlled environment
* Want to embed Eka MCP tooling into your own application
* Prefer client credentials over OIDC login

***

## Prerequisites

**1. Python 3.10 or higher**

Verify your Python version:

```bash theme={null}
python --version
```

**2. Get your API credentials**

You need a **Client ID** and **Client Secret** from the Eka developer console.

* Get your **Client ID** and **Client Secret** from the [Eka Console](https://console.eka.care/api-keys/)
* If you need access to a specific workspace (clinic), get an **API Key** from the [Hub](https://hub.eka.care/account/account/apitoken/)

> [!NOTE]
>
> Don't have access yet? Email **[ekaconnect@eka.care](mailto:ekaconnect@eka.care)** with your organization name and use case.

***

## Step 1 — Install the SDK

**pip + venv (recommended)**

Create an isolated virtual environment first to avoid dependency conflicts:

```bash theme={null}
python3 -m venv venv
source venv/bin/activate          # macOS / Linux
# venv\Scripts\activate           # Windows
pip install "git+https://github.com/eka-care/eka-mcp-sdk.git@main"
```

> [!NOTE]
>
> Keep the virtual environment activated whenever you run or configure the server. The `eka-mcp-server` command is only available inside the active `venv`.

**uv**

```bash theme={null}
uv add "eka-mcp-sdk @ git+https://github.com/eka-care/eka-mcp-sdk.git@main"
```

If you don't have `uv` yet:

```bash theme={null}
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Editable install (for contributors)**

Only needed if you want to **modify the SDK source code**:

```bash theme={null}
git clone https://github.com/eka-care/eka-mcp-sdk.git
cd eka-mcp-sdk
python3 -m venv venv
source venv/bin/activate          # macOS / Linux
# venv\Scripts\activate           # Windows
pip install -e .
```

An editable install means changes you make to the source are reflected immediately without reinstalling.

Verify the install:

```bash theme={null}
eka-mcp-server --help
```

You should see the server's CLI options printed.

***

## Step 2 — Configure Your Client

Pick your AI client below. Each config passes your credentials as environment variables directly — no `.env` file required.

> [!WARNING]
>
> Never commit your `EKA_CLIENT_ID`, `EKA_CLIENT_SECRET`, or `EKA_API_KEY` to version control. Add your config file to `.gitignore` if it contains credentials.

**Claude Desktop**

Open your Claude Desktop config file and add the `eka-care` server:

**macOS**

**Config location:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "eka-care": {
      "command": "eka-mcp-server",
      "env": {
        "EKA_CLIENT_ID": "your_client_id",
        "EKA_CLIENT_SECRET": "your_client_secret",
        "EKA_API_KEY": "your_api_key",
        "EKA_API_BASE_URL": "https://api.eka.care"
      }
    }
  }
}
```

**Windows**

**Config location:** `%APPDATA%\Claude\claude_desktop_config.json`

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "eka-care": {
      "command": "eka-mcp-server",
      "env": {
        "EKA_CLIENT_ID": "your_client_id",
        "EKA_CLIENT_SECRET": "your_client_secret",
        "EKA_API_KEY": "your_api_key",
        "EKA_API_BASE_URL": "https://api.eka.care"
      }
    }
  }
}
```

Restart Claude Desktop after saving. The Eka MCP tools will appear in your conversation.

**Cursor**

**macOS**

**Config location:** `~/Library/Application Support/Cursor/User/globalStorage/mcp.json`

```json mcp.json theme={null}
{
  "mcpServers": {
    "eka-care": {
      "command": "eka-mcp-server",
      "env": {
        "EKA_CLIENT_ID": "your_client_id",
        "EKA_CLIENT_SECRET": "your_client_secret",
        "EKA_API_KEY": "your_api_key",
        "EKA_API_BASE_URL": "https://api.eka.care"
      }
    }
  }
}
```

**Windows**

**Config location:** `%APPDATA%\Cursor\User\globalStorage\mcp.json`

```json mcp.json theme={null}
{
  "mcpServers": {
    "eka-care": {
      "command": "eka-mcp-server",
      "env": {
        "EKA_CLIENT_ID": "your_client_id",
        "EKA_CLIENT_SECRET": "your_client_secret",
        "EKA_API_KEY": "your_api_key",
        "EKA_API_BASE_URL": "https://api.eka.care"
      }
    }
  }
}
```

Or use the UI: **Cmd/Ctrl + Shift + P** → **Cursor Settings** → **Tools & MCP** → **New MCP Server** and paste the config above.

**VS Code**

Create or edit `.vscode/mcp.json` in your workspace (or add to your user `settings.json`):

```json .vscode/mcp.json theme={null}
{
  "servers": {
    "eka-care": {
      "type": "stdio",
      "command": "eka-mcp-server",
      "env": {
        "EKA_CLIENT_ID": "your_client_id",
        "EKA_CLIENT_SECRET": "your_client_secret",
        "EKA_API_KEY": "your_api_key",
        "EKA_API_BASE_URL": "https://api.eka.care"
      }
    }
  }
}
```

**Requirements:** VS Code 1.95+ with GitHub Copilot enabled.

**Windsurf**

**macOS**

**Config location:** `~/.codeium/windsurf/mcp_config.json`

```json mcp_config.json theme={null}
{
  "mcpServers": {
    "eka-care": {
      "command": "eka-mcp-server",
      "env": {
        "EKA_CLIENT_ID": "your_client_id",
        "EKA_CLIENT_SECRET": "your_client_secret",
        "EKA_API_KEY": "your_api_key",
        "EKA_API_BASE_URL": "https://api.eka.care"
      }
    }
  }
}
```

**Windows**

**Config location:** `%APPDATA%\.codeium\windsurf\mcp_config.json`

```json mcp_config.json theme={null}
{
  "mcpServers": {
    "eka-care": {
      "command": "eka-mcp-server",
      "env": {
        "EKA_CLIENT_ID": "your_client_id",
        "EKA_CLIENT_SECRET": "your_client_secret",
        "EKA_API_KEY": "your_api_key",
        "EKA_API_BASE_URL": "https://api.eka.care"
      }
    }
  }
}
```

**Zed**

Edit `~/.config/zed/settings.json`:

```json settings.json theme={null}
{
  "context_servers": {
    "eka-care": {
      "command": {
        "path": "eka-mcp-server",
        "args": [],
        "env": {
          "EKA_CLIENT_ID": "your_client_id",
          "EKA_CLIENT_SECRET": "your_client_secret",
          "EKA_API_KEY": "your_api_key",
          "EKA_API_BASE_URL": "https://api.eka.care"
        }
      }
    }
  }
}
```

***

## Step 3 — Verify

Restart your AI client. Then send a test prompt:

```text theme={null}
Search for patient [name]
```

The AI should call `search_patients` and return results from your Eka.care workspace.

***

## Other ways to run it

The same package runs three ways. It runs as an MCP server for an AI client, as an async Python library you call from your own code, and as a sync wrapper that works with CrewAI. Errors from the Eka.care APIs reach you unchanged, so the message you see is the one the API sent.

## Troubleshooting

> **'eka-mcp-server' command not found**
>
> The install likely went into a virtual environment that isn't on your PATH. Either:
>
> 1. Activate the virtual environment first:
>    ```bash theme={null}
>    source .venv/bin/activate  # macOS/Linux
>    .venv\Scripts\activate      # Windows
>    ```
>
> 2. Or use the full path to the binary in your config:
>    ```json theme={null}
>    {
>      "command": "/Users/you/project/.venv/bin/eka-mcp-server"
>    }
>    ```

> **Authentication failed / 401 errors**
>
> * Double-check `EKA_CLIENT_ID` and `EKA_CLIENT_SECRET` have no extra spaces or quotes
> * Ensure `EKA_API_KEY` matches the workspace you're trying to access
> * Credentials are available at [console.eka.care/api-keys](https://console.eka.care/api-keys/) and [hub.eka.care](https://hub.eka.care/account/account/apitoken/)

> **Tools not appearing in the AI client**
>
> * Fully restart the AI client after editing the config (not just reload)
> * Validate your config JSON is well-formed (no trailing commas, correct brackets)
> * Check the AI client's MCP logs — most clients expose these under Developer or Settings

***

> [!NOTE]
>
> **Need help?** Email **[ekaconnect@eka.care](mailto:ekaconnect@eka.care)** with your setup details and we'll help you get connected.


# Remote MCP
Source: https://developer.eka.care/docs/emr/build-with-ai/mcp-server/remote-mcp

Connect any AI client to Eka.care in minutes — no installation required.

The remote MCP server is hosted by Eka.care at `https://mcp.eka.care/mcp`. You don't install anything — just point your AI client at this URL and sign in with your Eka.care account.

**Server URL:** `https://mcp.eka.care/mcp`

> [!NOTE]
>
> **Prerequisite:** An active [Eka.care](https://eka.care) account. On first connect, your AI client will open a browser window for OAuth login.

***

## Setup by Client

Pick your AI client below and follow the steps.

**Claude Desktop**

### Claude Desktop (Paid / Pro)

The easiest path — add the server directly from the Connectors UI.

**1. Open Settings**

In Claude Desktop, click **Settings** → **Connectors** → **Add custom connector**

**2. Enter server details**

* Name: `Eka Care`
* URL: `https://mcp.eka.care/mcp`

**3. Add and authenticate**

Click **Add**, then sign in with your Eka.care account when prompted.

Config file location (if you prefer to edit manually):

**macOS**

```
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Windows**

```
%APPDATA%\Claude\claude_desktop_config.json
```

***

### Claude Desktop (Free)

Free tier doesn't have the Connectors UI. Use `mcp-remote` as a bridge instead.

**1. Open config**

Go to **Settings** → **Developer** → **Edit Config**

**2. Add this configuration**

**macOS / Linux**

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "eka-care": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.eka.care/mcp"]
    }
  }
}
```

Config location: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "eka-care": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.eka.care/mcp"]
    }
  }
}
```

Config location: `%APPDATA%\Claude\claude_desktop_config.json`

**3. Save and restart**

Save the file, restart Claude Desktop, then authenticate when the browser window opens.

**Cursor**

**1. Open MCP settings**

Press `Cmd/Ctrl + Shift + P` → type **Cursor Settings** → select **Tools & MCP** → click **New MCP Server**

**2. Add configuration**

**macOS**

```json theme={null}
{
  "mcpServers": {
    "eka-care": {
      "url": "https://mcp.eka.care/mcp"
    }
  }
}
```

Config location: `~/Library/Application Support/Cursor/User/globalStorage/mcp.json`

**Windows**

```json theme={null}
{
  "mcpServers": {
    "eka-care": {
      "url": "https://mcp.eka.care/mcp"
    }
  }
}
```

Config location: `%APPDATA%\Cursor\User\globalStorage\mcp.json`

**3. Connect**

Click **Connect** next to the eka-care entry, then sign in with your Eka.care account.

**VS Code**

**Requirements:** VS Code 1.95+ with GitHub Copilot

**1. Open Command Palette**

Press `Cmd/Ctrl + Shift + P`

**2. Add MCP server**

Type and select **MCP: Add Server** → choose **HTTP (HTTP or Server-Sent Events)**

**3. Enter details**

* URL: `https://mcp.eka.care/mcp`
* Server name: `eka-care`

**4. Authenticate**

VS Code will prompt you to sign in with your Eka.care account.

Alternatively, add directly to your config file:

**macOS**

```json settings.json theme={null}
{
  "mcp": {
    "servers": {
      "eka-care": {
        "type": "http",
        "url": "https://mcp.eka.care/mcp"
      }
    }
  }
}
```

**Windows**

```json settings.json theme={null}
{
  "mcp": {
    "servers": {
      "eka-care": {
        "type": "http",
        "url": "https://mcp.eka.care/mcp"
      }
    }
  }
}
```

Config location: `%APPDATA%\Code\User\globalStorage\github.copilot-chat\mcp.json`

**Windsurf**

**1. Open MCP config**

Press `Cmd/Ctrl + ,` → navigate to **Extensions** → **MCP**

**2. Add configuration**

**macOS**

```json theme={null}
{
  "mcpServers": {
    "eka-care": {
      "serverUrl": "https://mcp.eka.care/mcp"
    }
  }
}
```

Config location: `~/.codeium/windsurf/mcp_config.json`

**Windows**

```json theme={null}
{
  "mcpServers": {
    "eka-care": {
      "serverUrl": "https://mcp.eka.care/mcp"
    }
  }
}
```

Config location: `%APPDATA%\.codeium\windsurf\mcp_config.json`

**3. Restart and authenticate**

Restart Windsurf. On first use, a browser window will open for Eka.care login.

**Zed**

**1. Open settings**

Go to **Zed** → **Settings** (or press `Cmd/Ctrl + ,`)

**2. Add MCP server**

Add the following to your `settings.json`:

```json settings.json theme={null}
{
  "context_servers": {
    "eka-care": {
      "url": "https://mcp.eka.care/mcp",
      "transport": "http"
    }
  }
}
```

Config location: `~/.config/zed/settings.json`

**3. Restart and authenticate**

Restart Zed. Sign in with Eka.care when prompted.

**ChatGPT**

**Requirements:** ChatGPT with Go model or higher (remote MCP connectors are not available on the Free tier).

**1. Go to Settings**

Open [chatgpt.com](https://chatgpt.com) → click your profile (bottom-left) → **Settings**

**2. Enable developer mode**

Navigate to **Apps and Connectors** → scroll down → toggle on **Developer mode**

**3. Create connector**

In **Apps and Connectors**, click **Create app**:

* Name: `Eka Care`
* URL: `https://mcp.eka.care/mcp`

**4. Authenticate**

Click **Create** and sign in with your Eka.care account when the OAuth window appears.

***

## Verify the Connection

Once connected, test it with a simple prompt in your AI client:

```text theme={null}
Search for patient [name] in my clinic
```

You should see the AI call the `search_patients` tool and return results from your Eka.care account.

***

> [!NOTE]
>
> **Need an Eka.care account?** Contact **[ekaconnect@eka.care](mailto:ekaconnect@eka.care)** to get started. For enterprise or custom OAuth setups, reach out to the same address.


# Supported Tools
Source: https://developer.eka.care/docs/emr/build-with-ai/mcp-server/supported-tools

Complete list of available MCP tools and their capabilities

# Supported Tools

Eka MCP provides 20+ tools across patient management, appointments, ABHA/ABDM, and clinic operations. All tools support natural language queries through your AI assistant.

## Patient Management

| Tool Name | Description | Input Parameters | Returns |
| - | - | - | - |
| `search_patients` | Search for patients by name, mobile, email, or patient ID | `query` (string), `limit` (optional) | List of matching patients with IDs, contact info, and basic details |
| `get_patient_details` | Retrieve complete patient information | `patient_id` (string) | Full patient profile including medical history, demographics, and appointments |
| `add_patient` | Register a new patient | `name`, `mobile`, `email` (optional), `dob` (optional), `gender` (optional) | New patient ID and confirmation |
| `update_patient` | Modify existing patient information | `patient_id`, fields to update | Updated patient details |

## Appointment Management

| Tool Name | Description | Input Parameters | Returns |
| - | - | - | - |
| `get_available_slots` | Check doctor's availability | `doctor_id`, `date`, `clinic_id` (optional) | List of available time slots |
| `book_appointment` | Schedule a new appointment | `patient_id`, `doctor_id`, `slot_time`, `clinic_id` | Appointment ID and confirmation |
| `get_appointments` | List appointments by various filters | `patient_id` OR `doctor_id` OR `date`, `status` (optional) | List of appointments with details |
| `reschedule_appointment` | Change appointment timing | `appointment_id`, `new_slot_time` | Updated appointment details |
| `cancel_appointment` | Cancel scheduled appointment | `appointment_id`, `reason` (optional) | Cancellation confirmation |
| `get_appointment_details` | Retrieve specific appointment info | `appointment_id` | Complete appointment information |

## ABHA / ABDM

ABHA (Ayushman Bharat Health Account) tools let your AI assistant help patients log in with their ABHA mobile number, select their health profile, and fetch their ABHA card — all through a guided multi-step flow.

| Tool Name | Description | Input Parameters | Returns |
| - | - | - | - |
| `abha_send_otp` | Step 1 — Send OTP to the patient's ABHA-registered mobile number | `mobile_number` (10-digit) | `txn_id` to pass to the next step |
| `abha_verify_otp` | Step 2 — Verify the OTP entered by the patient | `otp`, `txn_id` (from Step 1) | Either the completed ABHA profile + card, or a list of profiles to choose from |
| `abha_select_profile` | Step 3 (if needed) — Select an ABHA profile when the patient has multiple | `phr_address` (e.g. `user@abdm`), `txn_id` (from Step 2) | Completed ABHA profile + ABHA card (base64 PNG) |

**Typical flow:**

```text theme={null}
"Help me log in with my ABHA"
→ abha_send_otp          (OTP sent to mobile)
→ abha_verify_otp        (OTP verified — returns profile or profile list)
→ abha_select_profile    (only if multiple profiles exist)
→ ABHA card shown to user
```

> [!NOTE]
>
> ABHA card is returned as a base64-encoded PNG in the response. The AI will render and display it directly — no additional tool call is needed.

## Doctor & Clinic Operations

| Tool Name | Description | Input Parameters | Returns |
| - | - | - | - |
| `get_doctor_profile` | Access doctor information | `doctor_id` | Doctor details, qualifications, specializations |
| `search_doctors` | Find doctors by name or specialization | `query`, `specialization` (optional) | List of matching doctors |
| `get_clinic_details` | Retrieve clinic information | `clinic_id` | Clinic address, services, contact info |
| `get_doctor_clinics` | List clinics associated with doctor | `doctor_id` | Array of clinic details |
| `get_clinic_services` | View services offered by clinic | `clinic_id` | List of available services |

## Medication Database

| Tool Name | Description | Input Parameters | Returns |
| - | - | - | - |
| `search_medications` | Look up medicine information | `query` (drug name) | Medicine details, dosage forms, manufacturers |
| `get_medication_details` | Get complete drug information | `medication_id` | Full drug profile with interactions and contraindications |

## Tool Parameters

## Usage Examples

### Simple Queries

```text theme={null}
"Search for patient Raj Kumar"
→ Uses: search_patients

"Show Dr. Singh's available slots tomorrow"
→ Uses: get_available_slots

"Get prescription history for patient 12345"
→ Uses: get_prescriptions
```

### Complex Workflows

```text theme={null}
"Book appointment for Raj Kumar with Dr. Singh tomorrow at 10 AM
and create prescription for Amoxicillin"
→ Uses: search_patients → book_appointment → create_prescription
```

## Rate Limits

| Plan | Requests/Minute | Requests/Day |
| - | - | - |
| Free | 10 | 1,000 |
| Pro | 60 | 10,000 |
| Enterprise | Unlimited | Unlimited |

## Error Handling

All tools return standardized error responses:

```json theme={null}
{
  "error": true,
  "message": "Patient not found",
  "code": "PATIENT_NOT_FOUND"
}
```

### Common Error Codes

* `PATIENT_NOT_FOUND` - Patient ID doesn't exist
* `SLOT_UNAVAILABLE` - Appointment slot already booked
* `INVALID_PARAMETERS` - Missing or incorrect parameters
* `UNAUTHORIZED` - Authentication required
* `RATE_LIMIT_EXCEEDED` - Too many requests

## Need More Details?

> **[Introduction](/docs/emr/build-with-ai/mcp-server/introduction)**
>
> Get started with Eka MCP

> **[Authentication](/docs/emr/build-with-ai/mcp-server/authentication)**
>
> Setup authentication methods

> **[Custom Client](/ai-tools/mcp-server/integrations/custom-client)**
>
> Build your own MCP client

> **[API Reference](/api-sdk/auth/getting-started)**
>
> Complete API documentation

***

**Questions?** Email [ekaconnect@eka.care](mailto:ekaconnect@eka.care)


# Encrypted API Requests and Responses
Source: https://developer.eka.care/docs/encryption/guide

Guide for implementing end-to-end encryption using JWE for Eka Care APIs

# Encrypted API Requests & Responses

Our APIs support end-to-end encryption for sensitive data and file uploads using [JWE (JSON Web Encryption) RFC 7516](https://datatracker.ietf.org/doc/html/rfc7516). This ensures that even over HTTPS, payloads remain confidential and tamper-proof.

## Key Details

* **Protected (`protected`)**: Base64URL-encoded JSON object containing the algorithm (`alg`) and encryption method (`enc`).
* **Algorithm (`alg`)**: Currently `dir` (direct mode, uses a shared symmetric key for encryption); other algorithms may be supported in the future
* **Encryption Method (`enc`)**: Currently `A128CBC-HS256` (AES-128 CBC with PKCS7 padding); other methods may be supported in the future
* **IV**: Random per request, Base64URL-encoded initialization vector
* **Ciphertext**: Base64URL-encoded encrypted content
* **Tag**: Authentication tag for integrity, Base64URL-encoded
* **Key (`kid`)**: Identifier for the shared AES key

## JSON API Requests

For APIs using `Content-Type: application/json`, encrypt the payload and send as JWE JSON serialization:

```json theme={null}
{
  "protected": "eyJhbGciOiAiZGlyIiwgImVuYyI6ICJBMTI4Q0JDLUhTMjU2In0",
  "iv": "0--10mVIyBcO_0GO",
  "ciphertext": "U2FsdGVkX1+...",
  "tag": "QmFzZTY0VGVzdFRhZw",
  "kid": "client-key-1"
}
```

### Example cURL Request

```bash theme={null}
curl --request POST \
  --url https://api.eka.care/abdm/na/v1/registration/aadhaar/init \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Encryption: JWE' \
  --data '{
    "protected": "eyJhbGciOiAiZGlyIiwgImVuYyI6ICJBMTI4Q0JDLUhTMjU2In0",
    "iv": "0--10mVIyBcO_0GO",
    "ciphertext": "U2FsdGVkX1+...",
    "tag": "QmFzZTY0VGVzdFRhZw",
    "kid": "client-key-1"
  }'
```

## File Upload APIs

Without encryption

```bash theme={null}
curl --request POST \
  --url https://api.eka.care/mr/api/v2/docs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file
```

With encryption

```bash theme={null}
curl --location 'https://api.eka.care/mr/api/v2/docs' \
--header 'Authorization: Bearer <token>' \
--header 'X-Encryption: JWE' \
--header 'Content-Type: application/json' \
--data '{
"protected": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0",
"iv": "o1jMW1CIrbEotbo6i1fdcg",
"ciphertext":"Aj_W1llT1pn6c_lWTMwSRcM5oKPsgqL_i2M3wr8UvI-HLxflxztqqDfiOqUtf7UWY7GGju1T2vUJ8S-O_pk6A2Q2k2LXgJ06YC4VUnMTe99_awFnekIOMbYX1T",
"tag": "o-Jx1iP8OWRhw9jAwcM3xQ",
"kid":"1"
}'
```

> [!NOTE]
>
> For tasks such as `PII` or `SRP`, make sure to include the appropriate query parameter as described in the [Upload API](https://developer.eka.care/api-sdk/models/medical-document-parsing/upload-report).

## Encrypted API Responses

Server responses can also be encrypted. Clients must decrypt using the shared key:

```json theme={null}
{
  "ciphertext": "SXNXEHqvd9PT15ELzuGScYNUS7RwXP9H3yqWl-Mml6bgwNdWoV3OdZ-Nuzz6C0tHX12Z82VnOL6q5_40vuIxDA",
  "iv": "oAvH6vVV_UYK7vrYsj2b8A",
  "tag": "kOLTuvgzaoxeN79DtGva_6Kf5FlpccclESO0XzoJZ2Y"
}
```

After decryption, the payload is your usual JSON object:

```json theme={null}
{
  "id": "123",
  "name": "Rakesh",
  "dob": "1990-01-01",
  "gender": "male"
}
```

## Example: Encrypting a File (Python)

```python theme={null}
from jwcrypto import jwk, jwe
import base64
import json

def b64url(data: bytes) -> str:
    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("utf-8")

def encrypt_file(file_path: str, key_str: str) -> dict:
    with open(file_path, "rb") as f:
        file_bytes = f.read()

    file_b64 = base64.b64encode(file_bytes).decode("utf-8")
    payload = {
        "file": file_b64
    }

    payload_json = json.dumps(payload).encode("utf-8")
    key_bytes = (key_str * 2).encode("utf-8")
    key_b64 = b64url(key_bytes)
    key = jwk.JWK(kty="oct", k=key_b64)
    header = {"alg": "dir", "enc": "A128CBC-HS256"}
    jwetoken = jwe.JWE(payload_json, protected=header)
    jwetoken.add_recipient(key)
    jwe_dict = json.loads(jwetoken.serialize(compact=False))
    return {
        "protected": jwe_dict["protected"],
        "iv": jwe_dict["iv"],
        "ciphertext": jwe_dict["ciphertext"],
        "tag": jwe_dict["tag"]
    }

encrypted_file = encrypt_file(
    "/Users/admin/Library/Application Support/JetBrains/PyCharm2024.2/scratches/Lab_Report_Sample.pdf",
    "YOUR_ENCRYPTION_KEY"
)

print(json.dumps(encrypted_file, indent=4))
```

```shell theme={null}
{
    "protected": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0",
    "iv": "oAvH6vVV_UYK7vrYsj2b8A",
    "ciphertext": "T0jZQGWh6WP+......",
    "tag": "LW3ikoOIGvtDY4TeH_ezfg"
}
```

## Example: Encrypting a Payload (Python)

```python theme={null}
from jwcrypto import jwk, jwe
import json
import base64

def b64url(data: bytes) -> str:
    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("utf-8")

def encrypt_jwe(payload: dict, key_str: str) -> dict:
    payload_json = json.dumps(payload).encode('utf-8')
    key_bytes = (key_str * 2).encode('utf-8')
    key_b64 = b64url(key_bytes)
    key = jwk.JWK(kty='oct', k=key_b64)

    header = {"alg": "dir", "enc": "A128CBC-HS256"}
    jwetoken = jwe.JWE(payload_json, protected=header)
    jwetoken.add_recipient(key)

    jwe_json = json.loads(jwetoken.serialize(compact=False))
    return {
        "protected": jwe_json["protected"],
        "iv": jwe_json["iv"],
        "ciphertext": jwe_json["ciphertext"],
        "tag": jwe_json["tag"]
    }

payload = {"aadhaar_number": "123456789012"}
encrypted_jwe = encrypt_jwe(payload, "YOUR_ENCRYPTION_KEY")
print(encrypted_jwe)
```

```shell theme={null}
{
    "protected": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0",
    "iv": "oAvH6vVV_UYK7vrYsj2b8A",
    "ciphertext": "T0jZQGWh6WP_TMz_1aUyqm06FGxi8FdQVK-0eleFDD7OBhxr3Bt2a1gt4OtbpuSn",
    "tag": "LW3ikoOIGvtDY4TeH_ezfg"
}
```

## Example: Encrypting a Payload (.net)

```csharp theme={null}
using System;
using System.Text;
using Jose;
using Newtonsoft.Json.Linq;

public class Program
{
    public static JObject EncryptJwe(JObject payload, string keyStr)
    {
        string payloadJson = payload.ToString(Newtonsoft.Json.Formatting.None);

        string doubled = keyStr + keyStr;
        byte[] key = Encoding.UTF8.GetBytes(doubled);

        string jweCompact = JWT.Encode(payloadJson, key, JweAlgorithm.DIR, JweEncryption.A128CBC_HS256);

        string[] parts = jweCompact.Split('.');

        return new JObject
        {
            ["protected"] = parts[0],
            ["iv"] = parts[2],
            ["ciphertext"] = parts[3],
            ["tag"] = parts[4]
        };
    }

    public static void Main()
    {
        var payload = new JObject
        {
            ["aadhaar_number"] = "123456789012"
        };

        var encrypted_jwe = EncryptJwe(payload, "YOUR_ENCRYPTION_KEY");
        Console.WriteLine(encrypted_jwe);
    }
}
```

```shell theme={null}
{
  "protected": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0",
  "iv": "-xRt08Nui-LIEUhYMaAODg",
  "ciphertext": "IMCGMlpPmV2DMkYJMeqLqlGj4pL74OZn-koLVNyDESrJU_LE6fnJJhrorRwBoIyh",
  "tag": "TAi3Yok9KU0FLTSL0WEWnQ"
}
```

## Example: Decrypting a Payload (Python)

```python theme={null}
from jwcrypto import jwk, jwe
import json, base64

def b64url(data: bytes) -> str:
    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("utf-8")

def decrypt_jwe(jwe_dict: dict, key_str: str) -> dict:
    key_bytes = (key_str * 2).encode('utf-8')
    key_b64 = b64url(key_bytes)
    key = jwk.JWK(kty='oct', k=key_b64)
    token = jwe.JWE()
    token.deserialize(json.dumps(jwe_dict))
    token.decrypt(key)
    return json.loads(token.payload.decode())

encrypted_jwe = {
    "protected": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0",
    "iv": "oAvH6vVV_UYK7vrYsj2b8A",
    "ciphertext": "T0jZQGWh6WP_TMz_1aUyqm06FGxi8FdQVK-0eleFDD7OBhxr3Bt2a1gt4OtbpuSn",
    "tag": "LW3ikoOIGvtDY4TeH_ezfg"
}

print(decrypt_jwe(encrypted_jwe, "YOUR_ENCRYPTION_KEY"))
```

```shell theme={null}
{"aadhaar_number": "123456789012"}
```

## Example: Decrypting a Payload (.net)

```csharp theme={null}
using System;
using System.Text;
using Jose;
using Newtonsoft.Json.Linq;

public class Program
{
    public static JObject DecryptJwe(JObject jweDict, string keyStr)
    {
        string doubled = keyStr + keyStr;
        byte[] key = Encoding.UTF8.GetBytes(doubled);

        string jweCompact = $"{jweDict["protected"]}..{jweDict["iv"]}.{jweDict["ciphertext"]}.{jweDict["tag"]}";

        string decryptedJson = JWT.Decode(jweCompact, key);

        return JObject.Parse(decryptedJson);
    }

    public static void Main()
    {
        var encrypted_jwe = new JObject
        {
            ["protected"] = "eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0",
            ["iv"] = "oAvH6vVV_UYK7vrYsj2b8A",
            ["ciphertext"] = "T0jZQGWh6WP_TMz_1aUyqm06FGxi8FdQVK-0eleFDD7OBhxr3Bt2a1gt4OtbpuSn",
            ["tag"] = "LW3ikoOIGvtDY4TeH_ezfg"
        };

        Console.WriteLine(DecryptJwe(encrypted_jwe, "YOUR_ENCRYPTION_KEY"));
    }
}
```

```shell theme={null}
{"aadhaar_number": "123456789012"}
```


# IP Allowlisting for Clients
Source: https://developer.eka.care/docs/encryption/ip-allowlisting-for-clients

Allowlisting and endpoint information to access Eka Care EMR

Ensure your network/firewall is configured to allow inbound connections from the below URLs for seamless integration with Eka Care EMR.

## Production

* **Allowed URLs:**
  * `*.eka.care`

## Staging

* **Allowed URLs:**
  * `*.dev.eka.care`

## S3 Bucket URLs

* `*.s3.ap-south-1.amazonaws.com`

***

> eka.care and dev.eka.care URL's are hosted on AWS Cloudfront, Make sure you have allowlisted [AWS CloudFront IP Addresses.](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/LocationsOfEdgeServers.html)


# Changelog
Source: https://developer.eka.care/docs/get-started/changelog

Latest updates and improvements to the Eka Developer Platform.

Get weekly developer updates in your inbox

New features, SDK releases, API changes, and bug fixes — delivered every week. No spam. Unsubscribe anytime.

Powered by Mailchimp · Your data is safe with us

**October 28, 2026**

API, AI tools and Docs changes

## Added

* **HIE-CM: 18 webhooks added.** `abha.care_context_discover`, `abha.care_context_discover_link_init`, `abha.consent_update`, `abha.context_discover_link_confirm` and 14 more.
* **IPD: 41 calls added.** [`DELETE /protocol/workflow/sa-forms/drafts/{id}`](/api-sdk/ipd/workflows/sa-forms/drafts/delete-an-sa-form-draft), [`GET /protocol/workflow/default-events`](/api-sdk/ipd/workflows/rules/get-the-catalog), [`GET /protocol/workflow/forms`](/api-sdk/ipd/workflows/forms/list-an-entitys-forms), [`GET /protocol/workflow/forms/{id}/timeline`](/api-sdk/ipd/workflows/forms/get-a-forms-timeline) and 37 more.
* **Billing: the `eka-billing` plugin is published.** Install it in Claude Code to give your agent this product's reference skill. [Open Build with AI](/docs/billing/build-with-ai).
* **Eka EMR: the `eka-emr` plugin is published.** Install it in Claude Code to give your agent this product's reference skill. [Open Build with AI](/docs/emr/build-with-ai).
* **Health Records: the `eka-health-records` plugin is published.** Install it in Claude Code to give your agent this product's reference skill. [Open Build with AI](/docs/health-records/build-with-ai).
* **IPD: the `eka-ipd` plugin is published.** Install it in Claude Code to give your agent this product's reference skill. [Open Build with AI](/docs/ipd/build-with-ai).
* **Medical Agents: the `eka-agents` plugin is published.** Install it in Claude Code to give your agent this product's reference skill. [Open Build with AI](/docs/agents/build-with-ai).
* **Medical Document Parsing: the `eka-document-parsing` plugin is published.** Install it in Claude Code to give your agent this product's reference skill. [Open Build with AI](/docs/models/build-with-ai).
* **Medical Knowledge: the `eka-medical-knowledge` plugin is published.** Install it in Claude Code to give your agent this product's reference skill. [Open Build with AI](/docs/datasets/build-with-ai).
* **Medical Scribe: the `eka-scribe` plugin is published.** Install it in Claude Code to give your agent this product's reference skill. [Open Build with AI](/docs/scribe/build-with-ai).
* **NHCX: the `eka-nhcx` plugin is published.** Install it in Claude Code to give your agent this product's reference skill. [Open Build with AI](/docs/nhcx/build-with-ai).
* **UHI: the `eka-uhi` plugin is published.** Install it in Claude Code to give your agent this product's reference skill. [Open Build with AI](/docs/uhi/build-with-ai).

## Changed

* **Eka Developer Platform: each product has its own pages.** The product menu has 18 items, grouped under ABDM Connect, Clinical AI, More from Eka, Newsboard and Resources. Each product has its own Documentation, and its own APIs & SDKs when it has an API. Old addresses redirect to the new pages. For example, Eka EMR has [Documentation](/docs/emr/patients), [APIs & SDKs](/api-sdk/emr/instructions/before-you-begin) and [Changelog](/docs/get-started/emr-changelog).
* **Eka Developer Platform: the docs have a new look.** Every page has new background, colours and fonts. No API changes with it.

## Corrected

* **IPD: a correction to the API reference.** The reference said IPD calls sat under `/ipd/v1/sdk` and `/ipd/v1/service`. They sit under `/ipd/sdk` and `/ipd/service`, where the services run, and the calls themselves never moved. [Read the page](/api-sdk/ipd/configuration/setup/get-ipd-setup-data).

**June 2, 2026**

June 2, 2026

## &#x20;Breaking

* **\[EkaAgents] echo-sdk prompt-schema rename** — `AgentConfig`, `PersonaConfig`, and `TaskConfig` are renamed to `AgentPrompt`, `PromptPersona`, and `PromptTask` and have moved from `echo.agents.config` to `echo.prompts.schemas`. `GenericAgent` and `AgUiAgent` now require `agent_prompt=` instead of `agent_config=`, `FetchedPrompt.agent_config` is now `FetchedPrompt.agent_prompt`, and `load_agent_config()` is replaced by `load_agent_prompt()`. The old module path and kwargs are removed — callers must update imports and constructor arguments before upgrading to 0.3.3.
* **\[EkaAgents] echo-sdk skill package move** — `echo.agents.skill.Skill` is now `echo.skills.Skill`; `Skill` is no longer re-exported from `echo.agents`. Update imports to `from echo.skills import Skill`.

## Added

* **\[EMR] Appointment reschedule history on the doctor app** — Rescheduling an appointment now persists a forward/back link between the source and the newly created appointment. The old appointment record stores `next_aid` (the new appointment id) at reschedule time, and the new appointment stores `prev_aids` (the chain of prior appointment ids) and inherits the existing `receipts` so payments and services already attached to the original visit are preserved. Both fields are exposed on the `AppointmentsModel` returned by the Firestore manager.
* **\[EkaAgents] Runtime skill configuration in echo-sdk** — New `echo.skills.SkillRuntimeConfig` (name, description, `prompt_config: PromptConfig`, `tool_names`) plus a `build_skills_from_runtime()` helper that fetches every skill's prompt in parallel via the configured prompt provider and materialises them into `Skill` instances. Individual prompt-fetch failures are logged and the offending skill is dropped, so one bad skill config no longer breaks the whole turn.
* **\[EkaAgents] `PromptConfig` descriptor** — New Pydantic model for fetching prompts from a provider (currently `langfuse`), with `name`, `version`, and `prompt_variables` and automatic whitespace-stripping on `name`. Used by `SkillRuntimeConfig` and intended for host apps that wire skill prompts dynamically.

## Fixed

* **\[EMR] Property persistence for examination findings and procedures** — The prescription pad now carries the `properties` map through the local upsert path and the genie sync middleware for both examination findings and procedures. Previously the save pipeline only forwarded `id` and `name` (plus `source` for findings), so structured property-group values such as Since/Note on findings and Date/Note on procedures were silently dropped on save and never made it to the synced prescription. Both reducer paths now use the shared `normalizeExaminationEntities` / `normalizeProcedureEntities` helpers and spread the full normalised entity, and the middleware emits `properties` when present.

## Changed

* **\[EkaAgents] Langfuse prompt provider returns `AgentPrompt`** — `LangfusePromptProvider.get_prompt()` and `FetchedPrompt` now expose `agent_prompt` (was `agent_config`); the underlying Langfuse-side schema (`role`, `goal`, `backstory`, `expected_output` on the prompt config; description in the prompt text) is unchanged.

## Upgraded

* **\[Platform] echo-sdk 0.3.3** — Python package version bumped from 0.3.2 to 0.3.3 alongside the prompt-schema rename and skills package split.

**June 1, 2026**

June 1, 2026

## Added

* **\[EMR] IPD dashboard and admit-patient drawer as remote web components** — The IPD list and admit-patient flows now render through `<ipd-dashboard>` and `<ipd-admit-patient-drawer>` custom elements loaded from a remotely-hosted IPD SDK (`elixir-dr.eka.care/ipd/main/assets/index.js`, with a matching dev URL). The host app injects Firestore, `fetchWithRefresh`, and a Firestore SDK adapter into the elements, and receives callbacks for profile mount, switch-workspace mount, admit/discharge, EMAR, IPD notes, medical history, medical document, billing payments, IPD slip print, and discharge summary. This decouples IPD shipping from the main app release cycle.
* **\[EMR] `OPEN_GLOBAL_SEARCH` bridge event** — The IPD web component (and other embedded surfaces) can now request the host app to open global search by dispatching an `OPEN_GLOBAL_SEARCH` event over the `EKA_EVENT` bus. The host respects route eligibility via `canOpenGlobalSearch(pathname)` and emits a `GLOBAL_SEARCH` track with `where: 'ipd'`.
* **\[EMR] Property groups on examination findings and procedures** — The prescription pad's examination findings and procedures rows now support the same structured property-group editor previously available only on symptoms and diagnoses. Examination findings expose a `Since` prefix-suggest group (Hour/Day/Week/Month/Year) and a `Note` open-text group; procedures expose a `Date` group and a `Note` group. Each row renders a more-options modal driven by `SymDiaPropertyInput`, with backward-compatible migration from the legacy top-level `notes` string into the structured note property group on read.
* **\[EMR] `source` discriminator on examination findings** — `ExaminationEntity` now carries an optional `source: 'symptom' | 'diagnosis'` field so the pad can track whether a finding was added from the symptoms or diagnoses path, enabling correct routing of property updates back into the originating entity.
* **\[EMR] Context-scoped sym/dia properties endpoint** — `GET /v1/sym-and-diag/properties` accepts three new optional query parameters: `procedures` (comma-separated procedure ids), `resource` (`Observation` | `Condition` | `ServiceRequest`), and `category` (e.g. `symptom`, `encounter-diagnosis`, `exam`). Callers pass a `SymDiaPropertiesContext` of `symptoms`, `diagnosis`, `examination_findings`, or `procedures` and the SDK maps it to the right `resource`/`category` pair.
* **\[EMR] Capillary Blood Glucose (CBG) and Hip Circumference vitals** — Prescription pad vitals catalogue adds two new server-backed vitals: Capillary Blood Glucose (CBG) and Hip Circumference. Both accept numeric values with decimal precision and render through the standard vitals input flow alongside existing vitals.

## Improved

* **\[EMR] On-demand IPD SDK loading** — `ensureIpdSdkScriptLoaded()` lazily injects the IPD SDK `<script type="module">` only when an IPD surface is opened, dedupes parallel callers via a shared promise, and surfaces a clean error toast if the SDK fails to load. Subsequent navigations reuse the already-loaded `window.IpdSDK` and avoid re-fetching the bundle.
* **\[EMR] Templar prescription rendering for examination findings and procedures** — Templar templates now render the new structured `properties` map on examination findings and procedures alongside legacy `notes`, with PDF print-body config and local PDF generation pipelines updated to consume the merged shape. Existing templates that only use `notes` continue to render unchanged.
* **\[EMR] Property-aware caching for sym/dia lookups** — Property-group fetches are now cached per `context:id` (e.g. `examination_findings:<id>`, `procedures:<id>`) so switching between symptoms, diagnoses, findings, and procedures no longer collides on a single cache key.

## Fixed

* **\[EMR] Lab tests table search returns stale or empty results** — The Lab Tests table built its Fuse fuzzy-search index once in the constructor and never refreshed it when the underlying lab data loaded or changed, so searches would miss entries or return nothing until the page was reopened. The index now rebuilds in `componentDidUpdate` whenever `data` changes, and any active search result is cleared to avoid showing matches against the stale index.

## Migrated

* **\[EMR] IPD UI extracted to a standalone SDK** — IPD admit, dashboard, billing, slip-print, and discharge surfaces previously bundled inside the doctor web app are now served from a separately-versioned IPD SDK and consumed through custom elements. The host app retains orchestration (Redux state, navigation, AI prompts for discharge summaries, PDF generation) and forwards data and callbacks into the elements.

## Hardened

* **\[Platform] JWT context propagation across appointment communication service** — Introduced an `AsyncLocalStorage`-backed request-context middleware that captures the caller's JWT identity (`cid`, `idp`) at the edge and threads it through all downstream messenger and appointment-event lookups without manual plumbing. Outbound bulk-review, reminder, reschedule, refund, receipt, payment, and cancellation payloads now carry the originating identity automatically, removing a class of bugs where context could be lost across async boundaries and tightening auditability of partner-triggered communications.
* **\[Platform] JWT-scoped attribution on patient messaging** — The patient messaging pipeline (welcome, prescription, self-assessment, and post-action communications) now propagates the authenticated caller's `c-id` and `idp` claims from the request JWT into messenger `lookup_params` alongside `khata_key`. This routes downstream billing and rate-limiting against the correct identity provider and client tenant for every SMS, WhatsApp, and push notification triggered via khata.

## Fixed

* **\[EMR] Lab tests browse-panel search returning empty/stale results** — The Fuse search index on the lab tests table was being built once in the constructor against the initial (often empty) `data` prop, so the first search after data finished loading returned no matches and later prop updates were ignored. The index now rebuilds whenever the underlying `data` prop changes, and any active search result is cleared on rebuild so users see fresh matches without having to reload the panel.

## Changed

* **\[EMR] `ExaminationEntity` shape** — `ExaminationEntity` gains optional `properties: { [k: string]: SymDiaProperty }` and `source` fields and is exported from `prescription-types-bundle`. The legacy `notes: string` field is preserved for read-compatibility but new writes route through the `pg-5243973452` note property group; consumers reading examination notes should prefer the property-group value and fall back to `notes`.
* **\[EMR] `Procedure` shape** — `Procedure` gains optional `properties: { [k: string]: SymDiaProperty }`. Date is now authored via the structured `Date` property group (`pg-31705165`) rather than the free `date` string; the `date` field remains for back-compat reads.

**May 30, 2026**

May 30, 2026

## &#x20;Breaking

* **\[Platform] eka-usage-sdk metric-type cleanup** — Dedicated error metrics are removed across all three SDKs (Go, Python, TypeScript). The `agent` metric drops `credit_consumed` and `tool_call_error`; `emr_tools` and `clinical_tools` drop `tool_call_error`. Record tool and agent error outcomes by emitting the corresponding metric with `status="error"` instead. The `agent` metric also adds a new `message` type for conversational events.

## Added

* **\[Platform] IDP-aware billable tagging in eka-usage-sdk** — `record()` now accepts optional `idp` and `c_id` parameters (Python kwargs, TS trailing args, Go `WithIDP` / `WithCID` options) sourced from the request JWT by the caller — the SDK does no token parsing or I/O. `is_billable` is set to `1` only when `status == "ok"` **and** `idp == "api-key"`; every other caller (SaaS/subscription, internal jobs, error outcomes, no-context callers) emits `0`. The new `c_id` (API key id) is copied verbatim into the payload for per-API-key analytics and defaults to `""`. `idp` itself is never written to the payload.

## Fixed

* **\[Platform] Stale ABDM metric names in eka-usage-sdk docs** — Documentation now reflects the current ABDM metric set (`abha`, `linking`, `data_transfer`), replacing the outdated names.

## Upgraded

* **\[Platform] eka-usage-sdk → 0.2.0** — Go, Python, and TypeScript SDKs all bumped to `0.2.0` (TS tag `ts-v0.2.0`) covering the IDP-aware billing tags and metric-type cleanup above.

**May 29, 2026**

May 29, 2026

## Added

* **\[EkaScribe] MedScribe Alliance TS SDK feature update** — The `@eka-care/medscribe-alliance-ts-sdk` ships a feature refresh (LIFE-1696) covering 13 files with new/updated session and recording surfaces. Pull the latest tag and review the diff for the full surface.

## Improved

* **\[EMR] Server-synchronized time in Health Records Android SDK** — `TimeProvider` now tracks a server-time offset persisted via `SharedPreferences`, with `RecordsSync` parsing the `Date` header from server responses to keep the offset current. `FileEntity`, `FileStorageManagerImpl`, and `RecordsRepositoryImpl` use `TimeProvider.nowMillis()` / `nowSeconds()` instead of `System.currentTimeMillis()`, so `createdAt`, `updatedAt`, and `lastUsed` stay consistent across devices with skewed clocks.
* **\[EMR] Stale-analysing record reset in Health Records Android SDK** — `RecordsDao.resetStaleAnalysingRecords` now clears the `is_analysing` flag for documents that have been stuck in analysis past a cutoff, and the reset is triggered automatically when records are read — so a crashed or interrupted parse no longer leaves a document permanently in the analysing state.
* **\[EMR] Analysing state consolidated into SmartTag** — The `android-document-ui` records grid removes its centered analysis progress indicator and separate blur/background treatment; `SmartTag` now drives both the "Smart" and "Analysing" states via an `isAnalysing` parameter (circular progress + "Analysing" text). Simpler conditional modifiers in `RecordsGridItem`, single source of truth for the tag visuals.

**May 27, 2026**

May 27, 2026

## Added

* **\[EkaScribe] startRecordingV2 in Eka JS SDK** — `@eka-care/eka-js-sdk` adds a `startRecordingV2` method that exposes the next-generation EkaScribe recording flow to JS consumers, alongside the existing `startRecording`. Use the V2 entry point for new integrations.
* **\[EMR] Date on Templar pt attribute** — The `pt` attribute in Templar templates now carries a `date` field, enabling richer rendering of patient-attached events with explicit dates on receipts and prescriptions.

**May 25, 2026**

May 25, 2026

## Added

* **\[EkaScribe] Scribe UI widget in Eka JS SDK** — `@eka-care/eka-js-sdk` adds a packaged UI widget for the scribe recording flow, giving integrators a drop-in surface for capture, status, and transcript display instead of wiring those primitives by hand.

**May 22, 2026**

May 22, 2026

## Changed

* **\[EMR] Gson-based parameter parsing in AddRecordPreviewActivity** — `android-document-ui` swaps manual `JSONObject` parsing for `Gson().fromJson` when reading the intent's params payload, and removes explicit `finish()` calls during initial validation — simpler initialization, fewer transient activity teardowns on malformed input.

**May 21, 2026**

May 21, 2026

## Added

* **\[EkaAgents] show\_appointments\_basic and get\_patient\_appointments\_basic in Eka MCP SDK** — `eka-mcp-sdk` v0.1.40 enables `show_appointments_basic` (list appointments with filters) and v0.1.41 adds `get_patient_appointments_basic` (fetch appointments for a specific patient), giving agents direct read access to the appointments surface without bespoke tool wiring. [View docs](/docs/datasets/build-with-ai/mcp-server/tools)
* **\[EMR] GST on Templar receipts** — Templar receipt templates now print GST on receipts, surfacing tax breakdown alongside the line items.

## Changed

* **\[EkaAgents] show\_appointments\_basic patient\_id filter constraint** — `show_appointments_basic` in `eka-mcp-sdk` now treats `patient_id` as a single-value filter — when a patient id is supplied, other filters are ignored — making the contract explicit and reducing ambiguous query combinations.

**May 20, 2026**

May 20, 2026

## Added

* **\[Platform] Custom Interceptor list in EkaNetwork Android** — `EkaNetwork.init` now accepts an optional list of OkHttp `Interceptor`s (stored per `appId`) and propagates them through `RetrofitServiceCreator` to both the `AuthApi` and dynamically-created services. `@JvmOverloads` is added for Java interop. Hosts can now plug in their own logging, tracing, or header interceptors without forking the network layer.

## Upgraded

* **\[EkaScribe] Eka Scribe Android → ekaNetworkAndroid 2.0.6** — `Eka-Scribe-Android` bumps the `ekaNetworkAndroid` version catalog entry from 2.0.5 to 2.0.6 to pick up the custom-interceptor support.
* **\[EMR] Health Records Android → network 2.0.6** — `eka-health-records-android` bumps the `network` library in `gradle/libs.versions.toml` from 2.0.5 to 2.0.6.
* **\[EMR] android-document-ui → records 3.3.1** — `android-document-ui` bumps the records dependency from 3.3.0 to 3.3.1.

**May 19, 2026**

May 19, 2026

## Added

* **\[EkaAgents] CRM lead-creation tool in Eka MCP SDK** — `eka-mcp-sdk` ships a new MCP tool for creating CRM leads, letting agents capture and route a lead in the same conversation flow as discovery and booking.
* **\[EkaAgents] AG-UI streaming in Echo Agent Kit** — `echo-sdk` adds AG-UI streaming support so agents can emit incremental UI updates to compatible clients during a turn instead of buffering the full response.
* **\[EkaAgents] Claude prompts in Echo Agent Kit** — `echo-sdk` adds prompt support for Anthropic Claude models, broadening the LLM provider mix available to agents built on the kit.

## Changed

* **\[EMR] Templar OPD slip moved from string templates to JSX** — Templar's OPD slip is rewritten from string-concatenated templates to a JSX-rendered template, aligning it with the rest of the template engine and unlocking more structured composition for downstream changes.

**May 18, 2026**

May 18, 2026

## Improved

* **\[EMR] AddRecordPreview stability and performance in android-document-ui** — Image URI resolution and large-image validation in `AddRecordPreviewScreen` move to a background thread (`LaunchedEffect` + `Dispatchers.IO`); the preview list now hands `File` objects directly to `AsyncImage` instead of decoding bitmaps and computing orientation on the UI thread. The "Add Details" bottom sheet is gated on PDF resolution. `FileSharing` switches to `MediaStore` for downloads on Android Q+, with stream-based copy to public Downloads and URI-segment-based PDF detection. Temporary files now live in a dedicated `records_temp` cache sub-directory with better cleanup on failure.

## Fixed

* **\[EMR] AddRecordPreviewActivity initialization on malformed params** — Manual `JSONObject` parsing of intent params now runs inside proper try/catch with `finish()` calls when params are missing or malformed, so the activity can no longer persist in an invalid state on bad input.

**May 17, 2026**

May 17, 2026

## Added

* **\[EkaAgents] Agent skills in Echo Agent Kit** — `echo-sdk` introduces a skills concept for building modular, reusable agent capabilities that can be composed into larger workflows.

## Fixed

* **\[EMR] Missing source files during record creation in Health Records Android** — `RecordsRepositoryImpl` now checks each source file's existence before processing or compression, logs a sync event with the document, business, and owner IDs when a file is missing, and returns `null` early so the broader record-creation path no longer surfaces a hard error when a single file has gone missing locally.

**May 15, 2026**

May 15, 2026

## Added

* **\[EMR] examinationFindings property group in Templar** — Templar adds a new `examinationFindings` property group with backward-compatible support for legacy notes, so prescriptions and clinical templates can render structured examination findings without breaking existing notes-only content.

## Improved

* **\[EkaAgents] doctor\_availability success response in Eka MCP SDK** — `eka-mcp-sdk` enriches the success response from the doctor availability flow so downstream booking tools have the context they need without re-querying.

## Fixed

* **\[EMR] Text wrapping on Templar receipts** — Fixed a Templar rendering bug where text was not breaking to the next line as expected; content now wraps correctly inside its container.

**May 14, 2026**

May 14, 2026

## Improved

* **\[EkaAgents] Selected hospital pushed to the top in Eka MCP SDK** — `eka-mcp-sdk` now surfaces the user's selected hospital at the top of availability listings, so chosen-hospital options aren't buried under nearby alternatives during a booking flow.

**May 13, 2026**

May 13, 2026

## Added

* **\[Platform] Java bindings for ABDM ECDH primitives** — The `abdm-ecdh` project adds a Java implementation of the ECDH primitives required for ABDM data-fetch flows, alongside the existing Python and Go bindings — making it easier for JVM-based HIP/HIU integrations to handle ABDM consent and data exchange.

## Hardened

* **\[Platform] CI for ABDM ECDH** — The `abdm-ecdh` repository gains a continuous integration pipeline so changes across the Python, Go, and Java surfaces are built and validated on every PR.

## Fixed

* **\[Platform] ABDM ECDH Python release pipeline** — Corrected the Python release configuration in `abdm-ecdh` so the package now publishes cleanly from the release workflow.

**May 12, 2026**

May 12, 2026

## Fixed

* **\[Platform] Aakaar EditableTable bottom AutoSuggest dropdown anchoring** — The bottom-row `AutoSuggest` dropdown in `EditableTable` was portalled to `document.body` and only realigned on window scroll or resize, so it could drift to a stale position after a row was added without triggering a page scroll, and it could hold a stale portal position that blocked user scroll after mass-clearing rows. The dropdown now uses a `getPopupContainer` that resolves to the nearest scrollable ancestor, so `rc-trigger` places it inside the same scroll context as the trigger and realigns natively on layout changes — no manual resize dispatch or blur-on-clear workaround required. `EditableTableProps` also exposes an optional `getPopupContainer` for callers with non-standard scroll hierarchies (virtualised lists, nested portals).

**May 8, 2026**

May 8, 2026

## Added

* **\[EkaScribe] Pause and resume in MedScribe Alliance TS SDK** — The MedScribe Alliance TypeScript SDK now exposes `pause` and `resume` methods, letting integrators temporarily halt and continue an in-progress scribe recording without ending or restarting the session. Useful for handling interruptions mid-consultation.

**May 7, 2026**

May 7, 2026

## &#x20;Breaking

* **\[EMR] Templar receipt patient age field** — The `TPdfObject` type used by `getPatientIntroForReceipt` replaces the numeric `ageInM?: number` field with a string `age?: string`. Callers must now pass a pre-formatted age (for example, `"5 Years 3 Months"`) instead of months as an integer; the previous "compute years from months" behaviour has been removed in favour of richer year-and-month rendering. Update any caller that was passing `ageInM` to pass `age` instead.

## Added

* **\[EkaScribe] EkaScribe TS SDK getDocument, getSessionDetails, and existing-session resume** — `@eka-care/ekascribe-ts-sdk` v2.1.50 adds three new instance methods: `getDocument(document_id)` (fetch a document by id), `getSessionDetails({ session_id, presigned })` (fetch full session metadata, documents, and `user_status` lifecycle), and `startRecordingForExistingSession({ txn_id, business_id, created_at, microphoneID?, sharedWorkerUrl?, flavour? })` (resume recording for a previously initialised session by reconstructing the audio pipeline and session bucket path). New `TGetV1SessionDetailsResponse`, `TSessionDocument`, and related types are exported. [View docs](/api-sdk/scribe/sdks/ekascribe-ts-sdk)

* **\[EkaScribe] Document publish payload in EkaScribe TS SDK** — `postV1Document` and the `getV1Document` response now carry an optional `publish: Record<string, unknown>` payload, allowing integrators to send and read structured publish metadata alongside a session document.

* **\[EkaScribe] user\_status on patchTransactionStatus** — `patchTransactionStatus` now accepts an optional `user_status` field, mirroring the lifecycle states (`init`, `recording_started`, `commit`) returned by `getSessionDetails`, so clients can advance the user-side status on a session in one call.

## Improved

* **\[EkaScribe] Hardened VAD lifecycle in EkaScribe TS SDK** — `VadWebClient` now wraps `startVad`, `pauseVad`, `destroyVad`, `resetVadWebInstance`, `reinitializeVad`, and the silent-audio monitor in defensive try/catch blocks, and `monitorAudioCapture` now guards `micVad.pause()` with an existence check. Errors are logged via `[EkaScribe]` console output instead of bubbling up and breaking the host page. The `EkaScribe` facade applies the same protection around `reinitializeVad`, `destroyVad`, and `pauseVad`.

* **\[EMR] Patient age rendering on receipts** — `getPatientIntroForReceipt` now prints the patient's full age string (years and months) on receipts instead of computing only whole years from months, giving a more clinically meaningful age label.

**May 6, 2026**

May 6, 2026

## Added

* **\[EkaAgents] service\_availability\_elicitation and book\_service in Eka MCP SDK** — The Eka MCP SDK gains two new tools for service and health-package booking flows: `service_availability_elicitation` (interactive UI tool that lets users discover services, view available dates, and pick a slot — accepts either `suggested_service_ids` or a single `service_id`, plus optional `hospital_id`, `preferred_date`, and `preferred_slot_time`) and `book_service` (creates a health-package booking from a `ServiceBookingRequest` with deduplication of concurrent calls and slot-unavailable handling). The shared elicitation builder was also generalised with an `entity_type` parameter so the same UI contract powers both doctor and service flows. [View docs](/docs/datasets/build-with-ai/mcp-server/tools)

* **\[EMR] Analysing UI in Health Records Android and Document UI** — The Eka Health Records Android SDK and `android-document-ui` module introduce an "analysing" state UI for documents under processing, surfacing parse-in-progress to end users instead of leaving the document in an ambiguous state. Internal core SDK contracts were adapted to drive the new UI cleanly. [View docs](/api-sdk/sdks/sdks/android/medical-records)

## Improved

* **\[EkaAgents] doctor\_availability\_elicitation now returns selected\_doctor\_id and selected\_hospital\_id** — When the elicitation completes successfully, the tool result now includes `selected_doctor_id` and `selected_hospital_id` in `_meta.tool_result`, so downstream booking tools can chain off the elicitation output without re-prompting the user.

## Fixed

* **\[EkaScribe] Session polling now surfaces failures as ERROR** — `SessionManager` in the EkaScribe Android SDK now transitions to `ERROR` (instead of `COMPLETED`) when transcript or full-output polling fails or times out. Failed transcript polls also short-circuit subsequent full-output polling, and `handleTransactionError` is consistently invoked on failures so users can recover and start a new session. Test scenarios were updated to reflect the new contract.

**May 5, 2026**

May 5, 2026

## Improved

* **\[EkaAgents] doctor\_availability\_elicitation aligned with search\_doctor\_tool** — The Eka MCP SDK removes the legacy `doctor_discovery` tool references and updates `doctor_availability_elicitation` to consume results from `search_doctor_tool`. The tool description and UI contract were updated to render multiple doctor cards in a single elicitation, and `suggested_doctor_ids` is now an accepted input parameter so an agent can hand a shortlist directly to the elicitation. [View docs](/docs/datasets/build-with-ai/mcp-server/tools)

* **\[EMR] IPD billing print totals** — The IPD billing print template (`getBodyForIpdBilling`) now computes Total Amount as `Σ(MRP × Qty)`, derives Total Discount from the difference with the line-item-discounted total, and renders an explicit Grand Total alongside Total Paid and amount due. The output replaces the previous Total MRP / Line Item Discount / Total Amount layout with a clearer Total Amount / Total Discount / Grand Total breakdown.

**May 2, 2026**

May 2, 2026

## Added

* **\[EkaAgents] Audio transcription module in Echo Agent Kit** — Echo Agent Kit adds a new `echo.audio` module with a `BaseTranscriber` interface, a `TranscriberConfig` model, and two pluggable providers: `GeminiTranscriber` (Gemini 2.0 / 2.5 audio models) and `EkaCareTranscriber` (Eka Care ASR over HTTPS, supporting `en-IN`, `en-US`, and `hi`). Audio can be supplied as raw bytes (with explicit `mime_type`), a public URL, or a Gemini Files API URI. A new `echo[ekacare]` extra pulls in `httpx` for the Eka Care provider. `get_transcriber(config)` and `generate_transcriber_config(...)` factory helpers make it straightforward to swap providers without rewriting agent code. [View docs](/docs/agents/agent-kit/introduction)

## Upgraded

* **\[EkaAgents] Echo Agent Kit v0.1.34** — Echo Agent Kit released as v0.1.34 with the new audio transcription module bundled in. The Gemini install hint also corrected from `google-generativeai` to `google-genai`. `pip install -U echo` is safe — defaults preserve existing agent behavior.

**May 1, 2026**

May 1, 2026

## Added

* **\[EkaAgents] Skills in Echo Agent Kit** — `GenericAgent` now supports `Skill` — a lazy-loaded bundle of `(instructions + tools + description)` that can be attached and detached mid-conversation. Two activation modes are supported: `llm` (default, agent auto-injects `load_skill` / `unload_skill` meta-tools and an `<available_skills>` registry into the system prompt so the model self-routes) and `manual` (host calls `await agent.activate_skill(name)` from an upstream router). Skills also expose `on_activate` / `on_deactivate` lifecycle hooks for tenant-scoped setup or telemetry, and tool-name collisions across base tools and skills are caught at agent construction. Existing agents that don't pass `skills=` are byte-for-byte unaffected. [View docs](/docs/agents/agent-kit/agents)

* **\[EkaAgents] Postgres engine and PgQueryTool in Echo Agent Kit** — Echo Agent Kit now ships an opt-in Postgres client (`echo[postgres]` extra) backed by an `asyncpg` connection pool with lazy initialization, plus `PgQueryTool` — a `BaseTool` subclass that runs a parametric SQL query and returns rows. SQL files can use psycopg-style `%(name)s` placeholders, which the client rewrites to asyncpg `$N` positional binds. A process-wide default client can be registered with `set_default_client(...)` so dynamic loaders that call `tool_class()` resolve correctly. Configuration is read from `ECHO_PG_*` environment variables. [View docs](/docs/agents/agent-kit/tools)

* **\[EMR] pageBreakTableTr in Templar getHead** — The `getHead` helper in the Templar prescription engine now supports `pageBreakTableTr`, allowing template authors to declare table-row level page breaks for cleaner multi-page prescription rendering.

## Improved

* **\[EkaAgents] Echo Agent Kit v0.1.33** — Echo Agent Kit released as v0.1.33 with the new Skills primitive, Postgres engine, and `PgQueryTool` bundled in. `pip install -U echo` is safe — defaults preserve existing agent behavior.

* **\[EMR] Diet chart authoring in Templar** — Diet chart support in the Templar prescription engine has been extended with additional structure and rendering refinements, building on the diet chart sections introduced on April 22.

**April 30, 2026**

April 30, 2026

## Added

* **\[Platform] ABDM ECDH Python package** — The ABDM ECDH key-exchange primitives used for secure consent and data-fetch flows are now distributable as a Python package, making it easier for partners to integrate ABDM-aligned encryption helpers without re-implementing the protocol.

**April 29, 2026**

April 29, 2026

## Improved

* **\[EMR] Doctor name on IPD receipts and bills** — IPD receipt and bill print output now uses the doctor profile's first-name and last-name fields directly instead of a single concatenated string, giving cleaner, more consistent doctor-name rendering across IPD billing artifacts.

**April 28, 2026**

April 28, 2026

## Added

* **\[EMR] forceApiSearch flag in Patient Directory TS SDK** — The Patient Directory TypeScript SDK now exposes a `forceApiSearch` option, letting integrators bypass the local cache and force a live API lookup for patient search — useful for high-confidence lookups where freshness must beat latency.

## Fixed

* **\[EMR] Patient Directory TS SDK lookup correctness** — Resolved an edge case in the Patient Directory TypeScript SDK where stale or partial cached state could surface incorrect patient search results; lookups now consistently reflect the live directory.

**April 27, 2026**

April 27, 2026

## Improved

* **\[EMR] Clinic name on OPD slip** — The Templar OPD slip print template now renders the clinic name in the slip header, improving identifiability of the issuing clinic on physical copies.

* **\[EkaAgents] MedAssist web file upload validation** — The MedAssist web widget now validates uploaded files against an updated allow-list of supported file types, surfacing a clear rejection for unsupported formats before the upload is attempted.

## Fixed

* **\[EkaAgents] \[Client-Specific] MedAssist web widget configuration** — Resolved a configuration regression that caused the MedAssist web widget to behave incorrectly on a partner deployment; the widget now initializes with the expected configuration on that surface.

**April 24, 2026**

April 24, 2026

## Changed

* **\[EkaAgents] Mobile number mandatory for profile creation in MCP SDK** — The MCP SDK now requires a mobile number when creating a patient profile, ensuring downstream integrations always have a contactable identifier. Existing profile creation flows must include this field. [View docs](/docs/emr/build-with-ai/mcp-server/supported-tools)

**April 23, 2026**

April 23, 2026

## Improved

* **\[EkaAgents] \[Client-Specific] Doctor card revamp** — Doctor discovery cards in the MCP SDK have been redesigned for the EMR client, with refreshed layout and additional doctor metadata surfaced inline. [View docs](/docs/emr/build-with-ai/mcp-server/supported-tools)

## Changed

* **\[Platform] ABDM usage metrics events** — The eka-usage-sdk now emits the latest ABDM-related usage events to Kafka, keeping the metrics pipeline aligned with current ABDM consent and linking flows.

**April 22, 2026**

April 22, 2026

## Added

* **\[EkaAgents] MCP session caching in Echo Agent Kit** — The Echo Agent Kit MCP integration now caches MCP sessions per user, splitting tool discovery and session caches with independent idle and absolute TTLs, LRU eviction on pool exhaustion, and `user_session_id` plumbed through `MCPTool.run` via `tool_context`. Tool cache keys are partitioned by configurable headers (`tool_cache_key_headers`), and concurrent cache misses are serialized to avoid duplicate discovery work. [View docs](/docs/agents/agent-kit/mcp-integration)

* **\[EkaAgents] Doctor discovery elicitation** — The MCP SDK now supports interactive elicitation for `doctor_discovery` cards, allowing agents to confirm doctor availability mid-conversation before booking. [View docs](/docs/emr/build-with-ai/mcp-server/supported-tools)

* **\[EMR] Diet charts in prescription templates** — The Templar prescription engine now supports diet chart sections, enabling structured diet plans to be authored and rendered alongside prescriptions.

## Improved

* **\[EkaAgents] MCP tool call timeout** — Tool calls in the Echo Agent Kit MCP integration are now bounded by a 10-second timeout, preventing slow downstream tools from blocking agent responses indefinitely.

* **\[EMR] Unit display name fallback in prescriptions** — Prescription `rx` and `labVitals` sections now render `unit_display_name` when available and fall back to `name`, producing cleaner unit labels on printed prescriptions.

## Fixed

* **\[EMR] IPD admission TinyMCE preview** — Fixed a rendering bug where the IPD admission rich-text preview was showing stale or malformed HTML in the Templar template engine.

## Removed

* **\[EkaAgents] Legacy MCP caching layer** — The previous monolithic MCP cache has been removed from the Echo Agent Kit in favor of the new split tool/session caching design.

**April 21, 2026**

April 21, 2026

## Fixed

* **\[Platform] Android document UI PDF initialization** — Fixed a crash where PDF rendering could initialize before view layout constraints were available, producing zero-sized canvases on some devices.

## Changed

* **\[EMR] Prescription QR placement** — The QR code on prescription PDFs has been moved into the footer details block for a cleaner header and consistent placement across templates.

**April 20, 2026**

April 20, 2026

## Added

* **\[EMR] IPD admission template upgrades** — The Templar prescription engine adds new fields and layout improvements to the IPD admission template, supporting richer admission notes.

## Improved

* **\[EkaScribe] Voice-to-text error handling on iOS DocAssist** — DocAssist for iOS now detects and surfaces voice-to-text failure scenarios with a clear error state instead of silently dropping the recording, making transient transcription errors recoverable for the user.

## Fixed

* **\[EkaAgents] MedAssist web microphone restored** — A temporary disablement of the microphone capture path in the MedAssist web widget was reverted on the same day after a regression was identified, restoring voice input.

**April 18, 2026**

April 18, 2026

## Added

* **\[EkaAgents] Contextual popup in MedAssist web widget** — The MedAssist web chat widget now supports a contextual popup, surfacing relevant suggestions and actions tied to the current conversation state.

## Improved

* **\[EkaAgents] MedAssist nudge configurability** — The onboarding nudge in the MedAssist web widget can now be disabled by integration partners that don't want unsolicited prompts on first load.

## Fixed

* **\[EkaAgents] Agent ID resolution in MedAssist web** — Fixed a bug where the MedAssist web widget could resolve to the wrong agent ID under certain configurations, ensuring conversations always route to the configured agent.

## Upgraded

* **\[Platform] eka-usage-sdk 0.1.1** — The eka-usage-sdk has been published at version 0.1.1, fixing the test runner and shipping the latest Kafka usage metric event definitions.

**April 17, 2026**

April 17, 2026

## Improved

* **\[EkaScribe] Android SDK MP3 encoding** — The EkaScribe Android SDK now uses MP3 encoding (via LAME) instead of AAC/MP4, producing raw MPEG Layer III bitstreams for more reliable audio chunk uploads. The AAC encoder and MP4 format option have been removed. [View docs](/api-sdk/scribe/sdks/android-sdk)

* **\[EkaScribe] Android SDK partial output polling** — Transaction result polling in the Android SDK now checks statuses across `integration`, `transcript`, and `custom` fields within `templateResults`, replacing the legacy `output` list. Empty statuses are treated as failures instead of timing out, improving error detection. [View docs](/api-sdk/scribe/sdks/android-sdk)

* **\[EkaScribe] iOS SDK parallel chunk processing** — The EkaScribe iOS SDK now processes audio chunks in parallel, improving transcription throughput and reducing end-to-end latency for longer recording sessions.

* **\[EkaAgents] Doctor discovery tool in MCP SDK** — The Eka MCP SDK now includes a doctor discovery tool for EMR workspaces, enabling agents to search for available doctors within a clinic context. [View docs](/docs/emr/build-with-ai/mcp-server/supported-tools)

* **\[EkaAgents] MedAssist web widget responsive layout** — The MedAssist web chat widget now renders correctly on small screens (under 360px and 767px widths), preventing layout overflow and improving usability on mobile devices.

**April 16, 2026**

April 16, 2026

## Added

* **\[EkaAgents] OTP authentication for EMR clients in MCP SDK** — The Eka MCP SDK now includes an `authentication_elicitation` tool enabled by default for EMR workspaces, supporting SMS-based OTP login with country code selection, OTP verification, and UHID profile selection. Agents can authenticate clinic users mid-conversation without leaving the AI client. [View docs](/docs/emr/build-with-ai/mcp-server/authentication)

* **\[EkaScribe] Document management in JS SDK** — The EkaScribe JS SDK now exposes `createDocument`, `deleteDocument`, and `getChunkTranscript` methods, enabling programmatic document lifecycle management and per-chunk transcript retrieval directly from the SDK. [View docs](/api-sdk/scribe/sdks/ekascribe-ts-sdk)

## Improved

* **\[EkaScribe] Output polling parameters in JS SDK** — The `pollOutputSummary` method now accepts `document_id` and `dlp` query parameters, and the status API response type includes `document_id` and `document_path` fields. The status API timeout has been increased from 16s to 20s for improved reliability. [View docs](/api-sdk/scribe/sdks/ekascribe-ts-sdk)

* **\[EkaAgents] MCP SDK workspace tool fallback** — When a workspace has no explicitly configured tool list, the MCP SDK now falls back to the default EMR tool set instead of failing, improving resilience for new workspace onboarding.

**April 15, 2026**

April 15, 2026

## Improved

* **\[EMR] Prescription PDF asset loading** — S3-hosted assets such as doctor signatures in prescription PDFs now include cache-busting query parameters, preventing stale cached versions from appearing. Signature display is also now controlled by a `show_signature` configuration flag for more flexible template rendering. [View docs](/docs/emr/prescription)

* **\[EMR] Eye exam ordering in prescription PDFs** — Ophthalmology examination tables in prescription PDFs now render in the correct display order, ensuring eye-care data appears consistently across generated documents. [View docs](/docs/emr/prescription)

* **\[EMR] Patient Directory API extras field** — The `extras` field in the Update EMR User endpoint now documents restrictions: no nested lists, no dictionaries inside lists, only one level of nesting in dictionaries, keys must not exceed 16 characters, and keys starting with `_` are ignored. [View docs](/api-sdk/emr/patient-directory-apis/update-emr-user)

**April 14, 2026**

April 14, 2026

## Added

* **BODHI open-source clinical knowledge graphs** — Two SNOMED-linked knowledge graphs (bodhi-s for condition–symptom mapping and bodhi-m for concept–drug–lab investigation mapping) are now publicly available. The graphs contain 9,300+ nodes and 16,700+ relationships across six formats (Neo4j, CSV, JSONL, PyG, RDF/Turtle, browser JSON), supporting symptom checking, differential diagnosis, and patient health profiling use cases. Released under CC BY-NC 4.0.

## Improved

* **\[Client-Specific] Prescription PDF template engine** — Added support for configurable prescription template styles, enabling custom PDF layouts that map clinical data (symptoms, history, vitals, medications, investigations, diagnosis, advices, review, and signature) to form-specific positions. A new `template_style` configuration option controls which layout is applied during PDF generation.

**April 13, 2026**

April 9–13

## Improved

* **IPD billing PDF layout** — The pricing summary in IPD billing PDFs now displays Total Paid and Amount Due/Overpaid labels, replacing the previous single "Amount to be paid" line for clearer printed output. [View docs](/docs/billing/payments)

* **OPD slip enhancements** — OPD slips now print tags and additional data fields, and the token number font size has been increased for better readability at the front desk.

* **Echo Agent Kit** — Empty prompt variables are now handled gracefully, preventing errors when prompt templates contain optional or unfilled placeholders. [View docs](/docs/agents/agent-kit/tools)

* **Medical Records Android SDK** — Oversized images are now validated before upload with a clear user alert, and PDF URI resolution has been moved to a background thread to prevent main-thread crashes.

## Fixed

* **Health Records Android SDK** — Missing files during record processing are now handled gracefully instead of causing crashes, with improved error handling in MD5 checksum generation.

**April 13, 2026**

Week of April 8–13

## Updates

* **EkaScribe documentation revamped** — The EkaScribe docs now include a Quick Start guide with a step-by-step TypeScript SDK integration walkthrough. Integration methods are reordered to recommend SDKs first, REST APIs second, and Chrome Extension third. SDK sidebar titles use proper casing, and deprecated APIs are nested under a warning section for clarity. [View docs](/docs/scribe/quickstart)

**April 11, 2026**

Week of April 8–11

## Updates

* **EkaScribe documentation revamped** — A new [Quick Start guide](/docs/scribe/quickstart) walks you through installing the SDK and transcribing your first consultation in minutes. SDKs are now promoted as the recommended integration path, and v1 APIs are marked deprecated with clear migration pointers to the [v2 APIs](/api-reference/health-ai/ekascribe/ekascribe-v2/overview). [View docs](/docs/scribe/overview)

* **Retrieve EMR User API** — A new GET endpoint is available in the Patient Directory to retrieve an EMR user profile by OID, complementing the existing update endpoint. [View docs](/api-sdk/emr/patient-directory-apis/retrieve-emr-user)

**April 9, 2026**

Week of April 6–9

## New features

* **New Patient Directory APIs** — Two new endpoints are now available in the Patient Directory: retrieve a patient profile by username, and update an EMR user profile (name, contact details, blood group, salutation, and custom fields). [View docs](/api-sdk/emr/patient-directory-apis/retrieve-patient-by-username)

## Updates

* **EkaScribe documentation revamped** — The EkaScribe docs have been restructured with a new [Quick Start](/docs/scribe/quickstart) guide, reordered integration methods (SDKs recommended first, then REST APIs, then Chrome Extension), improved SDK sidebar titles, and deprecated APIs now nested under a warning group for clarity. [View docs](/docs/scribe/overview)

**April 8, 2026**

Week of April 6–8

## Release Notes — April 8, 2026

> 13 changes · EkaScribe, EkaAgents, EMR, Platform

### &#x20;EkaScribe

* Added — New [Quick Start](/docs/scribe/quickstart) guide with a complete TypeScript SDK integration walkthrough, from credentials to first transcription.
* Improved — EkaScribe documentation restructured: SDKs promoted above REST APIs as the recommended integration path, sidebar titles corrected (proper casing for iOS, TypeScript, etc.), and deprecated API endpoints clearly nested with warning indicators. [View docs](/docs/scribe/overview)

### &#x20;EMR

* Added — Two new Patient Directory endpoints: retrieve a patient profile by username and update an EMR user profile (name, contact details, blood group, salutation, and custom fields). [View docs](/api-sdk/emr/patient-directory-apis/retrieve-patient-by-username)

### &#x20;EkaAgents

* Added — ABHA login and profile tools in the MCP SDK. Agents can now initiate ABHA login via mobile, Aadhaar, ABHA number, or PHR address, verify OTP, select from multiple profiles, and retrieve the ABHA card — all within a single agent conversation. [View docs](/docs/emr/build-with-ai/mcp-server/supported-tools)
* Improved — `_meta` field forwarding in `doctor_discovery` and `doctor_availability` MCP tools. MCP clients can now pass additional metadata (UI hints, session context) when invoking these tools. [View docs](/docs/emr/build-with-ai/mcp-server/supported-tools)
* Improved — MedAssist iOS background session handling. Chat sessions now reconnect automatically after app backgrounding, preventing conversation loss mid-interaction.
* Fixed — MedAssist iOS WebSocket error handling. Session timeouts and connection drops are now surfaced with clear error messages instead of failing silently.

### &#x20;EMR

* Improved — Prescription PDFs now include pachymetry, Amsler grid, and contact lens examination tables for ophthalmology visits, expanding printed eye-care data. [View docs](/docs/emr/prescription)

### &#x20;Platform & Infrastructure

* Improved — MCP Server documentation restructured into separate [Remote MCP](/docs/emr/build-with-ai/mcp-server/remote-mcp) and [Local MCP SDK](/docs/emr/build-with-ai/mcp-server/local-mcp) guides with per-client setup instructions, a comparison table, and clearer onboarding for both OAuth and API-credential flows. [View docs](/docs/emr/build-with-ai/mcp-server/introduction)
* Fixed — Changelog email subscription links now resolve correctly.
* Fixed — Documentation GitHub links updated to point to the correct renamed repositories.

### &#x20;Dependencies & Tooling

* Improved — Echo Agent Kit GitHub references updated from `eka-care/echo` to `eka-care/echo-sdk` across installation and quickstart guides.
* Improved — ABHA tool descriptions added to the MCP supported tools reference, replacing the previous prescription management section with the new ABHA/ABDM tool flow documentation.

**April 5, 2026**

Week of March 31 – April 5

## New features

* **ABHA login and profile tools in MCP SDK** — The Eka MCP SDK now includes tools for ABHA login and profile management. Agents can initiate login via mobile, Aadhaar, ABHA number, or PHR address, verify OTP, select from multiple ABHA profiles, and retrieve the ABHA card — all within an agent conversation. [View docs](/docs/emr/build-with-ai/mcp-server/supported-tools)

## Updates

* **MCP Server documentation restructured** — The MCP Server docs have been reorganized into separate [Remote MCP](/docs/emr/build-with-ai/mcp-server/remote-mcp) and [Local MCP SDK](/docs/emr/build-with-ai/mcp-server/local-mcp) guides, with per-client setup instructions and a comparison table, making it easier to choose the right deployment model and get connected faster. [View docs](/docs/emr/build-with-ai/mcp-server/introduction)

* **`_meta` field support in doctor discovery and availability tools** — The Eka MCP SDK now forwards `_meta` context from tool calls to the `doctor_discovery` and `doctor_availability` tools. This lets MCP clients pass additional metadata (such as UI hints or session context) when searching for doctors or checking appointment availability. [View docs](/docs/emr/build-with-ai/mcp-server/supported-tools)

* **More ophthalmology tables in prescription PDFs** — Prescription PDFs now include pachymetry, Amsler grid, and contact lens examination tables, expanding the range of eye-care data printed alongside the rest of the prescription. [View docs](/docs/emr/prescription)

* **MedAssist iOS background session handling** — MedAssist chat sessions on iOS now gracefully handle app backgrounding. When you switch away and return, the session reconnects automatically so conversations are not lost mid-interaction.

## Bug fixes

* **MedAssist iOS error handling** — Fixed an issue where WebSocket errors during a MedAssist chat session could fail silently. Errors such as session timeouts and connection drops are now surfaced with clear messages, and the chat UI recovers gracefully.

**March 30, 2026**

Week of March 30

## New features

* **Ophthalmology tables in prescription PDFs** — Prescription PDFs now include ophthalmology examination tables, so eye-care data captured during a visit is printed alongside the rest of the prescription. [View docs](/docs/emr/prescription)

## Updates

* **Eka MCP Server on Smithery** — The Eka MCP Server is now listed on [Smithery](https://smithery.ai), making it easier for developers to discover, install, and connect the server to any MCP-compatible AI client. [View docs](/docs/emr/build-with-ai/mcp-server/introduction)

**March 29, 2026**

Week of March 29

## New features

* **IPD billing PDF generation** — Clinics can now generate inpatient department (IPD) billing documents as PDFs. The generated PDF includes patient details, admission information, an itemized bills and receipts table, and a pricing summary with discounts. [View docs](/docs/billing/payments)

## Updates

* **Medical Records Android SDK** — Record grid items now support conditional visibility for contextual actions, giving integrators more control over the options displayed on each medical record card.

**March 28, 2026**

Week of March 28

## New features

* **Patient benefits tool in MCP Server** — A new `get_patient_benefits` tool is available in the Eka MCP Server, letting agents retrieve available offers and benefits for a specific patient. [View docs](/docs/emr/build-with-ai/mcp-server/supported-tools)

## Updates

* **Email authentication in MCP Server** — Authentication elicitation now supports email as a verification method in addition to mobile number, giving users more flexibility during in-agent authentication flows. [View docs](/docs/emr/build-with-ai/mcp-server/authentication)

* **MedAssist iOS chat improvements** — The MedAssist chat experience on iOS now includes updated suggestion chips, improved message bubbles, and better file upload handling.

**March 27, 2026**

Week of March 27

## Updates

* **OPD slip improvements** — OPD slips now display price and patient (PT) attributes, giving clinic staff more complete information at a glance.

* **Pagify SDK** — Improved iframe cleanup logic so embedded views are properly removed when a job completes, whether or not a container ID is specified.

* **EkaScribe iOS SDK** — Updated session ID generation for improved reliability and removed an unused dependency.

## Bug fixes

* **MedAssist web widget** — Fixed an issue where OTP verification could fail silently or return incorrect error messages. The verification flow now properly handles edge cases including callback requests and missing patient records.

**March 26, 2026**

Week of March 20–26

## New features

* **Vaccination reminder webhooks** — Receive webhook events when vaccination reminders are triggered for patients. [View docs](/api-sdk/emr/post_webhooks/vaccination-reminder-webhook)

* **Appointment reminder webhooks** — New webhook endpoints for appointment reminders, follow-up reminders, and their instant variants. [View docs](/api-reference/doc-tool/post_webhooks/appointment-reminder-webhook)

* **Follow-up appointment confirmation API** — Confirm follow-up appointments programmatically using the new endpoint. [View docs](/api-sdk/emr/appointment-api/confirm-follow-up-appointment)

* **Appointment rescheduling via MCP Server** — You can now reschedule appointments through the Eka MCP Server.

* **ABDM milestone flows** — Structured milestone guides (M1–M4) for ABDM integration, covering ABHA creation, login, profile management, and health data exchange. [View docs](/docs/hie-cm/flows/m1)

## Updates

* **Doctor Profile API** — The Get Doctor Profile response now includes a `salutation` field. [View docs](/api-sdk/emr/doctor-and-clinic-api/get-doctor-profile)

* **Echo Agent Kit** — Added `_meta` field support per the MCP specification for passing tool call metadata. Elicitation support now includes status tracking, messaging, and handling of multiple tool elicitations. [View docs](/docs/agents/agent-kit/tools)

* **EkaScribe Android SDK v4.0.4** — Architecture V2 with Java sample app support, session cancellation, and improved state management with idempotent operations. [View docs](/api-sdk/scribe/sdks/android-sdk)

* **Authentication elicitation in MCP Server** — MCP Server tools now support authentication elicitation, allowing tools to prompt for credentials during execution. [View docs](/docs/emr/build-with-ai/mcp-server/authentication)

* **EkaScribe JS SDK** — Improved error tracking, header handling, and ES6 build support. [View docs](/api-sdk/scribe/sdks/ekascribe-ts-sdk)

## Bug fixes

* **EkaVoiceToRx** — Fixed an issue where transcription results could appear in the wrong order, and resolved a bug where the stop button was unresponsive during active sessions.

* **Medical Records (iOS)** — Fixed an issue where deleting a record could fail silently.


# Cookbook
Source: https://developer.eka.care/docs/get-started/cookbook

Worked examples that combine Eka products into one thing a clinic or a patient uses.

Each recipe builds one thing end to end and names the Eka products it uses. Start from the one closest to what you are building, then follow its links into each product's docs.

## Build a system

> **[ABDM-enabled HIS](/docs/get-started/whats-possible/abdm-enabled-his)**
>
> ABHA at registration, linked visits, records with consent, and claims. Uses ABDM Connect and NHCX.

> **[Medical records from any source](/docs/get-started/whats-possible/medical-records-from-any-source)**
>
> Consultations, photos and PDFs become one coded record. Uses Scribe, Document Parsing and Health Records.

> **[Clinically intelligent HIS](/docs/get-started/whats-possible/clinically-intelligent-his)**
>
> A scribe, a medical assistant and agents on your EMR. Uses Scribe, Agents and Medical Knowledge.

> **[Patient experiences](/docs/products/patient-experiences)**
>
> A clinic's booking site, a patient agent and the records patients keep. Uses Agents, Eka EMR, Billing and Health Records.

## Connect your agent

> **[Eka as MCP connectors](/docs/get-started/whats-possible/mcp-connectors)**
>
> Every Eka MCP server, and how to plug it into Claude, Cursor or your own agent.

## Build with the SDK

> **[Appointments management](/docs/get-started/whats-possible/appointment-management)**
>
> An appointments app on the TypeScript SDK's appointments module. Uses Eka EMR.

> **[Patients management](/docs/get-started/whats-possible/patient-management)**
>
> A patients app on the TypeScript SDK's patients module. Uses Eka EMR.

> **[Medication search](/docs/get-started/whats-possible/medicine-lookup)**
>
> A medication search app on the TypeScript SDK. Uses Medical Knowledge.

> **[Health quiz](/docs/get-started/whats-possible/health-assessment)**
>
> A health quiz app built with four function calls. Uses Document Parsing's assessments.


# Eka Products
Source: https://developer.eka.care/docs/get-started/eka-products

<font size="2"> Every Eka product you build with, the EMR data you connect to your tools, and Eka's open research. </font>

***

## Scribe

> **[EkaScribe](/docs/scribe/about)**
>
> Ambient clinical documentation using voice.

***

## Agents

> **[MedAssist](/docs/agents/medassist)**
>
> AI assistance for clinical decision support.

> **[MCP for Indian treatment protocol search](/docs/datasets/build-with-ai/mcp-server/introduction)**
>
> Infrastructure for Indian treatment protocol search workflows and agents.

> **[Model Context Protocol (MCP)](/docs/emr/build-with-ai/mcp-server/introduction)**
>
> Infrastructure for AI-native healthcare workflows and agents.

***

## Patient experiences

> **[Appointments](/docs/emr/appointments)**
>
> Scheduling and appointment lifecycle management.

> **[Payments](/docs/billing/payments)**
>
> Billing, invoices, and payment tracking.

***

## Clinical intelligence

> **[Assessments](/integrations/health-ai/assessments)**
>
> AI-powered clinical and health risk assessments.

> **[Medical DB](/docs/datasets/medical-db)**
>
> Standardized medical knowledge base.

> **[Medical Document Parsing](/docs/models/medical-document-parsing)**
>
> Extract structured data from clinical documents.

***

## ABDM

> **[ABDM](/docs/hie-cm/about)**
>
> India’s ABDM integrations for consent-based health data exchange.

***

## Integrations

Already run your clinic on Eka's EMR? Connect its doctors, clinics and daily activity to the tools your team uses.

> **[Patient](/docs/emr/patients)**
>
> Patient profiles, demographics, medical history, and longitudinal records.

> **[Doctor](/docs/emr/doctor)**
>
> Clinical workflows, charting tools, and physician productivity features.

> **[Clinic](/docs/emr/clinic)**
>
> Clinic setup, configuration, staff, and operations.

> **[Prescriptions](/docs/emr/prescription)**
>
> Medication orders and prescription workflows.

***

## Research & Open Source

> **[Spotlight](/docs/models/spotlight)**
>
> Open models, datasets, blogs, papers, and who is building on them.

> **[Open Source](/docs/get-started/open-source)**
>
> SDKs, agent kits, MCP servers, evaluation tools, and knowledge graphs.

> **[Blog](https://info.eka.care/services)**
>
> Launches, benchmark updates, and health-data insights.


# EkaScribe Release Notes
Source: https://developer.eka.care/docs/get-started/ekascribe

Feature releases, improvements, and fixes across EkaScribe — extension, web, mobile, and AI.

**March 2026**

### Simplified recording mode — removed consultation & dictation toggle

The mode selection between consultation and dictation has been removed from the recording flow. The interface is now cleaner and less ambiguous for doctors starting a session.

**Type:** Improvement  ·  **Surface:** Web

***

### Consistent structured output — LLM prompt improvements

The scribe template LLM was occasionally returning raw JSON instead of formatted markdown. Prompts have been tuned so the model consistently returns structured markdown output.

**Type:** AI / Model

***

### EkaScribe surfaced across 4 touchpoints in the Eka doctor tool

EkaScribe entry points are now present on the Rx/Rad screen, sidebar, queue view, and as an end-visit prompt — making it easier for doctors to discover and start a session without switching context.

**Type:** Feature  ·  Improvement

**February 2026**

### Multi-language transcription

Sessions can now be transcribed in multiple languages. Results are stored separately per language and served via individual URLs in the API response, powered by the Echo SDK.

**Type:** Feature  ·  **Surface:** Web

***

### Responsive template UI on mobile web

Template screens on ekascribe.ai are now fully responsive and usable on mobile browsers — previously the layout broke on smaller viewports.

**Type:** Improvement  ·  **Surface:** Web

***

### EMR template auto-applied for extension sessions

The `eka_emr_template` is now automatically included in every extension-flavour init request, ensuring consistent structured output without requiring manual configuration per session.

**Type:** Feature

***

### Post-session audio tips journey for doctors

An automated engagement journey now triggers after a doctor's 2nd EkaScribe session, sharing tips to improve recording audio quality. A companion help center article has also been published on [help.ekascribe.ai](https://help.ekascribe.ai).

**Type:** Improvement

***

### Extension — request timeout errors resolved

Request timeout errors that were intermittently appearing in the Chrome extension have been identified and fixed.

**Type:** Bug fix

***

### Android — patient details now correctly passed to session status screen

Patient ID and name were being dropped during navigation from the patient selection screen to the session status screen. Fixed — context is now correctly carried through the recording flow.

**Type:** Bug fix  ·  **Surface:** Mobile

**January 2026**

### Android V2 — redesigned app (v1.1.1)

Full screen-by-screen redesign of the Android EkaScribe app. Key improvements include an output template selection bottom sheet on the home screen, a live session-in-progress screen, redesigned analysing/retry/result/edit and template screens, patient search and add flow, and reusable bottom sheets for language, model, and mode selection.

**Type:** Feature  ·  Improvement  ·  **Surface:** Mobile

***

### Transcription shown immediately after session ends

Raw transcription text is now displayed as soon as recording ends, before the full AI structuring pass completes. Doctors get instant feedback on what was captured rather than waiting with a blank screen.

**Type:** Feature  ·  **Surface:** Web

***

### Single-chunk transcript API

New synchronous API endpoint to retrieve a transcript for a single audio chunk — no streaming required. Designed for integrations that need low-latency transcript retrieval on a per-chunk basis.

**Type:** Feature  ·  **Surface:** Web

***

### Smart redirect for authenticated users

Doctors who are already signed in and navigate to login.eka.care or accounts.eka.care are now automatically redirected to their destination, skipping the redundant login screen.

**Type:** Improvement  ·  **Surface:** Web

***

### Website 2.0 — structured output, inline editing & chatbot

Major overhaul of ekascribe.ai. Structured clinical note output (V2DD format) is now rendered in the UI with section-level editing, medicine codification with inline edits, a task-section panel for note refinement, and an integrated chatbot interface for post-session note adjustment. Create Template is also now available on mobile web.

**Type:** Feature  ·  Improvement  ·  AI / Model  ·  **Surface:** Web

**December 2025**

### Extension floating panel — rebuilt as inline page overlay

The Chrome extension has been moved off Chrome's side panel and now renders as a content-script overlay directly inside the active tab. Doctors can record, view results, and edit clinical notes without leaving their EMR page. The panel supports word-document-style editing, enforces a single instance across tabs (with a "take me there" prompt if already open), shows a confirmation when closing mid-recording, and is fully removed from the DOM on close.

**Type:** Feature  ·  Improvement

***

### Extension — paste overlay toggle in settings

Doctors using EkaScribe alongside third-party EMRs (HealthPlix, Tatwacare, etc.) can now enable or disable the Eka paste icon overlay from extension settings. The overlay is automatically suppressed on Eka's own EMR to prevent input field interference.

**Type:** Feature  ·  Improvement

***

### Extension onboarding flow for first-time users

New users landing on the extension for the first time now see a guided onboarding flow — previously the initial state was blank and confusing.

**Type:** Improvement

***

### Past sessions list capped at 25

The extension was crashing for high-volume doctors with a large session history. Past sessions are now limited to the 25 most recent, resolving the breakage.

**Type:** Improvement  ·  Bug fix

***

### Website — mobile-responsive layout

scribe.eka.care was not usable on mobile viewports. The UI has been fully refactored to be responsive across screen sizes.

**Type:** Improvement  ·  **Surface:** Web

***

### Extension UI revamp — updated branding & label clarity

First visual refresh of the Chrome extension. "Output language" relabelled to "Transcription language" for clarity. Updated EkaScribe logo, dynamic microphone permission handling, and graceful Cognito token expiry handling all shipped in this update.

**Type:** Improvement

***

### VAD microphone detection fixed

Voice Activity Detection (VAD) was incorrectly registering microphone state in some configurations, causing recording to not start or stop as expected. Fixed.

**Type:** Bug fix  ·  **Surface:** Web

***

### Platform discovery page — ekascribe.ai/download

A new unified page listing all EkaScribe platforms (extension, mobile app, web) so doctors can find and install the right version for their workflow in one place.

**Type:** Feature  ·  **Surface:** Web


# EkaScribe Changelog
Source: https://developer.eka.care/docs/get-started/ekascribe-changelog

Updates and improvements to EkaScribe — transcription and clinical documentation.

Get weekly developer updates in your inbox

New features, SDK releases, API changes, and bug fixes — delivered every week. No spam. Unsubscribe anytime.

Powered by Mailchimp · Your data is safe with us

**October 28, 2026**

AI tools changes

## Added

* **Medical Scribe: the `eka-scribe` plugin is published.** Install it in Claude Code to give your agent this product's reference skill. [Open Build with AI](/docs/scribe/build-with-ai).

**May 29, 2026**

May 29, 2026

## Added

* **\[EkaScribe] MedScribe Alliance TS SDK feature update** — The `@eka-care/medscribe-alliance-ts-sdk` ships a feature refresh (LIFE-1696) covering 13 files with new/updated session and recording surfaces. Pull the latest tag and review the diff for the full surface.

**May 27, 2026**

May 27, 2026

## Added

* **\[EkaScribe] startRecordingV2 in Eka JS SDK** — `@eka-care/eka-js-sdk` adds a `startRecordingV2` method that exposes the next-generation EkaScribe recording flow to JS consumers, alongside the existing `startRecording`. Use the V2 entry point for new integrations.

**May 25, 2026**

May 25, 2026

## Added

* **\[EkaScribe] Scribe UI widget in Eka JS SDK** — `@eka-care/eka-js-sdk` adds a packaged UI widget for the scribe recording flow, giving integrators a drop-in surface for capture, status, and transcript display instead of wiring those primitives by hand.

**May 20, 2026**

May 20, 2026

## Improved

* **\[EkaScribe] Eka Scribe Android → ekaNetworkAndroid 2.0.6** — `Eka-Scribe-Android` bumps the `ekaNetworkAndroid` version catalog entry from 2.0.5 to 2.0.6, picking up upstream support for custom OkHttp interceptors at network init.

**May 8, 2026**

May 8, 2026

## Added

* **\[EkaScribe] Pause and resume in MedScribe Alliance TS SDK** — The MedScribe Alliance TypeScript SDK now exposes `pause` and `resume` methods, letting integrators temporarily halt and continue an in-progress scribe recording without ending or restarting the session. Useful for handling interruptions mid-consultation.

**May 7, 2026**

May 7, 2026

## Added

* **\[EkaScribe] EkaScribe TS SDK getDocument, getSessionDetails, and existing-session resume** — `@eka-care/ekascribe-ts-sdk` v2.1.50 adds three new instance methods: `getDocument(document_id)` (fetch a document by id), `getSessionDetails({ session_id, presigned })` (fetch full session metadata, documents, and `user_status` lifecycle), and `startRecordingForExistingSession({ txn_id, business_id, created_at, microphoneID?, sharedWorkerUrl?, flavour? })` (resume recording for a previously initialised session by reconstructing the audio pipeline and session bucket path). New `TGetV1SessionDetailsResponse`, `TSessionDocument`, and related types are exported. [View docs](/api-sdk/scribe/sdks/ekascribe-ts-sdk)

* **\[EkaScribe] Document publish payload in EkaScribe TS SDK** — `postV1Document` and the `getV1Document` response now carry an optional `publish: Record<string, unknown>` payload, allowing integrators to send and read structured publish metadata alongside a session document.

* **\[EkaScribe] user\_status on patchTransactionStatus** — `patchTransactionStatus` now accepts an optional `user_status` field, mirroring the lifecycle states (`init`, `recording_started`, `commit`) returned by `getSessionDetails`, so clients can advance the user-side status on a session in one call.

## Improved

* **\[EkaScribe] Hardened VAD lifecycle in EkaScribe TS SDK** — `VadWebClient` now wraps `startVad`, `pauseVad`, `destroyVad`, `resetVadWebInstance`, `reinitializeVad`, and the silent-audio monitor in defensive try/catch blocks, and `monitorAudioCapture` now guards `micVad.pause()` with an existence check. Errors are logged via `[EkaScribe]` console output instead of bubbling up and breaking the host page. The `EkaScribe` facade applies the same protection around `reinitializeVad`, `destroyVad`, and `pauseVad`.

**May 6, 2026**

May 6, 2026

## Fixed

* **\[EkaScribe] Session polling now surfaces failures as ERROR** — `SessionManager` in the EkaScribe Android SDK now transitions to `ERROR` (instead of `COMPLETED`) when transcript or full-output polling fails or times out. Failed transcript polls also short-circuit subsequent full-output polling, and `handleTransactionError` is consistently invoked on failures so users can recover and start a new session. Test scenarios were updated to reflect the new contract. [View docs](/api-sdk/scribe/sdks/android-sdk)

**April 20, 2026**

April 20, 2026

## Improved

* **\[EkaScribe] Voice-to-text error handling on iOS DocAssist** — DocAssist for iOS now detects and surfaces voice-to-text failure scenarios with a clear error state instead of silently dropping the recording, making transient transcription errors recoverable for the user.

**April 17, 2026**

April 17, 2026

## Improved

* **\[EkaScribe] Android SDK MP3 encoding** — The EkaScribe Android SDK now uses MP3 encoding (via LAME) instead of AAC/MP4, producing raw MPEG Layer III bitstreams for more reliable audio chunk uploads. The AAC encoder and MP4 format option have been removed. [View docs](/api-sdk/scribe/sdks/android-sdk)

* **\[EkaScribe] Android SDK partial output polling** — Transaction result polling in the Android SDK now checks statuses across `integration`, `transcript`, and `custom` fields within `templateResults`, replacing the legacy `output` list. Empty statuses are treated as failures instead of timing out, improving error detection. [View docs](/api-sdk/scribe/sdks/android-sdk)

* **\[EkaScribe] iOS SDK parallel chunk processing** — The EkaScribe iOS SDK now processes audio chunks in parallel, improving transcription throughput and reducing end-to-end latency for longer recording sessions.

**April 16, 2026**

April 16, 2026

## Added

* **\[EkaScribe] Document management in JS SDK** — The EkaScribe JS SDK now exposes `createDocument`, `deleteDocument`, and `getChunkTranscript` methods, enabling programmatic document lifecycle management and per-chunk transcript retrieval directly from the SDK. [View docs](/api-sdk/scribe/sdks/ekascribe-ts-sdk)

## Improved

* **\[EkaScribe] Output polling parameters in JS SDK** — The `pollOutputSummary` method now accepts `document_id` and `dlp` query parameters, and the status API response type includes `document_id` and `document_path` fields. The status API timeout has been increased from 16s to 20s for improved reliability. [View docs](/api-sdk/scribe/sdks/ekascribe-ts-sdk)

**April 13, 2026**

Week of April 8–13

## Updates

* **EkaScribe documentation revamped** — The EkaScribe docs now include a Quick Start guide with a step-by-step TypeScript SDK integration walkthrough. Integration methods are reordered to recommend SDKs first, REST APIs second, and Chrome Extension third. SDK sidebar titles use proper casing, and deprecated APIs are nested under a warning section for clarity. [View docs](/docs/scribe/quickstart)

**April 11, 2026**

Week of April 8–11

## Updates

* **EkaScribe documentation revamped** — A new [Quick Start guide](/docs/scribe/quickstart) walks you through installing the SDK and transcribing your first consultation in minutes. SDKs are now promoted as the recommended integration path, and v1 APIs are marked deprecated with clear migration pointers to the [v2 APIs](/api-reference/health-ai/ekascribe/ekascribe-v2/overview). [View docs](/docs/scribe/overview)

**April 9, 2026**

Week of April 6–9

## Updates

* **EkaScribe documentation revamped** — The EkaScribe docs have been restructured with a new [Quick Start](/docs/scribe/quickstart) guide, reordered integration methods (SDKs recommended first, then REST APIs, then Chrome Extension), improved SDK sidebar titles, and deprecated APIs now nested under a warning group for clarity. [View docs](/docs/scribe/overview)

**April 8, 2026**

Week of April 6–8

## Updates

* **EkaScribe documentation revamp** — The EkaScribe docs have been reorganized with a new [Quick Start](/docs/scribe/quickstart) guide for the TypeScript SDK, SDKs promoted above REST APIs as the recommended integration path, corrected sidebar titles, and deprecated API endpoints clearly marked. [View docs](/docs/scribe/overview)

**March 27, 2026**

Week of March 27

## Updates

* **EkaScribe iOS SDK** — Updated session ID generation for improved reliability and removed an unused dependency.

**March 26, 2026**

Week of March 20–26

## Updates

* **EkaScribe Android SDK v4.0.4** — Architecture V2 with Java sample app support, session cancellation, and improved state management with idempotent operations. [View docs](/api-sdk/scribe/sdks/android-sdk)
* **EkaScribe JS SDK** — Improved error tracking, header handling, and ES6 build support. [View docs](/api-sdk/scribe/sdks/ekascribe-ts-sdk)

## Bug fixes

* **EkaVoiceToRx** — Fixed an issue where transcription results could appear in the wrong order, and resolved a bug where the stop button was unresponsive during active sessions.


# Glossary
Source: https://developer.eka.care/docs/get-started/glossary

The terms used across Eka's AI, Integrations, ABDM and Platform docs, what each one means, and the page where you meet it.

This page defines the terms you meet across Eka's developer docs, grouped by product family.

## AI

### EkaScribe

| Term | What it means | Where it is used |
| - | - | - |
| EkaScribe | Eka's AI medical scribe. You record or stream a consultation or dictation and get back a transcript and structured clinical notes in the format you define. | [EkaScribe overview](/docs/scribe/overview) |
| EkaScribe session | One unit of work in EkaScribe, identified by a `session_id`. It ties audio capture, processing and results together: you create it, send audio, end it, then read the notes. | [Sessions overview](/api-sdk/scribe/sessions/overview) |
| Template | A note format you describe in plain markdown, such as a SOAP note or a discharge summary. You name templates when you create a session, and EkaScribe returns one structured note per template. | [Create template](/api-sdk/scribe/templates/create-template) |
| `pro` and `lite` | The two EkaScribe models. `pro` adds speaker diarization, custom templates and 60-minute sessions; `lite` is fast and built for dictation. | [EkaScribe overview](/docs/scribe/overview) |

### Agents and Models

| Term | What it means | Where it is used |
| - | - | - |
| MedAssist | Eka's agentic medical assistant. Your users talk to Eka's medical LLM in real time over a session you create with your API key and then join over WebSocket. | [MedAssist](/docs/agents/medassist) |
| Medical Document Parsing | The Eka API that extracts structured data from clinical documents. | [Medical Document Parsing](/docs/models/medical-document-parsing) |

## Integrations

### EMR

| Term | What it means | Where it is used |
| - | - | - |
| Doctor Tool | Eka's set of APIs for clinical workflows: appointment management, digital prescriptions and access to patient records, including records linked through ABDM. | [Before you begin](/api-sdk/emr/instructions/before-you-begin) |
| EMR | The Integrations product for patients, appointments and prescriptions. | [API Reference](/api-sdk/index#integrations) |

### IPD, Billing and Health Records

| Term | What it means | Where it is used |
| - | - | - |
| IPD | Inpatient department. The IPD APIs cover admission, beds, nursing and discharge for patients admitted to a facility. | [IPD setup data](/api-sdk/ipd/configuration/setup/get-ipd-setup-data) |
| Billing | The Integrations product for charges, deposits, invoices and payments. | [Payments](/docs/billing/payments) |
| Health Records | Records, cases and vitals held on the patient's side. | [Create overview](/api-sdk/health-records/create-overview) |

## ABDM

### HIE-CM: ecosystem and roles

| Term | What it means | Where it is used |
| - | - | - |
| ABDM | Ayushman Bharat Digital Mission, India's national digital health infrastructure. Patients, hospitals, labs, insurers and health apps exchange health data through it, with the patient's consent driving every exchange. | [ABDM overview](/docs/hie-cm/about) |
| ABDM Connect | Eka's REST API over the ABDM gateway. You call Eka, and Eka handles ABDM's gateway protocol, encryption and callbacks for you. | [ABDM Connect overview](/api-sdk/hie-cm/overview) |
| CARE | How these docs name the four ABDM milestones: Create (M1, the patient's ABHA), Attach (M2, records to the ABHA), Retrieve (M3, records with consent), Enrol (M4, doctors and facilities in HPR and HFR). | [What is ABDM Connect](/docs/hie-cm/about#care-the-four-milestones) |
| HIE-CM | The ABDM family that covers ABHA, care contexts, consent and records. Its specification also sets the ECDH scheme used to encrypt records in transit. | [Encryption](/docs/hie-cm/care-contexts/ecdh-encryption) |
| Consent Manager | The ABDM registry that manages consent between the parties that hold data and the parties that want it. The ABDM gateway itself acts as the Consent Manager. | [ABDM overview](/docs/hie-cm/about#core-registries) |
| HIP | Health Information Provider. A hospital, lab, clinic or pharmacy that holds patient records and links them to the patient's ABHA address so they can be found and shared. | [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip) |
| HIU | Health Information User. Any party, such as an insurer or referral system, that requests a patient's records with consent and receives them from the HIPs. | [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent) |
| PHR app | A personal health record app, the patient-facing side of ABDM. It usually acts as both a HIP for records the patient uploads and a HIU for records it fetches. | [Gather every health record in a PHR app](/docs/hie-cm/journeys/phr-patient-aggregates-records) |
| Milestone | One of the four stages, M1 to M4, in which ABDM certifies hospital and lab software. They cover identity, linking, consent and registries. | [ABDM overview](/docs/hie-cm/about#abdm-milestones) |
| HPR | Healthcare Professionals Registry. Each doctor, nurse or practitioner on it gets a unique HPR ID as a verified digital identity. | [Create an HPR ID with Aadhaar OTP](/docs/hie-cm/workflows/create-hpr-id) |
| HFR | Health Facility Registry. Each government or private facility on it gets a unique HFR ID, used for record linking and patient discovery. | [Register and onboard a facility](/docs/hie-cm/workflows/register-hfr) |

### HIE-CM: patient identity

| Term | What it means | Where it is used |
| - | - | - |
| ABHA | Ayushman Bharat Health Account, the patient's health identity. Every health transaction in ABDM is anchored to it. It takes the form of an ABHA number or an ABHA address. | [ABDM overview](/docs/hie-cm/about#core-registries) |
| ABHA number | The 14-digit, KYC-verified form of an ABHA. You create one from an Aadhaar OTP, with Aadhaar as the KYC. | [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp) |
| ABHA address | The patient's ABHA handle, such as `shyam@abdm`. A HIP links records to it. You can create one without KYC from a mobile OTP. | [Create an ABHA address with mobile OTP](/docs/hie-cm/workflows/create-abha-mobile-otp) |
| ABHA Gateway session | The patient's session with the ABHA Gateway, separate from your client token. Creating or registering an ABHA opens it, and patient-scoped calls without a live session return HTTP `491`. | [Hold the ABHA Gateway session](/docs/hie-cm/workflows/hold-gateway-session) |
| Scan & Share | The patient scans your facility's QR code with a PHR app to share their ABHA profile. Eka sends you the profile on a webhook, and you reply with an OPD token. | [Receive a scanned profile as a HIP](/docs/hie-cm/workflows/hip-scan-and-share) |

### HIE-CM: records and consent

| Term | What it means | Where it is used |
| - | - | - |
| Care context | A visit, test or admission at your facility, linked to the patient's ABHA address. Once linked, it is registered with ABDM, and any HIU the patient consents to can request it. | [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip) |
| Linking | Registering a care context under the patient's ABHA. You link new records yourself; the patient links older records through discovery. Linking returns `202 Accepted` and confirms on the `abha.link_care_context` webhook. | [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip) |
| Discovery | A patient searches your facility from a PHR app for records that were never linked to their ABHA. You answer three webhooks: return the matches, send an OTP, then confirm the link. | [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link) |
| FHIR bundle | The record format a HIP sends for a care context. If Eka stores your data, you send it base64-encoded in the `data` field when you link. Otherwise you build and encrypt it on each fetch request. | [Serve records on a fetch request](/docs/hie-cm/workflows/serve-data-on-fetch) |
| HI type | Health information type, the kind of record in a care context, for example `OPConsultation` or `Prescription`. You send it as `hi_type` when you link, and a fetch request lists the `hi_types` the HIU wants. | [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip) |
| Consent request | A HIU's request for a patient's records. It appears in the patient's PHR app, where they approve or deny it, and its status changes arrive on the `abha.consent_update` webhook. | [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent) |
| Consent artefact | The record ABDM generates when a patient approves a consent request, one per HIP. An expired artefact returns `ABDM-1061`, and you raise a new consent. | [Approve, deny or revoke a consent in a PHR app](/docs/hie-cm/workflows/phr-act-on-consent) |
| Consent PIN | The PIN a patient sets in a PHR app and verifies when they approve, deny or revoke a consent. | [Approve, deny or revoke a consent in a PHR app](/docs/hie-cm/workflows/phr-act-on-consent) |
| Auto-approval | A policy that lets the patient authorise a class of consent requests once, instead of approving each one. | [Set up the patient's health locker](/docs/hie-cm/workflows/set-up-health-locker) |
| Health locker | Storage the patient controls for their own records. When auto-approval is on, your PHR app is the locker, and Eka tells it each time a HIP links a new record. | [Set up the patient's health locker](/docs/hie-cm/workflows/set-up-health-locker) |
| Subscription | The standing arrangement Eka sets up with auto-approval. It sends `abha.subscription_notify` when a provider links a new record for the patient, and `abha.subscription_modified` when it changes. | [Set up the patient's health locker](/docs/hie-cm/workflows/set-up-health-locker) |
| ECDH | The encryption scheme for records sent between HIPs and HIUs: ECDH key agreement on Curve25519, with HKDF-SHA256 and AES-256-GCM. If Eka stores your records, Eka encrypts and decrypts them for you. | [Encryption](/docs/hie-cm/care-contexts/ecdh-encryption) |

### HIE-CM: identifiers and fields

| Term | What it means | Where it is used |
| - | - | - |
| OID (Eka user ID) | Eka's ID for a patient, returned as `eka.oid` when an ABHA is created or the patient logs in. You send it in the `X-Pt-Id` header or the `oid` query parameter on later calls. | [ABDM Connect overview](/api-sdk/hie-cm/overview#common-headers) |
| Partner patient ID | Your own ID for the patient, sent in the `X-Partner-Pt-Id` header. | [ABDM Connect overview](/api-sdk/hie-cm/overview#common-headers) |
| HIP ID | The ID of the facility a call is made from, sent in the `X-Hip-Id` header. On NHCX calls it selects the facility that raises the claim. | [ABDM Connect overview](/api-sdk/hie-cm/overview#common-headers) |
| `txn_id` | The transaction ID that the first call of an OTP or linking flow returns. You send it back on every later step of that flow. | [ABDM Connect overview](/api-sdk/hie-cm/overview#multi-step-flows) |
| `skip_state` | A field in the Aadhaar OTP verify response that tells you the next call. Its values are `confirm_mobile_otp`, `abha_create` and `abha_select`. | [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp) |
| `source_error` | The part of an ABDM Connect error body that carries ABDM's own code when the gateway refuses a call, such as `ABDM-1010`. | [Errors](/docs/hie-cm/errors) |

### NHCX

| Term | What it means | Where it is used |
| - | - | - |
| NHCX | National Health Claims Exchange. It carries cashless insurance claims, including PMJAY, between your hospital and the payer. ABDM Connect builds, signs and encrypts the FHIR bundles for you. | [NHCX overview](/docs/nhcx/getting-started) |
| Claim | The NHCX case that every call after setup hangs off. You create one per hospitalisation and keep its `claim_id` against your admission. | [NHCX overview](/docs/nhcx/getting-started) |
| Pre-auth | The NHCX request for approval you submit with the treating doctor, diagnosis, documents and answers. The payer rejects a pre-auth above the policy's wallet balance. | [NHCX overview](/docs/nhcx/getting-started) |

### UHI

| Term | What it means | Where it is used |
| - | - | - |
| UHI | Unified Health Interface. You use it to search blood banks and to book in-person doctor visits for your users. | [Search blood banks over UHI](/docs/uhi/workflows/blood-bank-search) |

## Platform

### Auth

| Term | What it means | Where it is used |
| - | - | - |
| Client credentials | The `client_id` and `client_secret` you create in the Eka Developer Console. You exchange them for an access token, and you keep them secret at all times. | [Authorization](/api-sdk/auth/getting-started) |
| Access token | The token you get from Connect Login and send on every API request. A `401 Unauthorized` means it has expired. | [Connect Login](/api-sdk/auth/client-login) |
| Refresh token | The token Connect Login returns with the access token. You use it to get a new access token after a `401`. | [Connect Refresh](/api-sdk/auth/refresh-token-v2) |
| Long-lived access token | An access token for server-to-server calls between trusted systems. You use it when you do not want to manage token refresh. | [Authorization](/api-sdk/auth/getting-started#long-lived-access-token) |

### Webhooks

| Term | What it means | Where it is used |
| - | - | - |
| Webhook | An HTTP callback Eka sends to your endpoint when something happens, so you do not poll. The payload carries the resource ID and the action, and you call the API for full details. | [Webhooks](/api-sdk/webhooks/getting-started) |
| Webhook signature | The `Eka-Webhook-Signature` header Eka adds when you give a signing key at registration. You verify it to confirm the event came from Eka unchanged. | [Webhook signature](/docs/webhooks/webhook-signature) |


# Open Source
Source: https://developer.eka.care/docs/get-started/open-source

<font size="2"> Eka's open source projects, SDKs, models, datasets, and publications. </font>

## Healthcare Agents & Agentic Kit

> **Echo SDK**
>
> Open-source, LLM-agnostic Python framework for building healthcare AI agents.
>
> [GitHub](https://github.com/eka-care/echo-sdk) · [Dev Portal](/docs/agents/agent-kit/introduction)

> **Synapse**
>
> Open-source agent SDK from Eka Care.
>
> [GitHub](https://github.com/eka-care/synapse-sdk) · [Dev Portal](#)

***

## MCPs & Tools

> **Eka Clinical Guidelines**
>
> Eka offers a hosted MCP tool to search 180+ published Indian and international treatment protocols and clinical guidelines from bodies like ICMR, WHO, and ADA.
>
> [Dev Portal](/docs/datasets/build-with-ai/mcp-server/introduction)

> **Eka EMR SDK**
>
> Eka offers a hosted and self-hostable MCP server that exposes the Eka EMR — patients, appointments, prescriptions, and doctor/clinic data — to AI assistants.
>
> [Dev Portal](/docs/emr/build-with-ai/mcp-server/introduction)

> **BODHI**
>
> Eka provides the BODHI clinical ontology — SNOMED-linked knowledge graphs mapping conditions to symptoms and concepts to drugs and lab investigations.
>
> [Learn more](https://info.eka.care/services/bodhi-bharat-ontology-for-disease-healthcare-informatics)

***

## Models

> **Parrotlet (Series A & V)**
>
> Eka's family of purpose-built medical models — vision (Parrotlet-V), ASR (Parrotlet-A), and embeddings (Parrotlet-E).
>
> [Dev Portal](/docs/models/models)

***

## Evaluation

> **Medical Model Evaluation (Karma)**
>
> OpenMedEvalKit — an open-source framework for benchmarking and evaluating medical AI models.
>
> [Learn more](https://info.eka.care/services/introducing-karma-openmedevalkit-an-open-source-framework-for-medical-ai-evaluation)

***

## Medical Scribe

> **MedScribe Alliance SDK**
>
> TypeScript SDK implementing the open MedScribe Alliance Protocol for ambient medical scribing.
>
> [Dev Portal](/api-sdk/scribe/sdks/ts-sdk)

> **Eka Scribe SDK**
>
> Eka offers ready-to-use SDKs (Android, iOS, Java, Python, TypeScript) that turn doctor–patient speech into structured medical notes, handling voice capture, chunking, and upload.
>
> [Dev Portal](/docs/scribe/overview)

***

## Datasets

> **Datasets**
>
> Open medical datasets for benchmarking speech-to-text, document parsing, and multilingual medical retrieval.
>
> [Dev Portal](/docs/models/datasets)

***

## Spotlight

> **Spotlight**
>
> Open models, datasets, blogs and papers from Eka MedAI — and the teams building on them.
>
> [Spotlight](/docs/models/spotlight) · [Blog](https://info.eka.care/services)

***


# Build with Eka
Source: https://developer.eka.care/docs/get-started/overview

Get your keys, authenticate once, then pick the solution that fits what you are building.

Every Eka product uses the same keys and the same access token. Get them once, then build with any product: the scribe, records, agents, models or ABDM.

## Get your API keys

**1. Create a client in the console**

Sign in to the [Eka Care console](https://console.eka.care) and create a client. You get two values.

> **[Client ID](/api-sdk/auth/client-login)**
>
> Identifies your application to Eka's APIs.

> **[Client Secret](/api-sdk/auth/client-login)**
>
> A confidential key, like a password, used with the client ID.

**2. Building for doctors or patients?**

Integrate Eka accounts with OpenID Connect (OIDC), or ask the healthcare provider for an API key from their [workspace](https://hub.eka.care/account/account/apitoken/).

**3. Set up your client**

Send every request to `https://api.eka.care`. Any HTTP client works: Postman, cURL or the library for your language.

> [!NOTE]
>
> For keys or help, write to [ekaconnect@eka.care](mailto:ekaconnect@eka.care).

## Authenticate

**1. Get an access token**

Call [client login](/api-sdk/auth/client-login) with your client ID and client secret. You get an access token and a refresh token.

**2. Send it with every request**

Put the access token in the `Authorization` header of each API call.

**3. Refresh it when it expires**

The access token lasts about 30 minutes. A `401 Unauthorized` means it has expired: call [refresh token](/api-sdk/auth/refresh-token-v2) for a new one.

For server-to-server work that should not refresh every half hour, use a [long-lived token](/api-sdk/auth/getting-started#long-lived-access-token).

## Pick a product

> **[Scribe](/docs/scribe/overview)**
>
> Turn a consultation into a structured note in your template.

> **[Agents](/docs/products/agents)**
>
> Build an agent for your purpose and give it Eka's medical tools.

> **[Patient experiences](/docs/products/patient-experiences)**
>
> Booking sites, patient agents and the records the patient keeps.

> **[Clinical intelligence](/docs/products/clinical-intelligence)**
>
> Read reports, code clinical terms and ground your AI in medical data.

> **[ABDM](/docs/products/abdm)**
>
> ABHA, linked records, consent, claims and the UHI network.

## Connect your tools

Already run your clinic on Eka's EMR? Connect it to the CRM or dashboard your team uses: appointments and visits from the [EMR](/docs/emr/patients), admissions from [IPD](/api-sdk/ipd/configuration/setup/get-ipd-setup-data), and invoices and payments from [Billing](/docs/billing/payments).

Not sure where your product fits? [Eka products](/docs/get-started/eka-products) lists every product, and the [glossary](/docs/get-started/glossary) explains the terms the docs use.


# Under the Hood
Source: https://developer.eka.care/docs/get-started/under-the-hood

Monthly transparency post covering infrastructure, reliability, performance, and security work across the Eka platform.

Get weekly developer updates in your inbox

New features, SDK releases, API changes, and bug fixes — delivered every week. No spam. Unsubscribe anytime.

Powered by Mailchimp · Your data is safe with us

**May 2026**

Monthly update — May 2026

## What shipped in May 2026

May was a wide-front month: the EkaScribe SDK surface kept maturing across web and mobile, EkaAgents broadened from doctor-booking into service and appointment workflows, EMR's records experience on Android gained the time and state-recovery primitives it had been missing, and Platform shipped a quiet but meaningful run of design-system, network, and ABDM improvements.

**Reliability & Uptime** — The biggest reliability work landed in the EMR records pipeline on Android. Health Records Android now keeps its own `TimeProvider` that tracks a server-time offset persisted in `SharedPreferences`, updated whenever a sync response comes back with a `Date` header. Anywhere the SDK previously called `System.currentTimeMillis()` for record and file timestamps, it now uses the synchronized clock — so `createdAt`, `updatedAt`, and `lastUsed` stay in sync across devices with skewed clocks. Alongside that, a stale-analysing-record reset clears the `is_analysing` flag for documents stuck in analysis past a cutoff, triggered automatically when records are read — so a crashed or interrupted parse no longer leaves a document permanently in the analysing state. On EkaScribe Android, session polling that previously slid into `COMPLETED` on failure now correctly transitions to `ERROR` and short-circuits the rest of the poll chain.

**Performance** — Android record-preview hot paths moved off the UI thread: image URI resolution, large-image validation, and orientation handling now run on `Dispatchers.IO` via `LaunchedEffect`, and the preview list passes `File` objects directly to `AsyncImage` instead of manually decoding bitmaps. File downloads switched to `MediaStore` on Android Q+ for scoped-storage compliance, with stream-based copy to public Downloads and a dedicated `records_temp` cache sub-directory with stricter cleanup on failure. On the JS side, the new scribe UI widget cut the integration surface significantly — what used to require wiring capture, status, and transcript primitives is now one drop-in component.

**Security & Compliance** — The MCP server's OAuth discovery flow was hardened to derive its origin from RFC 7239 `forwarded` headers before falling back to `x-forwarded-proto`, so `https://` URLs are advertised correctly when fronted by AWS API Gateway. `/.well-known/oauth-protected-resource` also now matches subpaths (e.g. `/mcp`), fixing 404s for clients that probe with the resource path appended. On the ABDM front, `abdm-ecdh` picked up a Java implementation of the ECDH primitives alongside the existing Python and Go bindings, with a CI pipeline added and the Python release path corrected — making it materially easier for JVM-based HIP/HIU integrations to handle ABDM consent and data exchange.

**Scalability** — EkaNetwork Android's `init` now accepts a list of custom OkHttp interceptors, stored per `appId` and threaded into both the `AuthApi` and dynamically-created services. Eka Scribe Android, Health Records Android, and `android-document-ui` all picked up the new network version, so hosts can plug in logging, tracing, or header interceptors without forking the network layer. The Aakaar design system's `tokens.ts` was decoupled from antd, so consumers of `@eka/aakaar/tokens` and the Aakaar MCP server no longer transitively pull antd into their bundles.

**Developer Infrastructure & Tooling** — The Aakaar MCP server got a component-metadata path-resolution fix, and the `EditableTable` bottom AutoSuggest dropdown now anchors to the nearest scrollable ancestor via a configurable `getPopupContainer` — eliminating stale dropdown positions after row inserts and the stuck-scroll state after mass-clearing rows. The `EkaScribe` TS SDK wrapped `VadWebClient`'s lifecycle methods in defensive try/catch with namespaced `[EkaScribe]` logging, so errors in the VAD path no longer escape to the host page.

**EkaScribe** — The product surface continued to mature on every runtime. The Eka JS SDK shipped a packaged scribe recording widget and a `startRecordingV2` entry point that exposes the next-generation recording flow alongside the existing `startRecording`. The MedScribe Alliance TypeScript SDK added pause and resume controls for in-progress recordings, plus a feature update tracking the LIFE-1696 work item that refreshed session and recording surfaces across thirteen files. The EkaScribe TS SDK at v2.1.50 picked up `getDocument`, `getSessionDetails`, and `startRecordingForExistingSession`, alongside an optional `publish` payload on the document API and `user_status` on `patchTransactionStatus` — closing out the full document and session lifecycle.

**EMR** — Templar receipts now print GST and use a `pt` attribute that carries a date. The OPD slip template was rewritten from string templates to JSX, aligning it with the rest of the engine. A new `examinationFindings` property group landed with backward-compatible support for legacy notes, and a long-running text-wrapping rendering bug was fixed. The patient age field on Templar receipts moved from a numeric `ageInM` to a richer `age` string — a breaking change for `TPdfObject` callers, but one that produces a more clinically meaningful age label. On Android, the records grid item's analysing state was consolidated into the `SmartTag` component, and the AddRecord preview activity got the stability, performance, and scoped-storage work described above.

**EkaAgents** — The Eka MCP SDK widened its tool surface meaningfully. New tools — `service_availability_elicitation`, `book_service`, `show_appointments_basic`, `get_patient_appointments_basic`, and a CRM lead-creation tool — extend agents from doctor-booking into service/health-package booking, appointment lookups, and lead capture. The `doctor_availability_elicitation` flow now returns `selected_doctor_id` and `selected_hospital_id` in `_meta.tool_result`, the doctor-availability success response was enriched, and the user's selected hospital is now ranked first in availability listings. The Echo Agent Kit added AG-UI streaming, Anthropic Claude prompt support, and a skills concept for building modular, reusable agent capabilities.

**April 2026**

Monthly Transparency Post

## Under the Hood — April 2026

April was about turning the AI agent infrastructure we've been investing in
into something production-grade — faster, more bounded, and easier to
authenticate against — while continuing to harden the EMR, EkaScribe, and
ABDM surfaces around it. We also opened up two pieces of internal IP to the
wider community.

### AI agent infrastructure

The Echo Agent Kit's MCP integration got the most substantial rework of the
month. The old monolithic MCP cache was retired in favor of a split design:
tool discovery and MCP sessions now live in separate caches, each with its
own idle and absolute TTLs, LRU eviction on pool exhaustion, and concurrent
cache-miss serialization to prevent duplicate discovery work. Tool cache keys
are partitioned by configurable headers, and `user_session_id` is now plumbed
through `MCPTool.run` via `tool_context` — so per-user sessions stay
correctly isolated even under load.

We also put bounds on tool execution: MCP tool calls in the Echo Agent Kit
are now capped at a 10-second timeout, so a slow downstream tool can no
longer block an agent response indefinitely. Empty prompt variables are
handled gracefully too — optional placeholders no longer throw.

On the MCP Server itself, we shipped OTP-based authentication for EMR
workspaces (with country code selection and UHID profile picking, all
mid-conversation), added a doctor discovery tool for EMR clinics, introduced
an interactive elicitation flow that lets agents confirm doctor availability
before booking, and made the MCP SDK fall back to the default EMR tool set
when a workspace has no explicit configuration — a meaningful resilience
improvement for new workspace onboarding. Profile creation in the MCP SDK
now requires a mobile number, ensuring downstream integrations always have
a contactable identifier.

The MedAssist surface saw steady iteration too — a contextual popup tied to
conversation state, configurable onboarding nudges so partners can suppress
unsolicited prompts, a proper agent-ID resolution fix, file-upload
validation against an allow-list of supported types, and a responsive layout
pass that fixes overflow on screens under 360px and 767px wide. A
microphone regression was caught and reverted same-day.

### Reliability and SDK hardening

EkaScribe's SDKs leveled up across all three runtimes. The Android SDK
switched from AAC/MP4 to LAME-based MP3 encoding for more reliable chunk
uploads, and its result polling now inspects `integration`, `transcript`,
and `custom` statuses inside `templateResults` instead of the legacy
`output` list — with empty statuses correctly treated as failures rather
than timing out. The iOS SDK now processes audio chunks in parallel,
cutting end-to-end transcription latency for longer recordings. The
JavaScript SDK gained `createDocument`, `deleteDocument`, and
`getChunkTranscript` for full programmatic document lifecycle control,
plus expanded polling parameters and a longer 20-second status API
timeout. EkaScribe iOS DocAssist also now surfaces voice-to-text failures
with a clear error state instead of silently dropping recordings.

On the Android side, the document UI no longer crashes when PDF rendering
initializes before view layout constraints are available — view setup is
now properly gated. Medical Records Android validates oversized images
before upload, moves PDF URI resolution off the main thread, and the
Health Records SDK handles missing files during record processing
gracefully with improved MD5 checksum error handling.

The Patient Directory TypeScript SDK got a `forceApiSearch` flag for
high-confidence lookups that need to bypass the local cache, and we
fixed a stale-cache edge case where partial cached state could surface
incorrect results.

### Platform and integrations

We extended the Patient Directory APIs with two new endpoints — retrieve
a patient profile by username and update an EMR user profile — plus a
GET endpoint to retrieve an EMR user by OID. The `extras` field also got
documented restrictions (no nested lists, dictionaries with one level of
nesting, 16-character key limit, leading-underscore keys ignored) so
integrators can rely on consistent shape contracts. The eka-usage-sdk
shipped at v0.1.1 with a fixed test runner and the latest Kafka usage
metric event definitions, and the ABDM-related usage events were updated
to match current consent and linking flows.

The Templar prescription engine saw a steady drumbeat of EMR-facing
improvements: clinic name on OPD slips; cleaner doctor name rendering on
IPD receipts and bills (using profile first/last name fields directly);
a `show_signature` flag plus cache-busting query parameters for S3-hosted
PDF assets; corrected ophthalmology table ordering; richer IPD admission
templates; an IPD admission TinyMCE preview fix; QR code repositioned
into the footer details for cleaner headers; a `unit_display_name`
fallback to `name` for cleaner unit labels; the addition of pachymetry,
Amsler grid, and contact lens examination tables; structured diet chart
sections in prescriptions; and a Total Paid / Amount Due summary on IPD
billing PDFs. OPD slips also got tags and a larger token font for
readability at the front desk.

### Open-sourcing internal IP

Two pieces of work landed in the open-source column. **BODHI** — two
SNOMED-linked clinical knowledge graphs (`bodhi-s` for condition–symptom
mapping and `bodhi-m` for concept–drug–lab investigation mapping, with
9,300+ nodes and 16,700+ relationships across six interchange formats)
— is now publicly available under CC BY-NC 4.0 for symptom checking,
differential diagnosis, and patient health profiling use cases. And the
**ABDM ECDH** key-exchange primitives we use internally for secure
consent and data-fetch flows are now distributable as a Python package,
so partners can integrate ABDM-aligned encryption helpers without
re-implementing the protocol.

### Developer experience

The EkaScribe documentation got a substantial revamp: a new Quick Start
guide walks integrators through installing the TypeScript SDK and
transcribing a first consultation in minutes; SDKs are now promoted as
the recommended integration path with REST APIs second and Chrome
Extension third; v1 APIs are clearly marked deprecated with migration
pointers to v2; and SDK sidebar titles use proper casing. The result is
a faster, less ambiguous path from "first time visiting the docs" to a
working transcription.

### What's next

In May, we're focused on continuing to extend the Echo Agent Kit
(audio transcription, lazy-loaded skills, and Postgres-backed tools have
already started landing in early May), expanding doctor and patient
directory APIs further, and tightening the production posture of the
MCP Server's caching and authentication paths.

**March 2026**

Monthly Transparency Post

## Under the Hood — March 2026

March was about making AI agents more capable and more connected. We expanded
what agents can do — from booking appointments to managing ABHA profiles —
while investing in the developer experience to make sure integrators can
connect, authenticate, and build quickly.

### Product highlights

* **ABHA login and profile management via MCP** — AI agents can now handle
  full ABHA workflows (login, OTP verification, profile selection, card
  retrieval) during a conversation, no manual steps needed. [View changelog](/docs/get-started/changelog)
* **Vaccination and appointment reminder webhooks** — New webhook endpoints
  for vaccination reminders, appointment reminders, and follow-up variants
  let integrations react to scheduling events in real time.
* **Follow-up appointment confirmation API** — A new endpoint to
  programmatically confirm follow-up appointments, removing the need for
  manual intervention.
* **Ophthalmology data in prescription PDFs** — Prescription PDFs now include
  pachymetry, Amsler grid, and contact lens examination tables, rounding out
  ophthalmology support across the platform.
* **IPD billing PDF generation** — Clinics can now generate inpatient billing
  documents as structured PDFs with itemized charges and pricing summaries.

### AI agent infrastructure

March saw sustained investment in the Eka MCP Server — the core interface
between AI assistants and the Eka healthcare platform.

We added five new tools this month: appointment rescheduling, patient benefits
lookup, ABHA login and profile management, and doctor discovery with metadata
forwarding. Each tool follows the authenticated remote MCP specification, so
any compatible AI client can use them without custom integration work.

Authentication got more flexible too. The MCP Server now supports email-based
verification alongside mobile, and tools can prompt for credentials
mid-conversation through elicitation — meaning the user never has to leave
their AI client to authenticate.

On the developer experience side, we restructured the MCP documentation into
separate Remote and Local SDK guides, published the server on Smithery for
easier discovery, and added comparison tables so developers can choose the
right deployment model in seconds.

### SDK and integration tooling

The EkaScribe Android SDK shipped Architecture V2 (v4.0.4) with Java support,
session cancellation, and idempotent state management — a significant
reliability improvement for integrators running the SDK in production. The JS
SDK received error tracking improvements, header handling fixes, and ES6 build
support.

The Echo Agent Kit gained `_meta` field support and improved elicitation
handling, aligning it with the latest MCP specification. The Pagify SDK cleaned
up iframe lifecycle management to prevent lingering embedded views.

On the mobile side, MedAssist on iOS now handles app backgrounding gracefully
— sessions reconnect automatically — and error messages are surfaced clearly
instead of failing silently. Suggestion chips, message bubbles, and file upload
handling were all refined.

### Documentation and developer experience

We published structured ABDM milestone guides (M1–M4) covering the full
integration path from ABHA creation through health data exchange. The Doctor
Profile API was extended with a salutation field. OPD slips now display price
and patient attributes.

The EkaScribe documentation received a significant revamp in early April: a new Quick Start guide gets developers from zero to first transcription in minutes using the TypeScript SDK, the docs now lead with SDKs as the recommended integration path, and deprecated API endpoints are clearly marked. Two new Patient Directory endpoints — retrieve by username and update EMR user profiles — expanded programmatic control over patient records.

The Medical Records Android SDK gained conditional visibility for record grid
items, and the changelog itself was cleaned up (Gmail subscription links and
GitHub repository links corrected).

### What's next

In April, we're focused on expanding MCP tool coverage across the EMR,
improving real-time event delivery for webhook consumers, and continuing to
harden the authentication and session management layers across all SDKs.


# Weekly Updates
Source: https://developer.eka.care/docs/get-started/weeklyupdates

Weekly summary of user-facing changes across the Eka platform.

Get weekly developer updates in your inbox

New features, SDK releases, API changes, and bug fixes — delivered every week. No spam. Unsubscribe anytime.

Powered by Mailchimp · Your data is safe with us

**Week of June 1, 2026**

Week of June 1 – June 7

### &#x20;EMR

#### New features

* **Reschedule keeps the appointment history together** — When you reschedule an appointment, the old and new appointments are now linked both ways. Receipts and services already attached to the original visit move over to the new one automatically, and you can see the full reschedule chain instead of two unrelated bookings.

#### Bug fixes

* **Patient profile picture chooser opens on the first tap** — The Camera and Gallery options on the patient profile picture sheet sometimes failed to launch or left the sheet stuck. Both now open reliably as soon as you tap them.

**Week of May 25, 2026**

Week of May 25 – May 31

### &#x20;EkaAgents

#### Updates

* **Quicker handoff to booking after picking a doctor** — Once a patient picks a doctor and hospital in a booking conversation, the agent now passes those choices straight to the next step instead of asking again — fewer back-and-forth turns to confirm an appointment.

### &#x20;EMR

#### Updates

* **Clearer "Analysing" state on records** — When a document is still being parsed by AI, the record now shows a small "Analysing" tag with a progress indicator, replacing the previous mixed treatment. Records that get stuck mid-analysis also automatically reset themselves so they don't stay in that state forever.
* **More accurate timestamps on records** — Record creation and last-used timestamps now sync to server time instead of relying on the device clock, so records keep the right order even on devices with skewed time.

### &#x20;EkaScribe

#### New features

* **Drop-in scribe recording widget** — The Eka JS SDK now ships a packaged recording widget you can drop into your own apps, with capture controls and status built in.
* **Next-generation recording entry point** — A new `startRecordingV2` method in the JS SDK exposes the latest scribe recording flow for new integrations.

**Week of May 18, 2026**

Week of May 18 – May 24

### &#x20;EkaAgents

#### New features

* **Appointment lookups inside agent conversations** — AI agents can now show a list of appointments and look up a specific patient's appointments mid-conversation, instead of pushing users back to the EMR for that information.

### &#x20;EMR

#### New features

* **GST printed on receipts** — Templar receipts now include a GST line, so the tax breakdown is visible alongside the line items.

#### Updates

* **Cleaner OPD slips** — The OPD slip print template has been rebuilt for cleaner, more consistent output, paving the way for further design refinements.
* **Smoother record uploads on Android** — Adding records on Android now feels lighter — image processing happens in the background, downloads work cleanly on newer Android versions, and the system handles temporary files more safely.

**Week of May 11, 2026**

Week of May 11 – May 17

### &#x20;EkaAgents

#### Updates

* **Selected hospital surfaced first in booking** — When a user picks a hospital, the agent now lists that hospital's availability at the top instead of burying it under nearby alternatives.
* **Richer responses after doctor availability checks** — Once the agent confirms a doctor is available, the response now carries more context so the next booking step doesn't have to re-ask.

### &#x20;EMR

#### New features

* **Examination findings on prescriptions** — Templar now supports a structured "examination findings" section on prescriptions, with backward compatibility so existing notes-style content keeps rendering as before.

#### Bug fixes

* **Receipt text now wraps correctly** — Fixed a Templar rendering bug where long text stayed on the same line instead of breaking; receipts now wrap cleanly inside the container.

**Week of April 28, 2026**

Week of April 28 – May 4

### &#x20;EkaAgents

#### New features

* **Smarter AI agents that focus on one task at a time** — Agents built on the Echo Agent Kit can now switch between focused flows (for example, doctor booking, lab booking, or appointment cancellations) mid-conversation, only loading the instructions and tools relevant to the active flow. The end result is faster, more on-topic agent responses without bloating every turn with unrelated capabilities.

#### Updates

* **Cleaner file uploads in MedAssist** — The MedAssist web widget now checks supported file types before starting an upload, so unsupported formats are rejected immediately with a clear message instead of failing partway through.

#### Bug fixes

* **MedAssist widget configuration on a partner deployment** — Fixed a configuration glitch that caused the MedAssist web widget to behave incorrectly on one partner surface; the widget now initializes as expected there.

### &#x20;EMR

#### New features

* **Force-fresh patient search** — Apps using the patient directory can now request a live, up-to-the-second patient lookup that bypasses the local cache — useful when freshness matters more than speed.

#### Updates

* **Clinic name on OPD slips** — Printed OPD slips now include the clinic name in the header, making it easier to identify which clinic issued the slip.
* **Cleaner doctor name on IPD receipts and bills** — IPD receipts and bills now show the doctor's name from their profile fields directly, producing cleaner, more consistent print output.
* **Richer diet charts on prescriptions** — Diet chart support on prescriptions has been refined further, building on the diet chart sections introduced earlier in the month.

#### Bug fixes

* **Patient search consistency** — Fixed an edge case where stale cached data in the patient directory SDK could surface incorrect search results; lookups now consistently reflect the live directory.

**Week of April 21, 2026**

Week of April 21 – April 27

### &#x20;EkaAgents

#### New features

* **Doctor availability confirmation mid-chat** — AI agents can now confirm a doctor's availability with the user inside the conversation before completing a booking, reducing back-and-forth.
* **Contextual popup in MedAssist** — The MedAssist web chat widget now shows a contextual popup with relevant suggestions tied to what the user is doing.

#### Updates

* **Optional onboarding nudge** — Clinics can now turn off the first-load nudge in the MedAssist web widget if they prefer a quieter experience for their users.
* **Patient profiles need a mobile number** — When agents create a new patient profile, a mobile number is now required so the patient can always be contacted.

#### Bug fixes

* **MedAssist web microphone** — A short-lived issue that disabled the microphone in the MedAssist web widget was identified and reverted the same day; voice input is working as expected.
* **Correct agent on every conversation** — Fixed an edge case where the MedAssist web widget could route to the wrong agent in certain configurations.

### &#x20;EMR

#### New features

* **Diet charts on prescriptions** — Doctors can now add structured diet plans directly to prescription templates, printed alongside the rest of the prescription.
* **Richer IPD admission notes** — The IPD admission template has been expanded with new fields and a cleaner layout for capturing admission details.

#### Updates

* **Cleaner units on prescriptions** — Lab values and medication units now show a friendlier display label when available, falling back to the standard name otherwise.
* **QR code in the footer** — The QR code on prescription PDFs has moved into the footer details for a tidier header.

#### Bug fixes

* **IPD admission preview** — Fixed a glitch where the rich-text preview of an IPD admission could show stale or malformed content.

### &#x20;EkaScribe

#### Bug fixes

* **Clearer voice-to-text errors on iOS** — DocAssist for iOS now shows a clear error if voice-to-text fails, instead of silently dropping the recording, so users can retry.

**Week of April 14, 2026**

Week of April 14 – April 20

### &#x20;EkaAgents

#### New features

* **OTP login for clinic users** — AI agents can now verify clinic staff identity via SMS OTP during a conversation, including country code selection and profile selection, so users never need to leave the chat to authenticate.

### &#x20;EMR

#### New features

* **ABDM Consent Management SDK** — A new embeddable widget lets you request, track, and manage ABDM health data consents for your patients directly from your application. When a patient approves, their medical records are delivered to your backend automatically.

#### Updates

* **Prescription PDF signatures** — Doctor signatures in prescription PDFs now load reliably without showing outdated cached versions, and signature display can be toggled on or off per template.

* **Eye exam print order** — Ophthalmology examination tables in prescription PDFs now always appear in the correct order.

### &#x20;EkaScribe

#### New features

* **Document management in JS SDK** — You can now create, delete, and retrieve per-chunk transcripts for documents directly from the EkaScribe JS SDK.

**Week of April 7, 2026**

Week of April 7 – April 13

## Updates

* **IPD billing printouts improved** — Printed IPD billing PDFs now clearly show how much has been paid and how much is due, making it easier for billing staff to review at a glance. [View docs](/docs/billing/payments)

* **OPD slips show more detail** — OPD slips now include tags and other patient data, and the token number is printed larger so it is easier to read at the front desk.

* **EkaScribe documentation revamped** — The EkaScribe docs now include a Quick Start guide, reordered integration methods with SDKs recommended first, and improved sidebar navigation. [View docs](/docs/scribe/quickstart)

## Bug fixes

* **Medical records upload** — Uploading very large images no longer causes the app to freeze. You now get a clear message if an image is too large.

* **Health records processing** — Record processing no longer fails when a file goes missing mid-upload.

**Week of March 31, 2026**

Weekly Update Summary

## Weekly Update — Week of March 31, 2026

> 8 updates this week. AI agents gain ABHA login capabilities, EkaScribe gets a Quick Start guide, and new Patient Directory endpoints ship.

### &#x20;EkaScribe

* Added — A new [Quick Start](/docs/scribe/quickstart) guide walks you through integrating EkaScribe with the TypeScript SDK in minutes — from getting credentials to your first transcription.
* Improved — EkaScribe documentation has been reorganized so SDK guides appear first as the recommended path, with clearer titles and deprecated APIs clearly marked.

### &#x20;EMR

* Added — You can now retrieve a patient profile by username and update EMR user profiles (name, contact details, blood group, salutation) through the Patient Directory API. [View docs](/api-sdk/emr/patient-directory-apis/retrieve-patient-by-username)

### &#x20;EkaAgents

* Added — Your AI assistant can now handle ABHA login and profile management during a conversation — initiate login, verify OTP, pick a profile, and pull up the ABHA card without leaving the chat. [View docs](/docs/emr/build-with-ai/mcp-server/supported-tools)
* Improved — MCP Server setup documentation has been reorganized into clear, separate guides for [Remote](/docs/emr/build-with-ai/mcp-server/remote-mcp) and [Local](/docs/emr/build-with-ai/mcp-server/local-mcp) deployments, so you can get connected faster with step-by-step instructions for your specific AI client.
* Improved — MedAssist chat on iOS now stays connected when you switch away from the app and come back — no more lost conversations.
* Fixed — Error messages in MedAssist iOS chat sessions are now shown clearly when something goes wrong, instead of failing without explanation.

### &#x20;EMR

* Improved — Prescription PDFs now include additional ophthalmology tables (pachymetry, Amsler grid, contact lens examination), so more of your eye-care data prints with the prescription. [View docs](/docs/emr/prescription)


# ABDM-enabled HIS
Source: https://developer.eka.care/docs/get-started/whats-possible/abdm-enabled-his

Build a hospital system that registers patients with ABHA, links their visits, shares records with consent and files insurance claims.

This recipe takes a hospital system from the front desk to the insurance claim on India's health stack. It uses [ABDM Connect](/docs/hie-cm/about) and [NHCX](/docs/nhcx/getting-started). Start with the [ABDM Connect quickstart](/docs/hie-cm/quickstart) to get your keys and your first call working.

**1. Register the patient with ABHA**

Create or verify the patient's ABHA at registration with [Milestone 1](/docs/hie-cm/flows/m1). At a busy counter, register patients from a QR code with [scan and share](/docs/hie-cm/scan-and-share/getting-started).

**2. Link each visit to the ABHA**

After the visit, link its records to the patient's ABHA as a provider with [Milestone 2](/docs/hie-cm/flows/m2). The [register and link journey](/docs/hie-cm/journeys/hip-register-patient-and-link-visit) shows the whole flow.

**3. Fetch records from other hospitals with consent**

Ask for the patient's records from other providers and receive them once the patient consents, with [Milestone 3](/docs/hie-cm/flows/m3). See the [fetch with consent journey](/docs/hie-cm/journeys/hiu-fetch-records-with-consent).

**4. Register your doctors and facility**

Enrol your doctors and your facility in the national registries with [Milestone 4](/docs/hie-cm/flows/m4).

**5. File the insurance claim**

Check eligibility, request pre-authorisation and submit the claim through [NHCX](/docs/nhcx/getting-started).

To have a coding agent build this with you, see [Build with AI for ABDM Connect](/docs/hie-cm/build-with-ai).


# Appointments Management
Source: https://developer.eka.care/docs/get-started/whats-possible/appointment-management

Building an appointments management app using the Eka Care SDK's appointments module.

## What We're Building

An appointments management app that demonstrates:

* Getting available slots for doctors
* Booking appointments
* Managing appointment status
* Updating appointment times
* Retrieving appointment details

# Final product

![Hero Light](https://mintcdn.com/ekacare/N05Ge-qB_HKjfni6/images/get-all-appointments.png?fit=max\&auto=format\&n=N05Ge-qB_HKjfni6\&q=85\&s=8b95ce073faf89e337a5677c3bbfaaec)

## Create Next.js App

```bash theme={null}
npx create-next-app@14.1.0 appointments-app
cd appointments-app
```

## Install Eka Care SDK

```bash theme={null}
npm install @eka-care/eka-care-core
```

## Setting Up Backend Auth

Head to this [repo](https://github.com/eka-care/ekathon-nextjs-auth-template-api) and you will have a deployed live running backend in 1 click.

## Building the Appointments App

Replace `pages/index.js` with:

```javascript theme={null}
import { useState, useEffect } from "react";
import createEkaInstance from "@eka-care/eka-care-core";

export default function AppointmentsApp() {
  const [ekaInstance, setEkaInstance] = useState(null);
  const [slots, setSlots] = useState(null);
  const [appointment, setAppointment] = useState(null);
  const [appointmentDetails, setAppointmentDetails] = useState(null);

  useEffect(() => {
    initializeSDK();
  }, []);

  const initializeSDK = async () => {
    const authRes = await fetch(
      "https://your-backend.vercel.app/api/manage-auth",
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
      }
    );

    const authData = await authRes.json();

    const ekaInstanceResult = createEkaInstance({
      source: "FE",
      auth_token: authData.data.access_token,
      backendAuthEndpointURL: "https://your-backend.vercel.app/api/manage-auth",
    });

    setEkaInstance(ekaInstanceResult);
  };

  // Get available slots for a doctor
  const getAvailableSlots = async () => {
    const availableSlots = await ekaInstance.appointments.getSlotsForDoctor({
      doctor_id: "doc123",
      clinic_id: "clinic456",
      start_date: "2025-06-01",
      end_date: "2025-06-01",
    });
    setSlots(availableSlots);
  };

  // Book an appointment
  const bookAppointment = async () => {
    const newAppointment =
      await ekaInstance.appointments.bookAppointmentSlotForDoctor({
        isBusinessOrDoctorAssosiatedWithEka: true,
        clinic_id: "clinic456",
        doctor_id: "doc123",
        patient_id: "patient789",
        appointment_details: {
          start_time: 1748607760,
          mode: "INCLINIC",
        },
        patient_details: {
          dob: "2004-08-01",
          first_name: "John",
          gender: "M",
        },
      });
    setAppointment(newAppointment);
  };

  // Get appointments by date
  const getAppointmentsByDate = async () => {
    const appointments =
      await ekaInstance.appointments.getAllAppointmentsByDate("25-01-06");
  };

  // Get appointment details by ID
  const getAppointmentDetails = async () => {
    const details = await ekaInstance.appointments.getAppointmentDetailsById({
      appointment_id: "apt123",
    });
    setAppointmentDetails(details);
  };

  // Update appointment time
  const updateAppointmentTime = async () => {
    const updatedTime = await ekaInstance.appointments.updateAppointmentTime({
      appointment_id: appointment.appointment_id,
      start_time: Date.now(),
    });
  };

  // Manage appointment status
  const parkAppointment = async () => {
    await ekaInstance.appointments.parkAppointment({
      appointment_id: "apt123",
    });
  };

  const completeAppointment = async () => {
    await ekaInstance.appointments.completeAppointment({
      appointment_id: "apt123",
    });
  };

  const cancelAppointment = async () => {
    await ekaInstance.appointments.cancelAppointment({
      appointment_id: "apt123",
    });
  };

  return (
    <div className="container mx-auto p-8">
      <div>...</div>
    </div>
  );
}
```

## Key SDK Methods Used

1. **Get Slots** - Retrieve available appointment slots for doctors
2. **Book Appointment** - Create new appointments with patient details
3. **Get Appointments** - Fetch appointments by date or ID
4. **Update Time** - Modify appointment start and end times
5. **Status Management** - Park, complete, or cancel appointments

## What We Built

A complete appointments management application using the Eka Care SDK where complex scheduling logic is handled by simple SDK method calls.

[Live App](https://sdk-demo-ui-three.vercel.app/appointments) and
[GitHub Repo](https://github.com/eka-care/web-sdk-ui-wrapper-old)


# Clinically intelligent HIS
Source: https://developer.eka.care/docs/get-started/whats-possible/clinically-intelligent-his

Add an ambient scribe, a medical assistant and agents grounded in Indian medical knowledge to a hospital system.

This recipe adds clinical AI to a hospital system: notes that write themselves, an assistant doctors can ask, and agents that act on the EMR. It uses [Scribe](/docs/scribe/overview), [Agents](/docs/agents/medassist) and [Medical Knowledge](/docs/datasets/overview).

**1. Write the note while the doctor talks**

Add [Scribe](/docs/scribe/quickstart) to the consultation screen, so each visit ends with a structured note in your template.

**2. Give doctors an assistant**

Embed [MedAssist](/docs/agents/medassist) for medical questions during the visit.

**3. Ground answers in Indian medical knowledge**

Look up drugs, labs and treatment protocols with [Medical Knowledge](/docs/datasets/overview), or give an assistant the same data through the [MedAI Tools MCP server](/docs/datasets/build-with-ai/mcp-server/introduction).

**4. Let agents act on the EMR**

Build an agent for one job with the [Echo Agent Kit](/docs/agents/agent-kit/introduction). Give it patients, appointments and prescriptions through the [EMR MCP server](/docs/emr/build-with-ai/mcp-server/introduction).

To have a coding agent build this with you, see Build with AI for [Agents](/docs/agents/build-with-ai) and [Scribe](/docs/scribe/build-with-ai).


# Health Quiz
Source: https://developer.eka.care/docs/get-started/whats-possible/health-assessment

Building a full stack health quiz app with just 4 Function calls, using eka-care's web SDK

# What are we building

An AI based health quiz app, which can be built with just `4 fns`. where the UI is all yours and on the backend side all it takes is just 4 functions i.e,

* to start the quiz,
* generate relevant questions,
* submitting the quiz result
* generating the likelihood of developing the disease

in this app we will be using `@eka-care/eka-care-core` from NPM and Next.js to make a clean health assessment app with the SDK.

# final product

choosing the disease

![Hero Light](https://mintcdn.com/ekacare/N05Ge-qB_HKjfni6/images/health-assessment-init-screen.png?fit=max\&auto=format\&n=N05Ge-qB_HKjfni6\&q=85\&s=a58c37d732564e1c48012869017ce2dd)

answering questions

![Hero Light](https://mintcdn.com/ekacare/N05Ge-qB_HKjfni6/images/health-assessment-ques1.png?fit=max\&auto=format\&n=N05Ge-qB_HKjfni6\&q=85\&s=7b651bca408007f7377d7f8eac4b7c98)

quiz result

![Hero Light](https://mintcdn.com/ekacare/N05Ge-qB_HKjfni6/images/health-assessment-result.png?fit=max\&auto=format\&n=N05Ge-qB_HKjfni6\&q=85\&s=6ed8c107e0a85e9d6e66a936c91b03b3)

## Create a Next.js App

```bash theme={null}
npx create-next-app@14.1.0 eka-carehealth-assessment
cd eka-carehealth-assessment
```

## Install the Eka Care SDK

```bash theme={null}
npm install @eka-care/eka-care-core
```

## Understanding SDK Initialization

The SDK can be initialized on both FE and BE. But for this app we will be initializing the SDK on FE
read more about initializing the SDK [here](https://developer.eka.care/api-sdk/sdks/sdks/web-sdk/getting-started)

## Setting Up Backend Auth.

If you decide to use this on a client side app, head to this [repo](https://github.com/eka-care/ekathon-nextjs-auth-template-api) and you will have a deployed running backend in 1 click, check the `readme.md`

## Now Let's Build a Clean Health Assessment UI

Time to create our main assessment component! and Leverage eka-care's SDK

**Replace `pages/index.js` with:**

```javascript theme={null}
import createEkaInstance from "@eka-care/eka-care-core";

export default function HealthAssessment() {
  const [ekaInstance, setEkaInstance] = useState(null);
  const [assessment, setAssessment] = useState(null);
  const [results, setResults] = useState(null);

  useEffect(() => {
    initializeSDK();
  }, []);

  const initializeSDK = async () => {
    const authRes = await fetch(
      "https://the-deployed-vercel-backend/api/manage-auth",
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
      }
    );

    const authData = await authRes.json();

    const ekaInstanceResult = createEkaInstance({
      source: "FE",
      auth_token: authData.data.access_token,
      backendAuthEndpointURL: `https://the-deployed-vercel-backend/api/manage-auth`, // this gets deployed in 1 click, please refer above
    });

    setEkaInstance(ekaInstanceResult);
  };

  const startAssessment = async () => {
    const assessmentResponse = await ekaInstance.assessment.initAssessment({
      client_id: "client_id_given_by_eka-care",
      user_info: {
        gender: "M",
        age: 25,
      },
      workflow_id: 814,
    });

    setAssessment(assessmentResponse);

    const startResponse = await ekaInstance.assessment.startAssessment({
      assessment_id: assessmentResponse.assessment_id,
      client_id: "client_id_given_by_eka-care",
    });

    if (startResponse.questions && startResponse.questions.length > 0) {
      const firstQuestion = startResponse.questions[0];

      await ekaInstance.assessment.continueAssessment({
        assessment_id: assessmentResponse.assessment_id,
        client_id: "client_id_given_by_eka-care",
        qid: firstQuestion.qid,
        user_response: "users response",
      });

      const finalResults = await ekaInstance.assessment.submitAssessment({
        assessment_id: assessmentResponse.assessment_id,
        client_id: "client_id_given_by_eka-care",
      });

      setResults(finalResults);
    }
  };

  return <div className="container mx-auto p-8">...</div>;
}
```

## What We Just Built

Congratulations! You've just created a complete health assessment application using the Eka Care SDK. Where most LOC was just React and UI part while the whole logic of auth, refresh, starting, continuing and submitting got abstracted in just `4 fns` that we called with a simple async await. Here's what our app includes:

## Key SDK Methods Demonstrated

1. **Initialize SDK** - Create SDK instance with frontend configuration
2. **Init Assessment** - Start a new health assessment workflow
3. **Start Assessment** - Begin the assessment and get first questions
4. **Continue Assessment** - Submit responses and get next questions
5. **Submit Assessment** - Complete the assessment and get results

## Next Steps

From here, you could extend this app by:

* Integrating with the appointments module to book consultations
* Adding medication search functionality
* Building a patient management dashboard

The Eka Care SDK makes it incredibly easy to build comprehensive healthcare applications - this app just scratches the surface of what's possible!

[Live app](https://sdk-demo-ui-three.vercel.app/assessment) and [Github repo](https://github.com/eka-care/web-sdk-ui-wrapper-old)


# Connect your agent to Eka with MCP
Source: https://developer.eka.care/docs/get-started/whats-possible/mcp-connectors

Every Eka MCP server, and how to plug each one into Claude, Cursor or your own agent as a set of tools.

Eka publishes its data and actions as MCP servers. An MCP server is a connector. Once your agent connects to one, the server's tools appear in the agent, and it calls them when a question needs them. Any MCP client works, from Claude and Cursor to an agent you build yourself.

## The servers

| Server | What your agent can do with it | Address | Sign-in |
| - | - | - | - |
| [Eka MCP](/docs/emr/build-with-ai/mcp-server/introduction) | Search and register patients, book and manage appointments, create prescriptions, read doctor and clinic data | `https://mcp.eka.care/mcp` | Your Eka.care account, on first connect. A self-hosted version uses a client ID and secret instead |
| [MedAI Tools MCP](/docs/datasets/build-with-ai/mcp-server/introduction) | Search Indian branded drugs, find treatment protocols, look up pharmacology, run clinical calculators | `https://medai-tools.eka.care/mcp` | Your Eka account, on first connect |

**1. Pick the servers your agent needs**

An agent that acts on a clinic's records needs the Eka EMR server. An agent that answers clinical questions needs MedAI Tools. An agent can use both at once.

**2. Connect an assistant you already use**

In Claude, Cursor or VS Code, add the server's address as a remote MCP server and sign in when asked. Each server's page has the steps for every client: [Eka EMR](/docs/emr/build-with-ai/mcp-server/remote-mcp) and [MedAI Tools](/docs/datasets/build-with-ai/mcp-server/quickstart).

**3. Or connect your own agent**

With the [Echo Agent Kit](/docs/agents/agent-kit/introduction), point an MCP connection at the server's address and pass its tools to your agent. The [MCP integration](/docs/agents/agent-kit/mcp-integration) page shows the code, including how to connect several servers at once.

**4. Check what the agent can call**

List the tools the server gives your agent before you rely on them. The full lists are on the [Eka EMR tools](/docs/emr/build-with-ai/mcp-server/supported-tools) and [MedAI Tools tools](/docs/datasets/build-with-ai/mcp-server/tools) pages.

To have a coding assistant build an agent like this with you, see [Build with AI for Medical Agents](/docs/agents/build-with-ai).


# Medical records from any source
Source: https://developer.eka.care/docs/get-started/whats-possible/medical-records-from-any-source

Turn a consultation, a photo of a report or a PDF into one structured, coded medical record.

This recipe turns whatever arrives at a clinic, a spoken consultation, a photo of a lab report or a PDF, into one structured medical record. It uses [Scribe](/docs/scribe/overview), [Document Parsing](/docs/models/medical-document-parsing) and [Health Records](/docs/health-records/upload-records).

**1. Turn the consultation into a note**

Record or stream the consultation with [Scribe](/docs/scribe/quickstart). It returns a structured note in the [template](/api-sdk/scribe/templates/list-templates) you choose, and a [FHIR bundle](/docs/scribe/resources/fhir-structure).

**2. Read reports, PDFs and photos**

Upload a lab report as a PDF or an image with [Document Parsing](/docs/models/medical-document-parsing). It returns the values in the report as structured data.

**3. Code what was found**

Map the diagnoses, medicines and tests to standard codes with [medical entity codification](/docs/models/medical-entity-codification), so other systems can read them.

**4. Keep it in the patient's record**

Save the note and the parsed report against the patient with [Health Records](/docs/health-records/upload-records).

To have a coding agent build this with you, see Build with AI for [Scribe](/docs/scribe/build-with-ai) and [Document Parsing](/docs/models/build-with-ai).


# Medication Search
Source: https://developer.eka.care/docs/get-started/whats-possible/medicine-lookup

Building a full stack Building a medication search app using the Eka Care SDK's medication search module.

## What We're Building

A medication search app that demonstrates:

* Searching medications by drug name
* Advanced search with multiple parameters
* Search by generic names
* Displaying comprehensive medication details

# Final product

![Hero Light](https://mintcdn.com/ekacare/N05Ge-qB_HKjfni6/images/medicine-search1.png?fit=max\&auto=format\&n=N05Ge-qB_HKjfni6\&q=85\&s=7b4bad35e9782d3893959eb680ce46ba)

## ![Hero Light](https://mintcdn.com/ekacare/N05Ge-qB_HKjfni6/images/medicine-search-results2.png?fit=max\&auto=format\&n=N05Ge-qB_HKjfni6\&q=85\&s=282970dbfba200c0e50d37236aeed894)

## Create Next.js App

```bash theme={null}
npx create-next-app@14.1.0 medication-search-app
cd medication-search-app
```

## Install Eka Care SDK

```bash theme={null}
npm install @eka-care/eka-care-core
```

## Setting Up Backend Auth

Head to this [repo](https://github.com/eka-care/ekathon-nextjs-auth-template-api) and you will have a deployed live running backend in 1 click.

## Building the Medication Search App

Replace `pages/index.js` with:

```javascript theme={null}
import { useState, useEffect } from "react";
import createEkaInstance from "@eka-care/eka-care-core";

export default function MedicationSearch() {
  const [ekaInstance, setEkaInstance] = useState(null);
  const [searchResults, setSearchResults] = useState(null);
  const [searchQuery, setSearchQuery] = useState("");

  useEffect(() => {
    initializeSDK();
  }, []);

  const initializeSDK = async () => {
    const authRes = await fetch(
      "https://your-backend.vercel.app/api/manage-auth",
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
      }
    );

    const authData = await authRes.json();

    const ekaInstanceResult = createEkaInstance({
      source: "FE",
      auth_token: authData.data.access_token,
      backendAuthEndpointURL: "https://your-backend.vercel.app/api/manage-auth",
    });

    setEkaInstance(ekaInstanceResult);
  };

  // Basic search by drug name
  const searchMedications = async () => {
    const medications = await ekaInstance.medicationSearch.searchMedications({
      drug_name: searchQuery,
    });
    setSearchResults(medications);
  };

  // Advanced search with multiple parameters
  const advancedSearch = async () => {
    const medications = await ekaInstance.medicationSearch.searchMedications({
      drug_name: "dolo",
      form: "tablet",
      volumes: "500",
    });
    setSearchResults(medications);
  };

  // Search by generic names
  const searchByGeneric = async () => {
    const medications = await ekaInstance.medicationSearch.searchMedications({
      generic_names: "Glimeperide,Metformin",
      drug_name: "Glimeperide",
    });
    setSearchResults(medications);
  };

  return (
    <div className="container mx-auto p-8">
      <div>...</div>
    </div>
  );
}
```

## Key SDK Methods Used

1. **Basic Search** - Search medications by drug name
2. **Advanced Search** - Search with form, volume, and other parameters
3. **Generic Search** - Search by generic medication names

## What We Built

A complete medication search application using the Eka Care SDK where the core functionality is handled by just 3 search method variations.

[Live App](https://sdk-demo-ui-three.vercel.app/medicine-search) and
[GitHub Repo](https://github.com/eka-care/web-sdk-ui-wrapper-old)


# Patients Management App
Source: https://developer.eka.care/docs/get-started/whats-possible/patient-management

Building a patients management app using the Eka Care SDK's patients module.

## What We're Building

A patients management app that demonstrates:

* Adding new patients to directory
* Searching patients by mobile number
* Getting patient details by ID
* Updating patient information

# Final product

adding a patient

![Hero Light](https://mintcdn.com/ekacare/N05Ge-qB_HKjfni6/images/add-patient.png?fit=max\&auto=format\&n=N05Ge-qB_HKjfni6\&q=85\&s=d03c60727c825e32151b034597fb265f)

Searching for patient with mobile number

![Hero Light](https://mintcdn.com/ekacare/N05Ge-qB_HKjfni6/images/search-patient.png?fit=max\&auto=format\&n=N05Ge-qB_HKjfni6\&q=85\&s=47ead93a6b175b1937ce8997dd67cb7f)

getting more details about a patient

![Hero Light](https://mintcdn.com/ekacare/N05Ge-qB_HKjfni6/images/get-patient-profile.png?fit=max\&auto=format\&n=N05Ge-qB_HKjfni6\&q=85\&s=a79ac759c466a8d80ae9d202dcd88bcd)

## Create Next.js App

```bash theme={null}
npx create-next-app@14.1.0 patients-app
cd patients-app
```

## Install Eka Care SDK

```bash theme={null}
npm install @eka-care/eka-care-core
```

## Setting Up Backend Auth

Head to this [repo](https://github.com/eka-care/ekathon-nextjs-auth-template-api) and you will have a deployed live running backend in 1 click.

## Building the Patients App

Replace `pages/index.js` with:

```javascript theme={null}
import { useState, useEffect } from 'react';
import createEkaInstance from "@eka-care/eka-care-core";

export default function PatientsApp() {
  const [ekaInstance, setEkaInstance] = useState(null);
  const [newPatient, setNewPatient] = useState(null);
  const [patient, setPatient] = useState(null);
  const [patientDetails, setPatientDetails] = useState(null);

  useEffect(() => {
    initializeSDK();
  }, []);

  const initializeSDK = async () => {
    const authRes = await fetch("https://your-backend.vercel.app/api/manage-auth", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
    });

    const authData = await authRes.json();

    const ekaInstanceResult = createEkaInstance({
      source: "FE",
      auth_token: authData.data.access_token,
      backendAuthEndpointURL: "https://your-backend.vercel.app/api/manage-auth",
    });

    setEkaInstance(ekaInstanceResult);
  };

  // Add new patient to directory
  const addNewPatient = async () => {
    const patient = await ekaInstance.patients.addPatientToDirectory({
      first_name: "John",
      gender: "M",
      mobile: "918074106021",
      dob: "2004-08-01",
    });
    setNewPatient(patient);
  };

  // Search patient by mobile number
  const searchPatient = async () => {
    const foundPatient = await ekaInstance.patients.searchPatientByMobile({
      mobile: "918074106021",
    });
    setPatient(foundPatient);
  };

  // Get patient details by ID
  const getPatientDetails = async () => {
    const details = await ekaInstance.patients.getPatientDetailsById({
      patient_id: "174860072074280",
    });
    setPatientDetails(details);
  };

  // Update patient details
  const updatePatientDetails = async () => {
    const updatedPatientDetails = await ekaInstance.patients.updatePatientDetails({
      patient_id: newPatient.patient_id,
      first_name: "John Updated",
      address: {
        city: "BLR",
        country: "IN",
      },
      dob: "2000-10-10",
    });
  };

  return (
    <div className="container mx-auto p-8">
      <div>...</div>
    </div>
  );
}
```

## Key SDK Methods Used

1. **Add Patient** - Register new patients in the directory
2. **Search Patient** - Find patients by mobile number
3. **Get Details** - Retrieve complete patient information
4. **Update Details** - Modify patient information and address

## What We Built

A complete patients management application using the Eka Care SDK where patient operations are handled through simple SDK method calls.

[Live App](https://sdk-demo-ui-three.vercel.app/patients) and
[GitHub Repo](https://github.com/eka-care/web-sdk-ui-wrapper-old)


# ABDM
Source: https://developer.eka.care/docs/hie-cm/about

What ABDM is, who takes part in it, and what you can build with Eka's ABDM Connect.

## ABDM Connect

**Ayushman Bharat Digital Mission (ABDM)** is India's national digital health infrastructure. It creates a shared ecosystem where patients, hospitals, labs, insurers, and health apps can exchange health data securely, with patient consent driving every transaction.

Eka's **ABDM Connect** is a plug-and-play API and SDK suite that handles the ABDM gateway complexity for you, so your team can focus on the product rather than the plumbing.

## The ABDM Ecosystem

### Core Registries

ABDM is built on four registries. Every entity gets a unique, verifiable identity through one of these.

> **ABHA**
>
> **Ayushman Bharat Health Account**
>
> The patient's health identity. Can be a 14-digit **ABHA Number** (KYC-verified via Aadhaar) or an **ABHA Address** like `nisha@abdm`. All health transactions in ABDM are anchored to this.

> **HPR**
>
> **Healthcare Professionals Registry**
>
> A national registry of licensed healthcare professionals. Each doctor, nurse, or practitioner gets a unique **HPR ID** for verified digital identity.

> **HFR**
>
> **Health Facility Registry**
>
> A national registry of health facilities, both government and private. Each facility gets a unique **HFR ID** used for record linking and patient discovery.

> **Consent Manager**
>
> **Consent Manager**
>
> Manages the consent flow between HIPs (who hold data) and HIUs (who want access). The ABDM Gateway itself acts as the Consent Manager.

### Roles in the Ecosystem

There are two roles in ABDM. A product can play both.

> **HIP**
>
> **Health Information Provider**
>
> Hospitals, labs, clinics, and pharmacies that generate and hold patient health records. After a visit or test, a HIP links the records to the patient's ABHA address so they're discoverable and shareable.
>
> *Examples: hospital HMS, diagnostic lab system, pharmacy software*

> **HIU**
>
> **Health Information User**
>
> Any entity that requests access to a patient's health records with the patient's consent. After consent is granted, the HIU receives the records from the relevant HIPs.
>
> *Examples: insurance company, specialist referral system, wellness platform*

## CARE: the four milestones

ABDM certifies hospital and lab software (HMIS/LMIS) in four milestones. Read them as CARE: **C**reate, **A**ttach, **R**etrieve, **E**nrol. Eka's ABDM Connect covers all four.

**1. Create (M1): the patient's ABHA**

Needed by every integration.

Before any record can be linked or shared, the patient needs an ABHA. Your product lets patients create an ABHA or log in with an existing one, view and update their profile, download their ABHA card, and check in at your facility by scanning a QR code.

**2. Attach (M2): records to the ABHA**

Needed by hospitals, labs, clinics, and pharmacies (HIPs).

After each visit or test, the records are linked to the patient's ABHA address. Patients can also find records you hold and link them themselves. When the patient consents to share them, your records are sent to whoever asked. Eka can store the records and handle sharing for you.

**3. Retrieve (M3): records, with consent**

Needed by anyone who wants to view a patient's records (HIUs).

You ask the patient for consent, the patient approves or denies it in their app, and once approved you receive the records from every provider they chose. Patients can revoke consent at any time.

**4. Enrol (M4): doctors and facilities**

Needed by every hospital and lab software integration.

Doctors and nurses get an HPR ID and facilities get an HFR ID, so they can take part in digital health transactions. Eka also links your facilities to Eka's bridge so records can flow.

## Journeys

One patient, all of CARE. Meera walks into a clinic without an ABHA; the receptionist creates one with her Aadhaar OTP (Create) and attaches the visit to it (Attach). A month later her insurer asks for the records. She approves the request in her PHR app, and the insurer retrieves the FHIR bundle from the clinic (Retrieve).

None of this works until the clinic and its doctors are enrolled in HFR and HPR (Enrol). The same story told from Meera's own app is the PHR track.

Each journey below is one person's story, in product terms, linking the workflows that implement each step.

| Your role | Journeys |
| - | - |
| Health facility software (HIP) | [Register a walk-in patient and link the visit](/docs/hie-cm/journeys/hip-register-patient-and-link-visit), [Let a patient claim their old records](/docs/hie-cm/journeys/hip-answer-discovery) |
| Insurer, referral or analytics platform (HIU) | [Fetch a patient's records with consent](/docs/hie-cm/journeys/hiu-fetch-records-with-consent) |
| Patient app (PHR) | [Gather every health record in a PHR app](/docs/hie-cm/journeys/phr-patient-aggregates-records) |
| Facility admin or HMS vendor | [Onboard a facility and its professionals to ABDM](/docs/hie-cm/journeys/facility-onboard-to-abdm) |
| Consumer app on UHI | [Book an in-person doctor visit over UHI](/docs/uhi/journeys/uhi-book-physical-consultation), [Pay an open bill by scanning the counter QR](/docs/uhi/journeys/uhi-scan-and-pay) |

## PHR App

A PHR (Personal Health Record) app is a separate ABDM track, distinct from the milestones above. It is the patient-facing side of ABDM: patients create their ABHA, see records from every provider they've visited, manage consent, and share their profile at health facilities.

A PHR app typically acts as both a HIP (storing records the patient uploads) and a HIU (fetching records from other providers on the patient's behalf). It covers:

* ABHA creation and patient login
* A single view of every linked record
* Approving or denying consent requests
* **Scan & Share**: the patient scans a QR code at a facility to share their profile for registration
* **Health locker**: storage the patient controls for their own documents
* **Notifications** when a provider links a new record

## What You Can Build

> **Hospital / Clinic Product (HMS)**
>
> If you run a hospital or clinic system, you need to be a HIP. After every visit or test, link the patient's records to their ABHA address. When a patient later consents to share them with another entity (like an insurer), your system serves those records automatically.

> **Consumer Health App (PHR)**
>
> If you're building a patient-facing app, you need the PHR track on top of the milestones. Patients can bring together their entire health history from every facility they've visited, manage consent, and check in at facilities by scanning a QR code.

> **Insurance / Analytics Platform (HIU)**
>
> If you need to access a patient's health records from any ABDM-connected provider, you need to be an HIU. You request consent from the patient and, once it is granted, receive their records directly.

> **Integrated Health Platform**
>
> Large hospital networks and health platforms often need to be HIP, HIU, and PHR at once. Your HMS links records (HIP), doctors can pull history from outside (HIU), and patients have a portal to manage everything (PHR).

## Ready to Build?

> **[ABDM Connect API Reference](/api-sdk/hie-cm/overview)**
>
> Environments, authentication, the Postman collection, and every API and callback by milestone.

> **[Onboarding & Credentials](/api-sdk/auth/getting-started#overview)**
>
> Get your credentials and onboard into ABDM through Eka Connect.


# Build with AI
Source: https://developer.eka.care/docs/hie-cm/build-with-ai

Set up a coding agent to build your ABDM Connect integration with the abdm-connect plugin.

Use the abdm-connect plugin to have a coding assistant build your ABDM Connect integration, milestone by milestone.

> [!NOTE]
>
> Check what the assistant writes against these docs, and test it in the sandbox before it reaches a patient.

> **[abdm-connect plugin](#install-the-plugin)**
>
> Commands that integrate ABDM Connect into your code, check what is done, and debug a failure.

## Before you start

Three things have to be in place before anything on this page works.

| What you need | Why |
| - | - |
| A coding assistant | Claude Code, Cursor, Codex or ChatGPT. Any one is enough. Pick one and stay on it. |
| A paid plan on it | Free tiers stop partway through a long task. |
| Your own project open in it | The assistant reads and writes the folder it is opened in. Open the repository you are building in first. |

Then work down this page in order: install the skill, connect the MCP server where there is one, and ask for one flow at a time in plain language. Read what the assistant writes before you run it.

## Install the plugin

> [!WARNING]
>
> The plugin covers M1 (ABHA creation and login) only for now. The M2 to M4 commands are listed below and are being expanded; check their output against these docs before you rely on it.

In Claude Code:

```bash theme={null}
/plugin marketplace add eka-care/abdm-utility
/plugin install abdm-connect@eka-abdm
```

In Cursor, Codex or another agent, copy the [skills folder](https://github.com/eka-care/abdm-utility/tree/main/skills) into the folder your agent loads skills from.

| Command | What it does |
| - | - |
| `/abdm-connect:integrate-m1` | ABHA creation and login, from your code to a passing sandbox test |
| `/abdm-connect:integrate-m2` | Care context linking and sharing records as a HIP |
| `/abdm-connect:integrate-m3` | Consent and fetching records as a HIU |
| `/abdm-connect:integrate-m4` | HPR and HFR registration and facility onboarding |
| `/abdm-connect:abdm-status` | What is integrated, what is missing, and compliance gaps |
| `/abdm-connect:abdm-debug` | Diagnose a failure from its error code or symptom |

Each integrate command reads your codebase and asks you once for credentials and UI decisions. It shows you a plan, builds, and tests on the sandbox until it passes. Its skills also answer questions as you work, such as which `hi_type` a lab report is.

## Prompting an agent for ABDM Connect

Tell the assistant these, and check its output against them.

| Tell it | Because |
| - | - |
| Look each endpoint up here before writing the call | The plugin carries the flows. The request and response shapes live on the reference pages, which are current. |
| Never store an Aadhaar number or an OTP | They are needed for one call and must not reach a database, a log or a test fixture. |
| Make webhook handlers safe to run twice | The same event can arrive more than once. Handle it once and acknowledge every copy. |
| Test against the sandbox first | Build and test against `api.dev.eka.care` until every flow passes, then switch to production. |
| Leave the ABDM portal steps to a person | Facility approval and Software Linkage happen on the ABDM portal, outside any API. |

## Read these docs as an agent

Every page here is also plain text an agent can read.

* [`llms.txt`](https://developer.eka.care/llms.txt) is a map of every page.
* [`llms-full.txt`](https://developer.eka.care/llms-full.txt) is every page's text in one file.
* The menu at the top of each page copies it as Markdown, or opens it in Claude or ChatGPT.


# Care Context Discovery
Source: https://developer.eka.care/docs/hie-cm/care-contexts/discover/introduction



ABDM allows a user to find their health records from any health facility they have visited via the discovery process.

When a discovery request is initiated by the user, the HIP will receive a list of verified identifiers along with name and demographic information. Verified information includes the ABHA address, the mobile number name, gender, year of birth.

## Overview for HIP Clients

If you are integrating as a HIP — a clinic, hospital, or health information system using Eka's APIs — this section explains how Care Context Discovery works end-to-end and what your system needs to handle.

### How Eka fits in

Eka acts as the middleware between ABDM and your system. You do not communicate with ABDM directly. Instead:

* ABDM sends all discovery and linking requests to Eka.
* Eka forwards them to your system via **webhooks**.
* Your system processes the request and responds back to Eka via **API calls**.
* Eka forwards your response to ABDM.

### End-to-End Flow

#### Phase 1 — Discovery

**1. Patient triggers discovery from a PHR app**

The patient opens any ABDM-compatible PHR app (e.g. ABHA app) and searches for their records at your facility. ABDM routes the request to Eka based on your registered HIP ID.

**2. Eka sends you a Discovery webhook**

Eka forwards the request to your registered webhook URL. The payload contains the patient's ABHA address, name, gender, year of birth, and other verified identifiers (mobile number, ABHA number).

* **Webhook Reference:** [Discovery Request Received](/docs/hie-cm/webhooks/discover-care-context)

**3. You search and respond with matching care contexts**

Search your system using the identifiers provided. Return the list of unlinked care contexts (e.g. visits, prescriptions, lab reports) that belong to this patient.

The `abha_address` in the webhook payload is a verified identifier — confirmed by ABDM, not self-declared by the patient. As per ABDM guidelines, it is the HIP's prerogative to save this to the matched patient's profile. If stored, you can use the ABHA address in future HIP-initiated linking flows to link new care contexts directly, without requiring the patient to go through discovery again.

* **API Reference:** [On Discover](/api-sdk/hie-cm/care-contexts/discover/on_discover)

#### Phase 2 — Linking

**1. Patient selects care contexts to link**

The patient reviews the care contexts returned in Phase 1 and selects the ones they want to link to their ABHA account. ABDM notifies Eka, which forwards the request to your system.

* **Webhook Reference:** [Link Initiation - Generate OTP](/docs/hie-cm/webhooks/discover-link-init)

**2. You generate and send an OTP**

Generate an OTP and deliver it to the patient's registered mobile number. Then notify Eka that the OTP has been dispatched.

* **API Reference:** [On Link Init](/api-sdk/hie-cm/care-contexts/discover/link_on_init)

**3. Patient submits OTP — you verify and confirm**

The patient enters the OTP in the PHR app. ABDM validates it and sends a confirmation to Eka, which forwards it to your system via a webhook containing the OTP token.

Your system must validate this token against the OTP you generated in the previous step. If valid, call the `on-link-confirm` API with the list of care contexts to be linked.

**Who does the linking?** You do — by calling `on-link-confirm`, your system is confirming to ABDM that the OTP is valid and that the selected care contexts should be linked. ABDM then registers the linkage on its side. You do not need to call the separate HIP-initiated Link API for this flow.

**Which HIP are the records linked to?** The care contexts are linked to your HIP, identified by the `hip_id` present in the webhook payload. This is the same HIP the patient searched when triggering discovery — the facility whose records they are claiming.

* **Webhook Reference:** [Link Confirmation - Verify OTP](/docs/hie-cm/webhooks/discover-link-confirm)
* **API Reference:** [On Link Confirm](/api-sdk/hie-cm/care-contexts/discover/link_on_confirm)

Once linking is confirmed, the care contexts are registered with ABDM under the patient's ABHA account and can be accessed by HIUs (e.g. doctors, hospitals) through the ABDM consent flow.

***

## PHR Flow

**1. Discover Unlinked CareContexts**

Use the discover api to get a list of care-contexts that are not linked to the user's account.
Linking Process is initiated by the user by providing the care-context id and the verification code is sent to the user's mobile number.

* **API Reference:** [Discover Unlinked CareContexts](/api-sdk/hie-cm/care-contexts/discover/discover)

**2. Initiate the linking**

Use the link init api to initiate the linking process, the HIP will send an OTP to the user's mobile number.

* **API Reference:** [Initiate the linking](/api-sdk/hie-cm/care-contexts/discover/link-init)

**3. Confirm the linking with OTP**

Use `txn_id` from the previous step and OTP sent to the user's mobile number to confirm the linking.

* **API Reference:** [Confirm the linking with OTP](/api-sdk/hie-cm/care-contexts/discover/link-confirm)

## HIP Flow

**1. On Discover**

The HIP receives a discovery request and returns the list of unlinked care-contexts associated with the user.

* **API Reference:** [On Discover](/api-sdk/hie-cm/care-contexts/discover/on_discover)

**2. On Link Init**

After generating the OTP, the HIP should call the `on-link-init` API to notify the ABDM gateway about the OTP sent.

* **API Reference:** [On Link Init](/api-sdk/hie-cm/care-contexts/discover/link_on_init)

**3. On Link Confirm**

After verifying the OTP and initiating the linking of the care-context, the HIP should call the on-link-confirm API to notify the ABDM gateway about the successful linking of the unlinked health record.

* **API Reference:** [On Link Confirm](/api-sdk/hie-cm/care-contexts/discover/link_on_confirm)


# Encryption
Source: https://developer.eka.care/docs/hie-cm/care-contexts/ecdh-encryption

ECDH encryption for ABDM health data exchange using the open-source abdm-ecdh library.


ABDM's HIE-CM specification requires a specific ECDH-based encryption scheme for exchanging health records between parties. Use the open-source [**eka-care/abdm-ecdh**](https://github.com/eka-care/abdm-ecdh) library to perform all cryptographic operations.

> [!NOTE]
>
> The library implements ECDH key agreement on Curve25519 (Weierstrass form) — matching Java/BouncyCastle — with HKDF-SHA256 key derivation and AES-256-GCM encryption. This is the same algorithm required by ABDM.

## Installation

```bash Go theme={null}
go get github.com/eka-care/abdm-ecdh/go@v1.0.0
```

```bash Python theme={null}
pip install abdm-ecdh
```

```xml Java (Maven) theme={null}
<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

<dependency>
  <groupId>com.github.eka-care</groupId>
  <artifactId>abdm-ecdh</artifactId>
  <version>java/v1.0.0</version>
</dependency>
```

## Usage

```go Go theme={null}
package main

import (
    abdmecdh "github.com/eka-care/abdm-ecdh/go"
    "fmt"
)

func main() {
    e := abdmecdh.New()

    // Each party generates their own key material
    sender, err := e.GenerateKeyMaterial()
    if err != nil {
        panic(err)
    }
    requester, err := e.GenerateKeyMaterial()
    if err != nil {
        panic(err)
    }

    // Sender encrypts
    enc, err := e.Encrypt(abdmecdh.EncryptionRequest{
        StringToEncrypt:    "sensitive health data",
        SenderNonce:        sender.Nonce,
        RequesterNonce:     requester.Nonce,
        SenderPrivateKey:   sender.PrivateKey,
        RequesterPublicKey: requester.X509PublicKey,
    })
    if err != nil {
        panic(err)
    }

    // Requester decrypts
    dec, err := e.Decrypt(abdmecdh.DecryptionRequest{
        EncryptedData:       enc.EncryptedData,
        SenderNonce:         sender.Nonce,
        RequesterNonce:      requester.Nonce,
        RequesterPrivateKey: requester.PrivateKey,
        SenderPublicKey:     sender.X509PublicKey,
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(dec.DecryptedData) // "sensitive health data"
}
```

```python Python theme={null}
from abdm_ecdh import generate_key_material, encrypt, decrypt

# Each party generates their own key material
sender    = generate_key_material()
requester = generate_key_material()

# Sender encrypts
enc = encrypt(
    string_to_encrypt="sensitive health data",
    sender_nonce=sender.nonce,
    requester_nonce=requester.nonce,
    sender_private_key=sender.private_key,
    requester_public_key=requester.x509_public_key,
)

# Requester decrypts
dec = decrypt(
    encrypted_data=enc.encrypted_data,
    sender_nonce=sender.nonce,
    requester_nonce=requester.nonce,
    requester_private_key=requester.private_key,
    sender_public_key=sender.x509_public_key,
)

print(dec.decrypted_data)  # "sensitive health data"
```

```java Java theme={null}
import care.eka.abdmecdh.AbdmEcdh;
import care.eka.abdmecdh.KeyMaterial;
import care.eka.abdmecdh.EncryptionResponse;
import care.eka.abdmecdh.DecryptionResponse;

// Each party generates their own key material
KeyMaterial sender = AbdmEcdh.generateKeyMaterial();
KeyMaterial requester = AbdmEcdh.generateKeyMaterial();

// Sender encrypts
EncryptionResponse enc = AbdmEcdh.encrypt(
    "sensitive health data",
    sender.nonce(),
    requester.nonce(),
    sender.privateKey(),
    requester.x509PublicKey()
);

// Requester decrypts
DecryptionResponse dec = AbdmEcdh.decrypt(
    enc.encryptedData(),
    sender.nonce(),
    requester.nonce(),
    requester.privateKey(),
    sender.x509PublicKey()
);

System.out.println(dec.decryptedData()); // "sensitive health data"
```

## Key Material

`GenerateKeyMaterial` / `generate_key_material` returns:

| Field | Description |
| - | - |
| `privateKey` / `private_key` | Base64-encoded private scalar |
| `publicKey` / `public_key` | Base64-encoded uncompressed EC point (65 bytes) |
| `x509PublicKey` / `x509_public_key` | Base64-encoded X.509 SubjectPublicKeyInfo DER — share with the counterparty |
| `nonce` / `nonce` | Base64-encoded 32-byte random nonce — share with the counterparty |

## Cryptographic Details

| Step | Algorithm |
| - | - |
| Key agreement | ECDH on Curve25519 (Weierstrass form) |
| Key derivation | HKDF-SHA256 (salt = first 20 bytes of XOR'd nonces) |
| Encryption | AES-256-GCM (IV = last 12 bytes of XOR'd nonces) |
| Key encoding | X.509 SubjectPublicKeyInfo DER (BouncyCastle explicit params) |

For more details, see the [ABDM Encryption and Decryption Guide](https://sandbox.abdm.gov.in/sandbox/v3/new-documentation?doc=EncryptionandDecryptions) and the [abdm-ecdh source](https://github.com/eka-care/abdm-ecdh).


# Overview
Source: https://developer.eka.care/docs/hie-cm/care-contexts/getting-started



A Care Context represents a logical grouping of health records. Each HMIS, LMIS, or PHR system should determine how to organize data into one or more care contexts for a user. For example, a hospital system might create a care context for each hospital visit, a lab test is a care-context for LMIS, or user-uploaded records in a PHR app.

# Care Context Linking and Data Sharing

Enables health data exchange between Health Information Providers (HIPs) and Health Information Users (HIUs).

**1. Link Care Contexts (HIP)**

The HIP links a care context to the patient's ABHA address using the [Care Context Link API](/api-sdk/hie-cm/care-contexts/link/hip-linking). This registers the care context with ABDM so it can be discovered and requested by HIUs.

You can optionally include the FHIR data as a base64-encoded string in the `data` field of the Link API request. If provided, Eka stores the data on its servers and handles data sharing automatically when an HIU requests it — you will **not** need to handle the `abha.hip_data_fetch` webhook.

**2. Receive Linking Confirmation**

Listen for the [`abha.link_care_context`](/docs/hie-cm/webhooks/link-care-context) webhook to confirm whether the care context was successfully linked (`LINKED`) or failed (`ERRORED`).

**3. Handle Data Fetch Requests**

When an HIU requests data for a linked care context (after the user grants consent), you receive the [`abha.hip_data_fetch`](/docs/hie-cm/webhooks/hip-data-fetch) webhook. This webhook is sent only if you are **not** storing the data on Eka servers and need to provide it yourself.

**4. Push Encrypted Data**

Prepare the ABDM-compliant FHIR bundle for the requested care contexts, encrypt it using the key information from the webhook, and push it via the [Care Context Data On-Fetch API](/api-sdk/hie-cm/care-contexts/data-on-fetch).

> [!NOTE]
>
> If you store health data on Eka servers — either by passing base64-encoded FHIR data in the `data` field of the [Link API](/api-sdk/hie-cm/care-contexts/link/hip-linking), or via the [Upload API](/api-sdk/health-records/obtain-authorization) — Eka handles data sharing automatically and you will **not** receive the `abha.hip_data_fetch` webhook.

***

# Listing Care Contexts

> [!NOTE]
>
> This feature is useful for displaying a list of care contexts to a doctor (HMIS) or within a PHR app.

Listing linked Care Contexts involves two steps, as an ABHA address could have thousands of documents associated with multiple providers.

**1. List Linked Providers**

Use the [List Providers](/api-sdk/hie-cm/care-contexts/providers/providers) API to retrieve all linked providers. This API returns a `hip_id` and the name for each linked provider.

**2. List Care Contexts for a Provider**

Using the `hip_id` obtained from the previous step, use the [List Care Contexts](/api-sdk/hie-cm/care-contexts/records/records) API to retrieve all linked care contexts for that provider.

# Linking Care Contexts

## Creating a new Care Context

Care contexts can be linked to an ABHA in various ways, depending on the document type.

## HIP Initiated Linking

Use the [Link](/api-sdk/hie-cm/care-contexts/link/hip-linking) API to create the care context. Once linked, you will receive the [`abha.link_care_context`](/docs/hie-cm/webhooks/link-care-context) webhook with the linking status.

## Upload a Medical Record

Use the [Upload](/api-sdk/health-records/obtain-authorization) API to upload a document and API will automatically create a care context.

## Discover Unlinked Care Contexts

ABDM allows a user to find their health records from any health facility they have visited via the discovery process.
[Detailed Documentation](/docs/hie-cm/care-contexts/discover/introduction)


# Changelog
Source: https://developer.eka.care/docs/hie-cm/changelog

Dated changes to the ABDM Connect API and its documentation, newest first.

**October 28, 2026**

API and AI tools changes

## Added

* **HIE-CM: 18 webhooks added.** `abha.care_context_discover`, `abha.care_context_discover_link_init`, `abha.consent_update`, `abha.context_discover_link_confirm` and 14 more.
* **NHCX: the `eka-nhcx` plugin is published.** Install it in Claude Code to give your agent this product's reference skill. [Open Build with AI](/docs/nhcx/build-with-ai).
* **UHI: the `eka-uhi` plugin is published.** Install it in Claude Code to give your agent this product's reference skill. [Open Build with AI](/docs/uhi/build-with-ai).

**October 13, 2026**

October 13, 2026

## Added

* **Journeys and workflows for every flow.** Seven journeys describe who uses ABDM Connect and why, from registering a walk-in patient to fetching records with consent. 23 workflows give the call order for each step, the fields to carry between calls, what to store, and what to do when a call fails. Start from the [Overview](/api-sdk/hie-cm/overview) or the [Quickstart](/docs/hie-cm/quickstart).
* **Webhook events in the spec.** The OpenAPI spec now describes the 18 webhook events Eka sends you, such as `abha.created` and `abha.consent_update`. See [Webhooks](/docs/hie-cm/webhooks) for when each fires and which workflow handles it.
* **Consent PIN reference pages.** Each consent PIN operation has its own page, for example [Consent pin set](/api-sdk/hie-cm/consents/pin/set) and [Consent pin reset](/api-sdk/hie-cm/consents/pin/reset).
* **ECDH reference pages.** [Ecdh keys](/api-sdk/hie-cm/care-contexts/ecdh/keys), [Ecdh encrypt](/api-sdk/hie-cm/care-contexts/ecdh/encrypt) and [Ecdh decrypt](/api-sdk/hie-cm/care-contexts/ecdh/decrypt) each have a page.

## Changed

* **Operation ids and tags.** Every operation in the spec now has an `operationId` and tags. If you generate a client from the spec, regenerate it to pick them up.
* **Order status pages.** [Order Status](/api-sdk/uhi/phys-cons/order-status) and [Get Order Status](/api-sdk/uhi/phys-cons/get-order-status) now document `POST` and `GET` `/abdm/uhi/v1/physical-consultation/booking/order-status`, the path the spec defines. They previously showed `/booking/status`. If you built against that path, switch to `/booking/order-status`.&#x20;

**March 26, 2026**

Week of March 20–26

## New features

* **ABDM milestone flows**: Structured milestone guides (M1–M4) for ABDM integration, covering ABHA creation, login, profile management, and health data exchange. [View docs](/docs/hie-cm/flows/m1)


# Overview
Source: https://developer.eka.care/docs/hie-cm/consents/getting-started



Milestone 3 covers two sides of the same flow: an HIU requesting access to a patient's health records, and the patient approving or denying that request. Once consent is approved, EKA handles all the intermediate ABDM gateway callbacks to fetch the data from the HIP.

> [!NOTE]
>
> User authorization is required for all consent operations (approve, deny, revoke).

***

## HIU: Requesting Health Data

An HIU initiates the flow by creating a consent request. The patient receives it on their PHR app and acts on it.

**1. Create a consent request**

Use the [Create Consent](/api-sdk/hie-cm/consents/consent-create) API to raise a request for a patient's health records. The request specifies the patient's ABHA address, the purpose, the date range of records needed, and the HIPs to fetch from.

**2. Patient approves the request**

The patient receives the request on their PHR app and approves it. Once approved, EKA handles all the ABDM gateway callbacks required to trigger data fetch from the HIP — no action needed on your side.

**3. Receive the health data**

Once the HIP pushes the data, it is delivered to you in one of two ways depending on how your integration is set up:

**If you manage data on your side:**
You receive the `abha.hiu_data_push` webhook with the encrypted FHIR bundle and `key_information` needed to decrypt it. Set up your HIU public keyset using the [Update Keyset](/api-sdk/hie-cm/care-contexts/hiu-keys) API — EKA shares this with the HIP so they can encrypt the data for you.

[abha.hiu\_data\_push webhook →](/docs/hie-cm/webhooks/hiu-data-push)

**If EKA stores the data:**
Call the [Retrieve Health Records](/api-sdk/health-records/retrieve-health-records) API with the `care_context_id` as the identifier. Get the `care_context_id` from the [Consent Details](/api-sdk/hie-cm/consents/consent-details) API after approval.

***

## Patient / PHR App: Managing Consent

From the patient's side, consent requests arrive and can be approved, denied, or revoked at any time.

**1. List consent requests**

Use the [List Consents](/api-sdk/hie-cm/consents/consent-list) API to fetch all pending and past consent requests for the patient.

**2. Approve a request**

Use the [Approve Consent](/api-sdk/hie-cm/consents/consent-approve) API. You need to provide the consent ID, the care contexts to share, and the HIP details.

On approval, ABDM generates consent artefacts — one per HIP involved. These artefacts authorize the HIU to fetch records from those HIPs.

**3. Deny a request**

Use the [Deny Consent](/api-sdk/hie-cm/consents/consent-deny) API with the consent ID and a reason.

**4. Revoke a granted consent**

Use the [Revoke Consent](/api-sdk/hie-cm/consents/consent-revoke) API with the consent artefact ID to revoke access for a specific HIP.

***

## Auto-Approval

For recurring or trusted access patterns, you can configure auto-approval policies so patients don't need to manually approve every request.

[Configure Auto-Approval →](/api-sdk/hie-cm/consents/auto-approval/update-auto-approval-policy)


# Overview
Source: https://developer.eka.care/docs/hie-cm/enrollment/face-auth/intro

Authenticate users via Aadhaar-based facial recognition

Face Authentication provides a secure and convenient way for users to verify their identity using Aadhaar-based facial recognition. This method allows users to authenticate themselves by scanning a QR code and completing face verification on their mobile device.

## How It Works

The Face Authentication flow consists of three sequential API calls:

**1. Initialize Face Auth**

Call the [Init API](/api-sdk/hie-cm/enrollment/face-auth/face-auth-init) to start a face authentication session. This generates a unique transaction ID and a QR code that the user scans with their mobile device.

**2. Poll for Status**

Use the [Capture API](/api-sdk/hie-cm/enrollment/face-auth/face-auth-capture) to poll the authentication status. Continue polling until the status changes from `Pending` to `Verified`. This indicates the user has successfully completed face verification on their device.

**3. Retrieve User Information**

Once verified, call the [Verify API](/api-sdk/hie-cm/enrollment/face-auth/face-auth-verify) with the user's Aadhaar number to fetch the authenticated user's demographic information. This includes details like name, date of birth, gender, and address.

## Flow Diagram

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant User
    participant ABDM

    Client->>API: POST /face-auth/init
    API-->>Client: Transaction ID + QR Code
    Client->>User: Display QR Code
    User->>ABDM: Scan QR & Complete Face Auth

    loop Poll until verified
        Client->>API: POST /face-auth/capture (Transaction ID)
        API-->>Client: Status (Pending/Verified)
    end

    Client->>API: POST /face-auth/verify (Transaction ID + Aadhaar)
    API-->>Client: User Information
    Client->>Client: Proceed to ABHA Creation
```

> **[Init API](/api-sdk/hie-cm/enrollment/face-auth/face-auth-init)**
>
> Start a face authentication session

> **[Capture API](/api-sdk/hie-cm/enrollment/face-auth/face-auth-capture)**
>
> Poll authentication status

> **[Verify API](/api-sdk/hie-cm/enrollment/face-auth/face-auth-verify)**
>
> Retrieve verified user information

## Next Steps

After successfully retrieving user information through face authentication, users can proceed to create their ABHA address using the verified demographic details.


# Error Code Mapping
Source: https://developer.eka.care/docs/hie-cm/errors



Error Code would match with the http status code in most cases.
4XX indicates a user error and 5XX indicates a server side error.

## By symptom

Start here when you know what you see but not which code it is. Each symptom lists the likely causes, what to check, the codes involved and the workflow step it belongs to.&#x20;

### OTP never arrives

Belongs to: the Generate OTP step of [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp), [Create an ABHA address with mobile OTP](/docs/hie-cm/workflows/create-abha-mobile-otp) and [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha).

| Likely cause | What to check | Codes |
| - | - | - |
| The patient is checking the wrong phone. The Aadhaar OTP goes to the mobile linked to the Aadhaar, not the `mobile` you send. | Show the patient the masked number in `hint` from the init response. | none |
| The OTP is delayed or lost. | Call the workflow's resend operation with the current `txn_id`, then use the `txn_id` it returns. | none |
| Too many OTP requests in this transaction. | Tell the patient to try again in 30 minutes, then start again from Generate OTP. | `ABDM-1100` |
| ABDM's SMS gateway is unavailable. | Retry later. | `ABDM-1004` |
| In [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link), your HIP sends this OTP itself. | Check your own SMS sending. | none |

### The patient is locked out after entering OTPs

Belongs to: the Verify OTP step of every ABHA creation, login and gateway session workflow.

| Likely cause | What to check | Codes |
| - | - | - |
| The OTP is wrong. | Ask the patient to re-enter it. | `MIS-1013`, `ABDM-1035` (OTP does not match, in [Discover and link records from a facility](/docs/hie-cm/workflows/phr-discover-and-link)) |
| Too many wrong attempts or OTP requests. | Tell the patient to try again in 30 minutes. | `ABDM-1100` |
| The patient is blocked. | Tell the patient to try again after 24 hours. | `ABDM-1027` |
| The transaction expired. | Start again from Generate OTP. | `ABDM-1017`, `MIS-1026` |

### Every call returns 401

Belongs to: every call. See [Authorization](/api-sdk/auth/getting-started).

| Likely cause | What to check | Codes |
| - | - | - |
| Your access token has expired. | Get a new token with [Refresh token](/api-sdk/auth/refresh-token-v2) and retry. | HTTP `401` |
| The token is missing from the request. | Send it as a Bearer token on every call. | HTTP `401` |

### Patient calls return 491

Belongs to: [Hold the ABHA Gateway session](/docs/hie-cm/workflows/hold-gateway-session), and every patient-scoped call in the PHR workflows, such as [Approve, deny or revoke a consent in a PHR app](/docs/hie-cm/workflows/phr-act-on-consent) and [Manage the ABHA profile and KYC](/docs/hie-cm/workflows/manage-profile-and-kyc).

| Likely cause | What to check | Codes |
| - | - | - |
| The patient's ABHA Gateway session has expired. | Run Session Init and Session Verify with a mobile OTP, then retry the call. See [User Session](/docs/hie-cm/session/getting-started). | HTTP `491` |
| You called Session Status without the patient's id. | Send the patient's `oid` in `X-Pt-Id`. | not documented |

### A webhook never arrives

Belongs to: every workflow that waits on an event. See [Webhooks](/docs/hie-cm/webhooks).

| Likely cause | What to check | Codes |
| - | - | - |
| Your endpoint is not registered with Eka, or is not reachable. | Check the registration with [Get webhooks](/api-sdk/webhooks/get-webhooks). Check the URL is public, uses HTTPS, and allows Eka's IP addresses. | none |
| Your endpoint does not reply `200` within 5 seconds. | Reply first, then process. Eka retries on any other status. | none |
| Your signature check rejects the event. | Compare your check with [Webhook signature](/docs/webhooks/webhook-signature). | none |
| The event is not sent in your setup. `abha.hip_data_fetch` is sent only if you keep the health data yourself. `abha.hiu_data_push` is sent only if you manage the data on your side; if Eka stores it, read the records instead. | Check whether Eka stores the data for you. | none |
| For `abha.hiu_data_push`: your public keyset is not registered. | Register it as in [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent). | none |
| For UHI events: the result is late. | Read the result with the matching `GET`, as in [Book a physical consultation over UHI](/docs/uhi/workflows/uhi-book-consultation). | none |

When `abha.created` does not arrive, use the Create response to proceed.&#x20;

### A consent request never moves on

Belongs to: the wait-for-status step of [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent).

| Likely cause | What to check | Codes |
| - | - | - |
| The patient has not acted on the request yet. | The patient approves or denies it in their PHR app. | none |
| `abha.consent_update` is not reaching you. | Check your webhook registration and signature check, then read the status from [Consent List](/api-sdk/hie-cm/consents/consent-list). | none |
| The request expired before the patient acted. | Raise a new consent request; do not retry the old one. | `ABDM-1061` |
| The patient denied the request. | Close the request on your side. | `ABDM-1062` |

### Records do not decrypt

Belongs to: the decrypt step of [Receive and decrypt records as a HIU](/docs/hie-cm/workflows/hiu-receive-data), and the encrypt step of [Serve records on a fetch request](/docs/hie-cm/workflows/serve-data-on-fetch).

| Likely cause | What to check | Codes |
| - | - | - |
| As a HIU: you used a different key pair from the one registered for this consent. | Use the `private_key` and `nonce` registered at the time of the consent. Report the entry with `success` `false`. | none |
| As a HIU: a field sent to Ecdh decrypt is not the Base64 value you received. | Send each field exactly as it came in the webhook or your store. | `ABDM-1006`, `ABDM-1010` |
| As a HIP: you encrypted with the wrong receiver key or nonce. | Take the receiver key and nonce from `key_information` in this `abha.hip_data_fetch` event. | not documented |

### A care context link reports ERRORED

Belongs to: the wait-for-status step of [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip).

| Likely cause | What to check | Codes |
| - | - | - |
| ABDM rejected the link. | Read `data.error` in `abha.link_care_context`. Correct the request and link again. | `data.status` `ERRORED` |
| The ABHA address or number is not recognised. | Check the `abha_address` saved on the patient record. | `ABDM-1051` |
| The HIP ID is wrong. | Check the `X-Hip-Id` header against your onboarded HIP ID. | `ABDM-1035` (Invalid HIP ID) |
| The gateway or a dependent service is down. | Retry later. | `ABDM-1019`, `ABDM-1024`, `ABDM-1048` |

## By code

| code | message | abdm-code | abdm-message |
| - | - | - | - |
| 500 | Something went wrong | ABDM-1000 | Unable to connect the database |
| 500 | No data found | ABDM-1001 | No data found |
| 500 | Something went wrong | ABDM-1002 | Integrity violation |
| 500 | Something went wrong | ABDM-1003 | Email Gateway is unavailable |
| 500 | Something went wrong | ABDM-1004 | SMS Gateway is unavailable |
| 500 | Something went wrong | ABDM-1005 | Invalid receiver |
| 400 | Bad Request, invalid request | ABDM-1006 | Bad Request, invalid request Body |
| 500 | Something went wrong | ABDM-1007 | Connection failed due to timeout |
| 500 | Something went wrong | ABDM-1008 | SMS service currently disabled |
| 500 | Something went wrong | ABDM-1009 | Email service currently disabled |
| 400 | Validation failed | ABDM-1010 | Validation failed |
| 500 | Something went wrong | ABDM-1011 | Gateway database unavailable |
| 400 | No records found against the ABHA Address | ABDM-1012 | No records found against the ABHA Address |
| 400 | Invalid ABHA Number | ABDM-1013 | Invalid ABHA Number |
| 400 | Invalid Mobile Email | ABDM-1014 | Invalid Mobile Email |
| 500 | Something went wrong | ABDM-1015 | Invalid Response |
| 500 | Something went wrong | ABDM-1016 | Invalid TimeStamp |
| 500 | Something went wrong | ABDM-1017 | Invalid TransactionId |
| 500 | Unable to share the details with Hospital | ABDM-1018 | Share Profile database unavailable |
| 500 | Something went wrong | ABDM-1019 | Dependent Service Unavailable |
| 500 | Something went wrong | ABDM-1020 | Unknown database |
| 500 | Something went wrong | ABDM-1021 | ABDM-1021 |
| 500 | Too many requests | ABDM-1022 | Too many requests |
| 500 | Something went wrong | ABDM-1023 | Invalid User |
| 500 | Something went wrong | ABDM-1024 | Dependent service unavailable |
| 500 | Something went wrong | ABDM-1025 | Invalid ServiceId |
| 500 | Something went wrong | ABDM-1026 | Invalid Link Token |
| 500 | You are blocked. Please try again after 24 hours. | ABDM-1027 | You are blocked. Please try again after 24 hours. |
| 500 | Something went wrong | ABDM-1028 | HIP is unavailable |
| 500 | Something went wrong | ABDM-1029 | Redis server is unavailable |
| 400 | Something went wrong | ABDM-1030 | Invalid request ID |
| 400 | Something went wrong | ABDM-1031 | Invalid request |
| 400 | Something went wrong | ABDM-1032 | Invalid header |
| 500 | Something went wrong | ABDM-1033 | HIU is unavailable |
| 500 | Something went wrong | ABDM-1034 | Notification service unavailable |
| 500 | Something went wrong | ABDM-1035 | Invalid HIP ID |
| 400 | OTP doesn't match | ABDM-1035 | OTP does not matched |
| 500 | Something went wrong | ABDM-1036 | Data does not matched |
| 500 | Something went wrong | ABDM-1037 | Counter and Care context count mismatch |
| 500 | Something went wrong | ABDM-1038 | ABHA address and Link token mismatch |
| 500 | Something went wrong | ABDM-1039 | Invalid Consent request id |
| 500 | Something went wrong | ABDM-1040 | Invalid HIU ID |
| 500 | Something went wrong | ABDM-1041 | Invalid Acknowledgement |
| 400 | Invalid request | ABDM-1042 | Provider Mandatory |
| 500 | Something went wrong | ABDM-1043 | ABHA Address does not match with KYC details. |
| 500 | Something went wrong | ABDM-1044 | Broadcast Failed |
| 500 | Something went wrong | ABDM-1045 | Database Access is restricted |
| 500 | Something went wrong | ABDM-1046 | Invalid Purpose |
| 500 | Something went wrong | ABDM-1047 | Purpose does not exist |
| 500 | Something went wrong | ABDM-1048 | Timeout |
| 500 | Something went wrong | ABDM-1049 | Invalid Profile Share Intent Keys |
| 500 | Something went wrong | ABDM-1050 | Invalid Profile Share Metadata Keys |
| 500 | Something went wrong | ABDM-1051 | Invalid ABHA Number or ABHA Address |
| 500 | Something went wrong | ABDM-1052 | Invalid TransactionId or response's requestId |
| 500 | Something went wrong | ABDM-1053 | Data already exists |
| 500 | Something went wrong | ABDM-1054 | Invalid Subscription Request Id |
| 500 | Something went wrong | ABDM-1401 | HIP is not available |
| 500 | Something went wrong | ABDM-1402 | Acknowledgement is not received from HIP |
| 500 | Something went wrong | ABDM-9999 | Unknown exception |
| 400 | Consent artefact expired | ABDM-1061 | Consent artefact expired |
| 400 | Consent Not granted | ABDM-1062 | Consent Not granted |
| 400 | Date Range given is invalid | ABDM-1063 | Date Range given is invalid |
| 400 | Something went wrong | ABDM-1064 | request with this request id already exists |
| 500 | Something went wrong | ABDM-1109 | ABHA DB service unavailable |
| 500 | Something went wrong | ABDM-1108 | Notification DB service unavailable |
| 500 | Something went wrong | ABDM-1205 | Document DB Gateway is unavailable |
| 500 | Something went wrong | ABDM-1202 | Document Gateway is unavailable |
| 500 | Something went wrong | ABDM-1200 | LGD Gateway is unavailable |
| 500 | Something went wrong | ABDM-1201 | IDP Gateway is unavailable |
| 500 | Something went wrong | ABDM-1101 | This ABHA Address already exists. Please create with unique ABHA Address |
| 500 | Something went wrong | ABDM-1006 | Invalid combinations of scopes |
| 500 | Something went wrong | ABDM-1100 | You have requested multiple OTPs Or Exceeded maximum number of attempts for OTP match in this transaction. Please try again in 30 minutes. |
| 500 | ABHA User not found. | ABDM-1110 | ABHA User not found. |
| 400 | Mobile number not found. | ABDM-1111 | Mobile number not found. |
| 400 | Aadhaar details not found. | ABDM-1112 | Aadhaar details not found. |
| 400 | Login via Password is not allowed | ABDM-1113 | Login via Password is not allowed |
| 400 | Login via ABHA Number OTP is not allowed | ABDM-1114 | Login via ABHA Number OTP is not allowed |
| 400 | Login via Aadhaar OTP is not allowed | ABDM-1115 | Login via Aadhaar OTP is not allowed |
| 400 | Mobile number verification is pending. | ABDM-1102 | Mobile number verification is pending. |
| 400 | The OTP that you have entered is incorrect. Please try again. | MIS-1013 | OTP(One Time Password) is invalid, Please enter the correct OTP. |
| 500 | Transaction not found for UUID. | MIS-1026 | Transaction is not found for UUID. |
| 400 | This account has already been claimed by the mobile number: `mobile_number` | EKA-1001 | This account has already been claimed by the mobile number: `mobile_number` |
| 400 | This mobile number has already been claimed by another account. | EKA-1002 | Mobile number `mobile_number` has already been claimed by another account. |


# Milestone 1
Source: https://developer.eka.care/docs/hie-cm/flows/m1

ABHA Creation and Login flows for ABDM integration.

> **Note:** All flows require Authorization from the [Session API](/api-sdk/auth/client-login). The `oid` obtained can be reused across other flows.

***

## Create ABHA

Three methods to create an ABHA account. Each flow runs independently.

### Via Aadhaar OTP

```mermaid theme={null}
flowchart LR
  A["Generate OTP"] --> AR["Resend OTP"]
  A --> B["Verify OTP"]
  B --> C{"Mobile linked with Aadhaar?"}
  C -->|Yes| D["Create ABHA"]
  C -->|No| E["Mobile Verify OTP"]
  E --> ER["Mobile Resend OTP"]
  E --> F["Create ABHA"]
```

### Via Face Auth

```mermaid theme={null}
flowchart LR
  A["Face Auth Init"] --> B["Capture Face"]
  B -.->|async| P["Polling API"]
  B --> C["Verify"]
  C --> D{"Mobile linked with Aadhaar?"}
  D -->|Yes| E["Create ABHA"]
  D -->|No| F["Mobile Verify OTP"]
  F --> FR["Mobile Resend OTP"]
  F --> G["Create ABHA"]
```

### Via Mobile OTP

```mermaid theme={null}
flowchart LR
  A["Generate OTP"] --> AR["Resend OTP"]
  A --> B["Verify OTP"]
  B --> C["Create ABHA"]
```

***

## Login ABHA

Three methods to login. All methods resolve to `skip_state = abha_end` on success.

> [!NOTE]
>
> The `oid` from login can be reused in other downstream flows.

### Via PHR Address

```mermaid theme={null}
flowchart LR
  A["Generate OTP"] --> B["Verify OTP"]
  B --> C["skip_state = abha_end"]
```

### Via Aadhaar

```mermaid theme={null}
flowchart LR
  A["Generate OTP"] --> B["Verify OTP"]
  B --> C["skip_state = abha_create"]
  C --> D["Auto-Login API"]
  D --> E["skip_state = abha_end"]
```

### Via Mobile

```mermaid theme={null}
flowchart LR
  A["Generate OTP"] --> B["Verify OTP"]
  B --> C["PHR Login API"]
  C --> D["skip_state = abha_end"]
```

> [!NOTE]
>
> If `skip_state = abha_create` and `len(abha_profiles) > 0`, the client can use the **Auto-Login API** to log into an existing ABHA from `abha_profiles` directly.


# Milestone 2
Source: https://developer.eka.care/docs/hie-cm/flows/m2

Care Context Linking and Data Fetch flow for ABDM integration.

## M2 Flow — Care Context Linking

```mermaid theme={null}
flowchart TD
  A{"Data stored by Eka Care?"}

  A -->|Yes| B(["Include data in Linking API"])
  A -->|No| C(["Don't include data in Linking API"])

  B --> D["Care Context Linking"]
  C --> D

  D --> E["Care Context Linking Status  ― Webhook"]

  E --> F{"Data stored by Eka Care?"}

  F -->|No| H["Handle Data Fetch Requests ― Webhook"]

  H --> I["Push care context data to HIU"]
```

> [!NOTE]
>
> Steps marked \*\* Webhook\*\* are asynchronous — your server will receive a callback at the registered webhook URL. You do not need to poll for status.

| Step | Type | Description |
| - | - | - |
| Care Context Linking Status | Webhook | Notifies when linking succeeds or fails |
| Handle Data Fetch Requests | Webhook | Triggered when HIU requests data not stored by Eka Care |


# Milestone 3
Source: https://developer.eka.care/docs/hie-cm/flows/m3

Consent management and health data retrieval flow for ABDM integration.

## M3 Flow — Consent & Health Data Retrieval

### HIU — Consent Management

```mermaid theme={null}
flowchart LR
  A["Create Consent"] --> B["Consent List"]
  B --> C["Consent Details"]
```

### PHR — Consent Actions

```mermaid theme={null}
flowchart LR
  A["Consent Approve"] --> B["Consent Deny"]
  B --> C["Consent Revoke"]
```

> [!NOTE]
>
> **Consent Approve** is triggered after the HIU creates a consent request. The PHR user can approve, deny, or later revoke the consent.

### Data Retrieval

```mermaid theme={null}
flowchart TD
  A["Consent Approve"]
  A --> B{"Data stored by Eka Care?"}

  B -->|Yes| C["Retrieve Health Records"]
  B -->|No| D["Health Data Received from HIP ― Webhook"]
```

> [!NOTE]
>
> If data is **not** stored by Eka Care, the system waits for the HIP to push data. Your server will receive this via the \*\* Health Data Received from HIP\*\* webhook.

| Step | Type | Description |
| - | - | - |
| Health Data Received from HIP | Webhook | Triggered when HIP pushes health records after consent approval |


# Milestone 4
Source: https://developer.eka.care/docs/hie-cm/flows/m4

Healthcare Professional Registry (HPR), Health Facility Registry (HFR), and Onboarding flows for ABDM integration.

## M4 Flow — Registries & Onboarding

***

## 1. Healthcare Professional Registry (HPR)

### Via Aadhaar Authentication

```mermaid theme={null}
flowchart LR
  A["Get Aadhaar OTP"] --> B["Verify Aadhaar OTP"]
  B --> C["Verify Mobile"]
```

### HPR ID Creation

```mermaid theme={null}
flowchart LR
  A["Get HPR Info"] --> B{"HPR ID exists?"}
  B -->|Yes| E["Done — Skip creation"]
  B -->|No| C["Suggest IDs"]
  C --> D["Create HPR"]
```

### Mobile Login *(alternative entry)*

```mermaid theme={null}
flowchart LR
  A["Get Mobile OTP"] --> B["Verify Mobile OTP"]
  B --> C["Check If HPR is Available"]
```

> [!NOTE]
>
> Use **Get Aadhaar OTP → Verify → Verify Mobile** for first-time registration. Use **Get Mobile OTP → Verify Mobile OTP** for returning professionals logging in via mobile.

***

## 2. Health Facility Registry (HFR)

```mermaid theme={null}
flowchart LR
  A["Search HFR"] --> B{"Facility exists?"}
  B -->|Yes| D["Link HFR"]
  B -->|No| C["Onboard HFR"]
  C --> D
```

> [!NOTE]
>
> Always **Search HFR** first. If the facility already exists in the ABDM registry, skip onboarding and go directly to **Link HFR**.

***

## 3. Onboarding to Eka

```mermaid theme={null}
flowchart LR
  A["Create HPR ID on ABDM portal"] --> B["Register Facility HFR ID"]
  B --> C["Software Linkage via Eka Bridge ID"]
  C --> D["Onboard to Eka"]
```

> [!NOTE]
>
> This is a **one-time setup** flow. Once the HPR ID and HFR ID are created and registered on the ABDM portal, use the **Software Linkage** step from the facility dashboard to connect via the Eka Bridge ID, then call the Onboard API to complete integration.


# Glossary
Source: https://developer.eka.care/docs/hie-cm/glossary

The terms used in the ABDM Connect docs, what each one means, and the page where you meet it.

The terms you meet in the ABDM Connect docs. Follow the link in the last column to see a term in context.

## Ecosystem and roles

| Term | What it means | Where it is used |
| - | - | - |
| ABDM | Ayushman Bharat Digital Mission, India's national digital health infrastructure. Patients, hospitals, labs, insurers and health apps exchange health data through it, with the patient's consent driving every exchange. | [ABDM overview](/docs/hie-cm/about) |
| ABDM Connect | Eka's REST API over the ABDM gateway. You call Eka, and Eka handles ABDM's gateway protocol, encryption and callbacks for you. | [ABDM Connect overview](/api-sdk/hie-cm/overview) |
| CARE | How these docs name the four ABDM milestones: Create (M1, the patient's ABHA), Attach (M2, records to the ABHA), Retrieve (M3, records with consent), Enrol (M4, doctors and facilities in HPR and HFR). | [What is ABDM Connect](/docs/hie-cm/about#care-the-four-milestones) |
| HIE-CM | The ABDM family that covers ABHA, care contexts, consent and records. Its specification also sets the ECDH scheme used to encrypt records in transit. | [Encryption](/docs/hie-cm/care-contexts/ecdh-encryption) |
| Consent Manager | The ABDM registry that manages consent between the parties that hold data and the parties that want it. The ABDM gateway itself acts as the Consent Manager. | [ABDM overview](/docs/hie-cm/about#core-registries) |
| HIP | Health Information Provider. A hospital, lab, clinic or pharmacy that holds patient records and links them to the patient's ABHA address so they can be found and shared. | [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip) |
| HIU | Health Information User. Any party, such as an insurer or referral system, that requests a patient's records with consent and receives them from the HIPs. | [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent) |
| PHR app | A personal health record app, the patient-facing side of ABDM. It usually acts as both a HIP for records the patient uploads and a HIU for records it fetches. | [Gather every health record in a PHR app](/docs/hie-cm/journeys/phr-patient-aggregates-records) |
| Milestone | One of the four stages, M1 to M4, in which ABDM certifies hospital and lab software. They cover identity, linking, consent and registries. | [ABDM overview](/docs/hie-cm/about#abdm-milestones) |
| HPR | Healthcare Professionals Registry. Each doctor, nurse or practitioner on it gets a unique HPR ID as a verified digital identity. | [Create an HPR ID with Aadhaar OTP](/docs/hie-cm/workflows/create-hpr-id) |
| HFR | Health Facility Registry. Each government or private facility on it gets a unique HFR ID, used for record linking and patient discovery. | [Register and onboard a facility](/docs/hie-cm/workflows/register-hfr) |

## Patient identity

| Term | What it means | Where it is used |
| - | - | - |
| ABHA | Ayushman Bharat Health Account, the patient's health identity. Every health transaction in ABDM is anchored to it. It takes the form of an ABHA number or an ABHA address. | [ABDM overview](/docs/hie-cm/about#core-registries) |
| ABHA number | The 14-digit, KYC-verified form of an ABHA. You create one from an Aadhaar OTP, with Aadhaar as the KYC. | [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp) |
| ABHA address | The patient's ABHA handle, such as `shyam@abdm`. A HIP links records to it. You can create one without KYC from a mobile OTP. | [Create an ABHA address with mobile OTP](/docs/hie-cm/workflows/create-abha-mobile-otp) |
| ABHA Gateway session | The patient's session with the ABHA Gateway, separate from your client token. Creating or registering an ABHA opens it, and patient-scoped calls without a live session return HTTP `491`. | [Hold the ABHA Gateway session](/docs/hie-cm/workflows/hold-gateway-session) |
| Scan & Share | The patient scans your facility's QR code with a PHR app to share their ABHA profile. Eka sends you the profile on a webhook, and you reply with an OPD token. | [Receive a scanned profile as a HIP](/docs/hie-cm/workflows/hip-scan-and-share) |

## Records and consent

| Term | What it means | Where it is used |
| - | - | - |
| Care context | A visit, test or admission at your facility, linked to the patient's ABHA address. Once linked, it is registered with ABDM, and any HIU the patient consents to can request it. | [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip) |
| Linking | Registering a care context under the patient's ABHA. You link new records yourself; the patient links older records through discovery. Linking returns `202 Accepted` and confirms on the `abha.link_care_context` webhook. | [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip) |
| Discovery | A patient searches your facility from a PHR app for records that were never linked to their ABHA. You answer three webhooks: return the matches, send an OTP, then confirm the link. | [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link) |
| FHIR bundle | The record format a HIP sends for a care context. If Eka stores your data, you send it base64-encoded in the `data` field when you link. Otherwise you build and encrypt it on each fetch request. | [Serve records on a fetch request](/docs/hie-cm/workflows/serve-data-on-fetch) |
| HI type | Health information type, the kind of record in a care context, for example `OPConsultation` or `Prescription`. You send it as `hi_type` when you link, and a fetch request lists the `hi_types` the HIU wants. | [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip) |
| Consent request | A HIU's request for a patient's records. It appears in the patient's PHR app, where they approve or deny it, and its status changes arrive on the `abha.consent_update` webhook. | [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent) |
| Consent artefact | The record ABDM generates when a patient approves a consent request, one per HIP. An expired artefact returns `ABDM-1061`, and you raise a new consent. | [Approve, deny or revoke a consent in a PHR app](/docs/hie-cm/workflows/phr-act-on-consent) |
| Consent PIN | The PIN a patient sets in a PHR app and verifies when they approve, deny or revoke a consent. | [Approve, deny or revoke a consent in a PHR app](/docs/hie-cm/workflows/phr-act-on-consent) |
| Auto-approval | A policy that lets the patient authorise a class of consent requests once, instead of approving each one. | [Set up the patient's health locker](/docs/hie-cm/workflows/set-up-health-locker) |
| Health locker | Storage the patient controls for their own records. When auto-approval is on, your PHR app is the locker, and Eka tells it each time a HIP links a new record. | [Set up the patient's health locker](/docs/hie-cm/workflows/set-up-health-locker) |
| Subscription | The standing arrangement Eka sets up with auto-approval. It sends `abha.subscription_notify` when a provider links a new record for the patient, and `abha.subscription_modified` when it changes. | [Set up the patient's health locker](/docs/hie-cm/workflows/set-up-health-locker) |
| ECDH | The encryption scheme for records sent between HIPs and HIUs: ECDH key agreement on Curve25519, with HKDF-SHA256 and AES-256-GCM. If Eka stores your records, Eka encrypts and decrypts them for you. | [Encryption](/docs/hie-cm/care-contexts/ecdh-encryption) |

## Identifiers and fields

| Term | What it means | Where it is used |
| - | - | - |
| OID (Eka user ID) | Eka's ID for a patient, returned as `eka.oid` when an ABHA is created or the patient logs in. You send it in the `X-Pt-Id` header or the `oid` query parameter on later calls. | [ABDM Connect overview](/api-sdk/hie-cm/overview#common-headers) |
| Partner patient ID | Your own ID for the patient, sent in the `X-Partner-Pt-Id` header. | [ABDM Connect overview](/api-sdk/hie-cm/overview#common-headers) |
| HIP ID | The ID of the facility a call is made from, sent in the `X-Hip-Id` header. On NHCX calls it selects the facility that raises the claim. | [ABDM Connect overview](/api-sdk/hie-cm/overview#common-headers) |
| `txn_id` | The transaction ID that the first call of an OTP or linking flow returns. You send it back on every later step of that flow. | [ABDM Connect overview](/api-sdk/hie-cm/overview#multi-step-flows) |
| `skip_state` | A field in the Aadhaar OTP verify response that tells you the next call. Its values are `confirm_mobile_otp`, `abha_create` and `abha_select`. | [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp) |
| `source_error` | The part of an ABDM Connect error body that carries ABDM's own code when the gateway refuses a call, such as `ABDM-1010`. | [Errors](/docs/hie-cm/errors) |

For terms from every Eka product, see the [Eka glossary](/docs/get-started/glossary).


# Onboard a facility and its professionals to ABDM
Source: https://developer.eka.care/docs/hie-cm/journeys/facility-onboard-to-abdm

A facility admin or HMS vendor registers the clinic's doctors in HPR, registers the clinic in HFR, and onboards the clinic to Eka so it can act as a HIP.

## In short

* Register each professional in HPR, then the clinic in HFR, then onboard the clinic to Eka.
* It is a one-time setup per facility, plus one HPR registration per professional.
* At least one registered professional is needed before the facility can be registered.
* Onboarding returns the HIP ID your HMS uses from then on.
* Every patient-facing journey starts only after this one has finished.

## Who and when

A facility admin at a clinic, or the HMS vendor setting the clinic up, who wants the clinic to take part in ABDM through Eka. The clinic is about to go live on an HMS integrated with ABDM Connect. No patient visit can be linked or shared until two things are true. Its doctors have Healthcare Professional Registry (HPR) IDs, and the clinic has a Health Facility Registry (HFR) ID onboarded on Eka. This is a one-time setup per facility, plus one HPR registration per professional.

**Already in place:** nothing on ABDM. You need Eka API credentials for your HMS ([Authorization](/api-sdk/auth/getting-started)), the professionals' Aadhaar numbers and the mobiles linked to them, and the facility's details. Every patient-facing journey, such as [Register a walk-in patient and link the visit](/docs/hie-cm/journeys/hip-register-patient-and-link-visit), starts only after this one has finished.

## What they want

"Get our doctors and our clinic registered with ABDM once, correctly, so we can start linking patient records from the next OPD."

## The steps

1. The admin lists the professionals who practise at the clinic. At least one registered professional is needed before the facility can be registered.
2. Each professional who has no HPR ID creates one from inside the HMS. They give their Aadhaar number and read out the OTP sent to the mobile linked to it. The HMS checks that the mobile they give matches Aadhaar and whether an HPR ID already exists. If none exists, it offers suggested IDs to choose from. → workflow: [Create an HPR ID with Aadhaar OTP](/docs/hie-cm/workflows/create-hpr-id)
3. The HMS saves each professional's HPR ID on their staff record.
4. The admin searches the registry for the facility by its HFR ID. If the facility is not there, the HMS registers it. The HMS then links the facility to the Eka Bridge and onboards it to Eka. Eka returns the HIP ID the HMS uses from then on. → workflow: [Register and onboard a facility](/docs/hie-cm/workflows/register-hfr)
5. The admin confirms the facility shows as onboarded and switches on ABDM features for front-desk staff.

## What they have at the end

Every professional at the clinic has an HPR ID, held on their staff record in the HMS. The facility has an HFR ID, is linked to the Eka Bridge, and is onboarded on Eka as a Health Information Provider (HIP). The HMS holds the facility's HIP ID and its Scan and Share URL. Front-desk staff can now register patients and link visits.

## Branches

* **The professional already has an HPR ID.** The existence check returns it and creation is skipped; the HMS saves the existing ID. → same workflow, existing-ID branch of [Create an HPR ID with Aadhaar OTP](/docs/hie-cm/workflows/create-hpr-id)
* **The mobile the professional gives does not match Aadhaar.** The verification step fails and the professional cannot continue with that mobile. → same workflow, mobile verification step
* **A returning professional signs in with their mobile instead of Aadhaar.** They receive an OTP on their mobile and the HMS checks their HPR ID. → workflow: [Log in to HPR with a mobile OTP](/docs/hie-cm/workflows/hpr-mobile-login)
* **The facility is already in HFR.** The search finds it, so the HMS skips registration and goes straight to linking and onboarding. → same workflow, existing-facility branch of [Register and onboard a facility](/docs/hie-cm/workflows/register-hfr)
* **The facility was registered on the ABDM portal by hand.** The admin registered the HPR ID and HFR ID on the [ABDM portal](https://nhpr.abdm.gov.in/nhpr/v4/login) and waited for approval. They then entered the Eka Bridge ID under Software Linkage there. The HMS only needs the final onboarding step. → same workflow, last step of [Register and onboard a facility](/docs/hie-cm/workflows/register-hfr)
* **The HFR registration is waiting for approval.** On the portal route the HFR ID arrives only after approval. Onboarding to Eka waits until then.&#x20;


# Let a patient claim their old records
Source: https://developer.eka.care/docs/hie-cm/journeys/hip-answer-discovery

A patient finds the records your facility holds for them from a PHR app and links them to their ABHA, while your HMS answers each request.

## In short

* Your HMS answers each request from a patient's PHR app on its own, through Eka.
* It searches its records with the patient's verified details and returns what is not yet linked.
* The patient picks records and confirms them with an OTP your HMS sends by SMS.
* On a matching OTP, ABDM registers the records under the patient's ABHA.

## Who and when

A patient who visited your clinic or hospital in the past, before their visits were linked to an ABHA. They now have an ABHA and use an ABDM PHR app, such as the ABHA app, to gather their health records in one place. They pick your facility in the app and ask it for their records. Nobody at your facility is involved: your HMS, acting as a Health Information Provider (HIP), answers every request on its own, through Eka.

**Already in place:** your software acts as a HIP, with the setup from [Register a walk-in patient and link the visit](/docs/hie-cm/journeys/hip-register-patient-and-link-visit). The facility has a HIP ID and is onboarded on Eka (see [Onboard a facility and its professionals to ABDM](/docs/hie-cm/journeys/facility-onboard-to-abdm)). Your server can receive Eka webhooks. Your HMS holds past visits, prescriptions or reports for patients, with at least their name, gender, year of birth and mobile number.

## What they want

"Find the records this hospital has for me and add them to my ABHA, so I can show them to my next doctor."

## The steps

1. The patient opens their PHR app, chooses your facility and asks for their records. ABDM sends the request to Eka, which passes it to your HMS. The request carries the patient's verified ABHA address, name, gender, year of birth and mobile number.
2. Your HMS searches its patient records with those details. It answers with the visits and documents that belong to this patient and are not yet linked. → workflow: [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link)
3. The PHR app lists what your facility found. The patient picks the records they want to link. This is a human action in the app.
4. Your HMS sends a one-time password (OTP) by SMS to the patient's registered mobile number and tells ABDM it has done so. → workflow: [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link)
5. The patient reads the OTP from their SMS and types it into the PHR app. This is a human action.
6. Your HMS checks the OTP against the one it sent. If it matches, it confirms the link, and ABDM registers the records under the patient's ABHA. Your HMS marks them as linked. → workflow: [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link)

## What they have at the end

The patient sees your facility's past records in their PHR app, linked to their ABHA. They can share them, with consent, with any Health Information User (HIU) such as another doctor or an insurer. Your HMS holds those records marked as linked, so it leaves them out of the next discovery answer. If your HMS chose to, it also holds the patient's verified ABHA address on their record, so new visits can be linked straight away.

## Branches

* **Your HMS finds no matching patient.** It answers the discovery with an error, and the PHR app tells the patient nothing was found. → same workflow, no-match branch of [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link)
* **The patient enters a wrong or expired OTP.** Your HMS answers the confirmation with an error and links nothing. → same workflow, OTP branch
* **Your HMS saves the patient's ABHA address on a match.** Future visits for this patient are linked directly after each visit, with no discovery needed. → workflow: [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip)
* **An HIU later asks for the linked records and your HMS keeps the data itself.** Eka asks your HMS for the records on a webhook, and your HMS serves them encrypted. → workflow: [Serve records on a fetch request](/docs/hie-cm/workflows/serve-data-on-fetch)
* **All of the patient's records are already linked.** There is nothing unlinked to return, so your HMS answers as for no match.  → same workflow, no-match branch


# Register a walk-in patient and link the visit
Source: https://developer.eka.care/docs/hie-cm/journeys/hip-register-patient-and-link-visit

A clinic receptionist finds or creates the patient's ABHA at the front desk, and the visit is linked to it as a care context.

## In short

* The receptionist logs the patient in to their ABHA, or creates one, with an OTP.
* The HMS saves the ABHA number, ABHA address and `oid` on the patient record.
* After the visit, the HMS links it to the ABHA as a care context.
* Confirmation of the link arrives on a webhook.

## Who and when

A receptionist at a clinic or hospital whose HMS is integrated with Eka as a Health Information Provider (HIP). A patient walks in for an OPD visit. They have no ABHA, do not know whether they have one, or have one but have never used it on this system. The clinic wants every visit linked to the patient's ABHA so the records can be found and shared later, with the patient's consent.

**Already in place:** your software acts as a HIP. The facility has a HIP ID and is onboarded on Eka ([Onboard a facility to ABDM](/docs/hie-cm/journeys/facility-onboard-to-abdm)), and your server can receive Eka webhooks.

## What they want

"Get this patient an ABHA, or find the one they already have, register today's visit against it, and don't hold up the queue."

## The steps

1. The receptionist asks whether the patient has an ABHA and what they can offer as identity: an ABHA address, their Aadhaar, or a mobile number. Most walk-ins do not know whether they have one.
2. If the patient has an ABHA, the receptionist logs them in with an OTP to the patient's mobile. → workflow: [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha)
3. If not, the receptionist creates one. With Aadhaar and its linked mobile, the patient reads out the OTP and gets a KYC-verified 14-digit ABHA number. → workflow: [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp)
4. The HMS saves the ABHA number, ABHA address and Eka's user id (`oid`) on the patient record. It prints the ABHA card if the patient wants one.
5. The consultation happens. The doctor records the prescription or visit summary in the HMS as usual.
6. After the visit, the HMS links the visit to the patient's ABHA as a care context. Confirmation arrives on a webhook; the HMS marks the visit as linked. → workflow: [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip)

## What they have at the end

The patient has an ABHA number and an ABHA address, and knows them. The HMS holds `abha_address`, `abha_number` and `oid` on the patient record, so every later ABDM call for this patient needs no new lookup. Today's visit is a linked care context, discoverable from any PHR app the patient uses and shareable with any HIU the patient grants consent to.

## Branches

* **The Aadhaar OTP finds an existing ABHA.** The verify step reports an existing profile; the flow logs the patient in rather than creating a duplicate. → same workflow, auto-login branch of [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp)
* **The Aadhaar mobile is not linked.** The flow asks for a separate mobile verification before creating. → same workflow, mobile verification branch
* **The patient refuses Aadhaar, or needs assisted registration without an OTP.** → the alternatives in [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp)
* **A later call for the patient returns `491`.** The patient's ABHA Gateway session has expired; renew it with a mobile OTP and retry. → workflow: [Hold the ABHA Gateway session](/docs/hie-cm/workflows/hold-gateway-session)
* **The patient wants their ABHA card, or KYC on a mobile-created address.** Fetch the profile, show the card and QR code, or run KYC. → workflow: [Manage the ABHA profile and KYC](/docs/hie-cm/workflows/manage-profile-and-kyc)
* **The patient shows a Scan and Share QR at the counter.** Their PHR app has already sent the profile. The HMS receives it on a webhook and replies with a token, skipping steps 1 to 3. → workflow: [Receive a scanned profile as a HIP](/docs/hie-cm/workflows/hip-scan-and-share)
* **The HMS keeps the clinical data itself rather than on Eka.** When the patient later shares records, Eka asks the HMS for them on a webhook and the HMS serves them encrypted. → workflow: [Serve records on a fetch request](/docs/hie-cm/workflows/serve-data-on-fetch)
* **The patient visited before this integration existed.** Old visits are not linked. The patient can find and claim them from their PHR app, which the HMS answers on webhooks. → workflow: [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link)


# Fetch a patient's records with consent
Source: https://developer.eka.care/docs/hie-cm/journeys/hiu-fetch-records-with-consent

An insurer or referral platform asks a patient for consent, and the patient's records arrive from every facility that holds them.

## In short

* Register your public key once, then raise a consent request for the patient's records.
* The patient approves the request in their PHR app.
* Each HIP sends the approved records; your platform decrypts them and tells Eka which it could read.
* If Eka stores the records for you, you read them from Eka instead.

## Who and when

An operations team at an insurer, or a coordinator on a referral platform, whose software is integrated with Eka as a Health Information User (HIU). A patient files a claim, or is referred to a specialist, and the team needs the patient's past records: prescriptions, discharge summaries, lab reports. The records sit at hospitals and clinics that are Health Information Providers (HIPs). The team cannot read them until the patient agrees.

**Already in place:** your software acts as a HIU. How to onboard as a HIU is not yet documented; for the facility ID, see facility onboarding in [Onboard a facility to ABDM](/docs/hie-cm/journeys/facility-onboard-to-abdm).  Your server can receive Eka webhooks. The patient has an ABHA. The visits you want are linked to it as care contexts at the HIPs that hold them ([Register a walk-in patient and link the visit](/docs/hie-cm/journeys/hip-register-patient-and-link-visit)).

## What they want

"Get this patient's records from the hospitals that treated them, with their permission, without chasing paper."

## The steps

1. Before the first request, your platform registers the public key that HIPs use to encrypt records for you. This happens once, and again whenever you rotate the key. → workflow: [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent)
2. The coordinator asks the patient for their ABHA address and explains why the records are needed.
3. The coordinator raises a consent request: which patient, for what purpose, which record types, which date range, and which facilities. → workflow: [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent)
4. The patient sees the request in their PHR app and approves it, choosing which records to share. This is the patient's action, not yours.
5. Your platform learns that the consent is granted and shows the request as approved. → same workflow, wait for the status update
6. Each HIP sends the approved records. Your platform decrypts them, checks each one, and tells Eka which records it could read. → workflow: [Receive and decrypt records as a HIU](/docs/hie-cm/workflows/hiu-receive-data)
7. The coordinator or underwriter reads the records in your platform.

## What they have at the end

Your platform holds the patient's FHIR records for the care contexts the patient approved, decrypted, each tied to the consent that authorised it. You hold the consent id and its status, so you can show an auditor what the patient agreed to and for how long. Eka has been told which records arrived intact.

## Branches

* **The patient denies the request.** The status update says so and no records arrive. Close the request in your platform and tell the coordinator. → same workflow, denied branch of [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent)
* **The patient does not respond.** The request stays pending and can expire unanswered. → same workflow, expiry branch
* **Eka stores the records for you.** Nothing arrives on a webhook. You read each approved care context from Eka's records product instead. → workflow: [Receive and decrypt records as a HIU](/docs/hie-cm/workflows/hiu-receive-data), "Eka stores the data" branch
* **One HIP is down or never sends.** Records arrive from the other HIPs; the missing one does not. → same workflow, failure table
* **A record fails to decrypt or its checksum does not match.** You report it as failed to Eka for that care context. → same workflow, acknowledge step
* **The patient revokes consent later.** The status update says so. Stop using the records from that HIP. → same workflow, revoked branch of [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent)
* **The visit was never linked at the HIP.** The consent cannot cover it. The patient asks the facility to link it, or claims it from their PHR app. → journey: [Register a walk-in patient and link the visit](/docs/hie-cm/journeys/hip-register-patient-and-link-visit)


# Gather every health record in a PHR app
Source: https://developer.eka.care/docs/hie-cm/journeys/phr-patient-aggregates-records

A patient creates an ABHA in a PHR app, pulls in records from every facility they have visited, decides who sees them, and shares their profile at a facility counter.

## In short

* The patient creates an ABHA in the app, or logs in to one they already have.
* They link records from each facility they visited, with an OTP.
* They answer each consent request, and a health locker policy brings in new records.
* At a facility counter, one scan shares their profile.

## Who and when

A patient who has installed a Personal Health Record (PHR) app built on ABDM Connect. They have visited several hospitals, clinics and labs over the years, and their records are scattered across each facility's software. They open the app to get an ABHA, see everything in one place, and stop carrying paper files to every appointment.

**Already in place:** your software acts as a PHR app. That usually makes it a Health Information User (HIU), when it pulls records from facilities on the patient's behalf. It is also a Health Information Provider (HIP), when it holds records the patient uploads. You have Eka credentials ([Authorization](/api-sdk/auth/getting-started)), and your cloud can receive Eka webhooks, because linking results, consent updates and subscription notifications arrive only there. No other journey has to run first.

## What they want

"Put all my health records in one app, let me decide who sees them, and let me check in at the hospital without filling a form."

## The steps

1. The patient opens the app for the first time and creates an ABHA. With Aadhaar and its linked mobile, they enter the OTP Aadhaar sends and get a KYC-verified ABHA number and ABHA address. → workflow: [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp)
2. A returning patient logs in instead, with their ABHA address, Aadhaar or mobile number and an OTP. → workflow: [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha)
3. The app keeps the patient's ABHA gateway session alive. When it expires, the patient enters one more mobile OTP and carries on where they were. → workflow: [Hold an ABHA gateway session](/docs/hie-cm/workflows/hold-gateway-session)
4. The patient checks their profile, completes KYC if the app asks, and saves their ABHA card and QR code. → workflow: [Manage the ABHA profile and KYC](/docs/hie-cm/workflows/manage-profile-and-kyc)
5. The patient searches for a hospital or lab they have visited. The app asks that facility for records it holds against the patient that are not yet linked. The patient picks the ones that are theirs and enters the OTP the facility sends to their mobile. → workflow: [Discover and link records from a facility](/docs/hie-cm/workflows/phr-discover-and-link)
6. The app lists every facility the patient now has records with, and the records under each one. → workflow: [List a patient's linked records](/docs/hie-cm/workflows/phr-list-records)
7. Requests from doctors, hospitals and insurers who want to see the records land in the patient's inbox. The patient reads each one and approves it, denies it, or later revokes it. → workflow: [Act on a consent request](/docs/hie-cm/workflows/phr-act-on-consent)
8. So they are not asked every time, the patient turns the app into their health locker. They approve a standing policy once, and the app is notified each time a facility links a new record, then fetches it through a consent. → workflow: [Set up the health locker](/docs/hie-cm/workflows/set-up-health-locker)
9. On their next visit, the patient scans the QR code at the registration counter. Their profile reaches the facility's software, and the app shows the token number the counter issues. → workflow: [Share a profile at a facility counter](/docs/hie-cm/workflows/phr-scan-and-share)

## What they have at the end

The patient has an ABHA number and an ABHA address, and the app holds a session for them. Records from every facility they linked appear in one list, grouped by facility. They have answered every pending consent request. Under a standing policy, the app is notified of each new record and fetches it through a consent. At a facility counter, one scan registers them and gives them a token.

## Branches

* **The patient cannot use an Aadhaar OTP, or already has an ABHA.** → branches of [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp)
* **The facility finds no unlinked records for the patient.** → retry branch of [Discover and link records from a facility](/docs/hie-cm/workflows/phr-discover-and-link)

- **The patient uploads a record of their own, such as an old lab report.** The upload becomes a care context under the app's own HIP, discoverable and shareable like any facility record.&#x20;


# Overview
Source: https://developer.eka.care/docs/hie-cm/nhpr-abdm/getting-started



This guide explains how to integrate with the **National Health Provider Registry (NHPR)** under the ABDM ecosystem. The integration is divided into three parts:

1. **HPR APIs** — Create and manage Healthcare Professional IDs directly from your portal
2. **HFR APIs** — Search, register, and link Health Facilities directly from your portal
3. **Onboarding** — Register your HPR & HFR with ABDM and onboard them to the Eka system

## 1. Healthcare Professional Registry (HPR)

These APIs let you integrate HPR ID creation directly into your application, so healthcare professionals can register their digital identity without leaving your portal.

**1. Aadhaar Authentication**

Initiate the process by sending an OTP to the professional's Aadhaar-linked mobile number. Verify the OTP to establish identity.

**2. Verify Linked Mobile**

Verify that the mobile number provided by the user matches the one linked with their Aadhaar record. This ensures the contact details are authentic.

**3. Check Existing HPR ID**

Check if an HPR ID already exists for the current transaction or Aadhaar profile. If it exists, you may skip creation; otherwise, proceed to generate a new ID.

**4. Get ID Suggestions**

If no ID exists, retrieve a list of system-suggested HPR IDs (e.g., `dr.name@hpr`) based on the user's profile to help them choose a valid handle.

**5. Create HPR ID**

Finalize the registration by creating the HPR ID using a chosen or available handle. This generates the professional's digital profile in the ABDM network.

[HPR APIs →](/api-sdk/hie-cm/nhpr-abdm/hpr/get-aadhar-otp)

## 2. Health Facility Registry (HFR)

These APIs let you integrate facility management directly into your application, so you can search, register, and link health facilities from your portal.

**1. Search Facility**

Check if the facility already exists in the registry before attempting to create a new one.

**2. Onboard Facility**

Register a new facility in the ABDM registry. This requires submitting official details such as the facility name, physical address, and the authorizing doctor's OID.

**3. Link Facility**

Once a facility is identified or onboarded, connect it to the ABDM Bridge software. This linkage allows the facility to exchange health data and participate in the digital health network securely.

[HFR APIs →](/api-sdk/hie-cm/nhpr-abdm/hfr/search-facility)

## 3. Onboarding to Eka

Once the HPR ID and HFR ID have been created and registered on the ABDM portal, the final step is to onboard the facility into the Eka system. This connects your ABDM-registered facility to the Eka Bridge, enabling health data exchange through EKA's ABDM Connect.

**1. Create HPR ID**

Register as a Facility Manager or Healthcare Professional on the ABDM portal.

**2. Register Facility (HFR ID)**

Log in with your HPR ID, add facility details, upload documents, and submit for approval. Once approved, you receive the HFR ID.

**3. Software Linkage**

From the facility dashboard, select Software Linkage and use the Eka Bridge ID to register your facility under Eka Bridge.

**4. Onboard to Eka**

Call the onboard API to register the facility in the Eka system, completing the integration.

[Onboarding Guide →](/docs/hie-cm/nhpr-abdm/onboarding-overview)


# Facility Onboarding
Source: https://developer.eka.care/docs/hie-cm/nhpr-abdm/onboarding-overview

Onboard your ABDM-registered healthcare facility to the Eka system

After your healthcare facility has been registered on the ABDM portal with a valid HPR ID and HFR ID, you need to onboard it into the Eka system. This final step connects your facility to the Eka Bridge, enabling it to participate in health data exchange through EKA's ABDM Connect.

> [!NOTE]
>
> You can create HPR and HFR IDs either through the [ABDM portal](https://nhpr.abdm.gov.in/nhpr/v4/login) or programmatically using the [HPR](/api-sdk/hie-cm/nhpr-abdm/hpr/get-aadhar-otp) and [HFR](/api-sdk/hie-cm/nhpr-abdm/hfr/search-facility) APIs.

## Prerequisites

**1. Create HPR ID**

Every facility needs at least one registered healthcare professional. Create an HPR ID via Aadhaar-based verification — either through the [ABDM portal](https://nhpr.abdm.gov.in/nhpr/v4/login) or using the [HPR APIs](/api-sdk/hie-cm/nhpr-abdm/hpr/get-aadhar-otp).

**2. Register Facility (HFR ID)**

Log in with the HPR ID on the ABDM portal. Add facility details (name, address, type), upload required documents, and submit for approval. Once approved, you receive the **HFR ID** — the facility's unique identifier in the ABDM network.

**3. Software Linkage**

From the facility dashboard on the ABDM portal, navigate to **Software Linkage**. Enter the **Eka Bridge ID** to register your facility under the Eka Bridge. This authorizes Eka to act as the software provider for your facility's ABDM transactions.

## Onboard to Eka

Once all prerequisites are complete, call the onboard API to register the facility in the Eka system.

> **[Onboard Facility API](/api-sdk/hie-cm/nhpr-abdm/onboarding)**
>
> **POST** `/abdm/v1/hip/onboard`


# Overview
Source: https://developer.eka.care/docs/hie-cm/patient-requests/getting-started



### ABHA has three kinds of requests

#### 1. Consents

These are consents requests by another HIUs(Doctors / PHR Apps / EMRs)
to view the patient care context/documents.

#### 2. Subscription Requests

These are the requests created by PHR Apps to get notification when new
care context is created for the patient by other HIPs.

#### 3. Authorization Requests

These are raised by HIPs to link a document to the Patients ABHA Address.

> [!NOTE]
>
> User Authorization will be required for all these operations.

**1. List All Request Overview**

Use the [List Requests](/api-sdk/hie-cm/patient-requests/list-requests) endpoint
to get all your requests related to Subscriptions, Authorizations, and Consents.

**2. Get Detailed Request Overview**

Use the [Get Details](/api-sdk/hie-cm/patient-requests/requests-get-details) endpoint to retrieve detailed information about a specific Consent, Subscription, or Authorization request by its ID.


# 1 · ABHA Onboarding
Source: https://developer.eka.care/docs/hie-cm/phr/abha-onboarding

Create an ABHA address, log the patient in, and hold a live ABHA Gateway session.

The first thing a PHR app does is give the patient an **ABHA address** (`nisha@abdm`) — the identity every later API call is anchored to. A patient either creates one in your app, or already has one and logs in.

## Create an ABHA address

Three independent methods. Pick whichever your onboarding UX supports; face auth is the fallback when the patient's mobile is not linked to their Aadhaar.

```mermaid theme={null}
flowchart LR
  A["Mobile OTP"] --> Z["ABHA address created"]
  B["Aadhaar OTP"] --> Z
  C["Face Auth"] --> Z
```

### Via mobile OTP

The lightest path — creates an ABHA address without Aadhaar KYC.

| Step | API |
| - | - |
| Generate OTP | [`POST /abdm/na/v1/registration/mobile/init`](/api-sdk/hie-cm/enrollment/mobile/init) |
| Resend OTP | [`POST /abdm/na/v1/registration/mobile/resend`](/api-sdk/hie-cm/enrollment/mobile/resend) |
| Verify OTP | [`POST /abdm/na/v1/registration/mobile/verify`](/api-sdk/hie-cm/enrollment/mobile/verify) |
| Create ABHA | [`POST /abdm/na/v1/registration/mobile/create-phr`](/api-sdk/hie-cm/enrollment/mobile/create) |

### Via Aadhaar OTP

Produces a KYC-verified 14-digit **ABHA number** alongside the address.

| Step | API |
| - | - |
| Generate Aadhaar OTP | [`POST /abdm/na/v1/registration/aadhaar/init`](/api-sdk/hie-cm/enrollment/aadhaar/initiate-registration) |
| Resend Aadhaar OTP | [`POST /abdm/na/v1/registration/aadhaar/resend`](/api-sdk/hie-cm/enrollment/aadhaar/aadhaar-resend-otp) |
| Verify Aadhaar OTP | [`POST /abdm/na/v1/registration/aadhaar/verify`](/api-sdk/hie-cm/enrollment/aadhaar/verify-otp) |
| Verify mobile (if not Aadhaar-linked) | [`POST /abdm/na/v1/registration/aadhaar/mobile/verify`](/api-sdk/hie-cm/enrollment/aadhaar/mobile-verify) |
| Resend mobile OTP | [`POST /abdm/na/v1/registration/aadhaar/mobile/resend`](/api-sdk/hie-cm/enrollment/aadhaar/mobile-resend-otp) |
| Create ABHA | [`POST /abdm/na/v1/registration/aadhaar/create-phr`](/api-sdk/hie-cm/enrollment/aadhaar/create-abha) |
| Log into an existing ABHA found during the flow | [`POST /abdm/na/v1/registration/aadhaar/auto-login`](/api-sdk/hie-cm/enrollment/aadhaar/auto-login) |

### Via face auth

For patients whose mobile is not linked to Aadhaar and who cannot receive an Aadhaar OTP.

| Step | API |
| - | - |
| Overview | [Face Auth](/docs/hie-cm/enrollment/face-auth/intro) |
| Init | [`POST /abdm/na/v1/face-auth/init`](/api-sdk/hie-cm/enrollment/face-auth/face-auth-init) |
| Capture | [`POST /abdm/na/v1/face-auth/capture`](/api-sdk/hie-cm/enrollment/face-auth/face-auth-capture) |
| Verify | [`POST /abdm/na/v1/face-auth/verify`](/api-sdk/hie-cm/enrollment/face-auth/face-auth-verify) |

[Full M1 creation flow chart →](/docs/hie-cm/flows/m1)

## Helper APIs

Use these while the patient is still filling the form — they make the difference between a clean signup and a failed one.

| Purpose | API |
| - | - |
| Check whether an ABHA address is already taken | [`POST /abdm/na/v1/registration/phr/check`](/api-sdk/hie-cm/commons/does-health-id-exist) |
| Suggest available ABHA addresses | [`GET /abdm/na/v1/registration/suggest`](/api-sdk/hie-cm/commons/suggest-abha-address) |
| Resolve a pincode to state / district | [`GET /abdm/v1/registration/pincode/{pincode}`](/api-sdk/hie-cm/commons/pincode-details) |

## Login to the PHR app

A returning patient logs in with ABHA address, Aadhaar or mobile number. All three converge on `skip_state = abha_end`.

| Step | API |
| - | - |
| List available login methods for an identifier | [`POST /abdm/na/v1/profile/login/methods`](/api-sdk/hie-cm/login/methods) |
| Generate login OTP | [`POST /abdm/na/v1/profile/login/init`](/api-sdk/hie-cm/login/init) |
| Verify login OTP | [`POST /abdm/na/v1/profile/login/verify`](/api-sdk/hie-cm/login/verify) |
| Complete PHR login (mobile route, picks one of several ABHAs) | [`POST /abdm/na/v1/profile/login/phr`](/api-sdk/hie-cm/login/login) |

> [!NOTE]
>
> When login returns `skip_state = abha_create` **and** `abha_profiles` is non-empty, the patient already has ABHAs on that identifier — use the [Auto-Login API](/api-sdk/hie-cm/enrollment/aadhaar/auto-login) to sign them into an existing one instead of creating a duplicate.

## Hold the ABHA Gateway session

Creation and login both open a session with the ABDM gateway. It expires. Any patient-scoped API called without it returns HTTP `491`, and you must re-authenticate with a mobile OTP.

| Step | API |
| - | - |
| Check whether a session is still valid **(call this first)** | [`GET /abdm/v1/session/status`](/api-sdk/hie-cm/session/status) |
| Generate mobile OTP for a new session | [`POST /abdm/v1/session/init`](/api-sdk/hie-cm/session/init) |
| Verify OTP and get the session token | [`POST /abdm/v1/session/verify`](/api-sdk/hie-cm/session/verify) |

[User Session overview →](/docs/hie-cm/session/getting-started)

## Skip the UI entirely

If you don't want to build the OTP screens, the ABHA Web SDK ships the whole creation and login flow as an embeddable, themeable component.

> **[M1 — ABHA Web SDK](/api-sdk/hie-cm/sdks/web-sdk/abha-sdk/get-started)**
>
> Drop-in ABHA creation, login, KYC and Scan & Share, with your own branding.

> [!NOTE]
>
> The [`abha.created`](/docs/hie-cm/webhooks/abha-created) webhook fires on your cloud when an ABHA address is successfully created. Use it to provision the patient in your own database rather than relying on the client-side response.


# 5 · Consents & Subscriptions
Source: https://developer.eka.care/docs/hie-cm/phr/consents

The patient's control panel: list, approve, deny and revoke consent requests, and set up auto-approval and the health locker.

Consent is the whole point of ABDM. A PHR app sits on both sides of it — it **receives** consent requests raised by other HIUs so the patient can act on them, and it **raises** its own requests when it needs to pull records on the patient's behalf.

> [!NOTE]
>
> Every consent operation needs a live ABHA Gateway session. See [User Session](/docs/hie-cm/session/getting-started).

## The patient's request inbox

An ABHA address receives three kinds of request. All three land in the same inbox.

| Kind | Raised by | What it asks for |
| - | - | - |
| **Consent** | Another HIU — a doctor, hospital, insurer, or another PHR app | Permission to view specific care contexts |
| **Subscription** | A PHR app | Ongoing notification whenever a new care context is created |
| **Authorization** | A HIP | Permission to link a document to the patient's ABHA address |

| Purpose | API |
| - | - |
| List all requests | [`GET /abdm/v1/requests`](/api-sdk/hie-cm/patient-requests/list-requests) |
| Get one request's details | [`GET /abdm/v1/request`](/api-sdk/hie-cm/patient-requests/requests-get-details) |

[Patient Requests overview →](/docs/hie-cm/patient-requests/getting-started)

## Acting on a consent request

```mermaid theme={null}
flowchart LR
  A["Consent request arrives"] --> B{"Patient decides"}
  B -->|Approve| C["Consent artefacts generated<br/>(one per HIP)"]
  B -->|Deny| D["Request closed"]
  C --> E["Revoke anytime"]
```

| Action | API |
| - | - |
| List consent requests | [`POST /abdm/v1/consents/list`](/api-sdk/hie-cm/consents/consent-list) |
| Get consent details (including `care_context_id`s) | [`POST /abdm/v1/consents/details`](/api-sdk/hie-cm/consents/consent-details) |
| Approve — pick which care contexts to share | [`POST /abdm/v1/consents/approve`](/api-sdk/hie-cm/consents/consent-approve) |
| Deny, with a reason | [`POST /abdm/v1/consents/deny`](/api-sdk/hie-cm/consents/consent-deny) |
| Revoke a granted consent artefact | [`POST /abdm/v1/consents/revoke`](/api-sdk/hie-cm/consents/consent-revoke) |

On approval, ABDM generates one **consent artefact per HIP** involved. Revocation is per artefact — the patient can cut off one hospital without revoking the whole consent.

## Raising a consent request as an HIU

Your PHR app fetching records from other providers *is* an HIU operation. Same API a hospital or insurer would use.

| Purpose | API |
| - | - |
| Create a consent request | [`POST /abdm/v1/consents/create`](/api-sdk/hie-cm/consents/consent-create) |

Specify the patient's ABHA address, the purpose, the date range, and which HIPs to fetch from. Once the patient approves, EKA drives all the intermediate gateway callbacks for you — see [Fetch & Display Records](/docs/hie-cm/phr/records).

## Auto-approval and the health locker

Asking the patient to approve every single record is unusable at scale. An **auto-approval policy** lets the patient authorise a class of requests once — this is what turns your PHR app into the patient's **health locker**: new records flow in without a prompt each time.

| Purpose | API |
| - | - |
| Get the current auto-approval policy | [`GET /abdm/v1/consents/auto-approval`](/api-sdk/hie-cm/consents/auto-approval/get-status) |
| Create or update the policy | [`PATCH /abdm/v1/consents/auto-approval`](/api-sdk/hie-cm/consents/auto-approval/update-auto-approval-policy) |

When the locker is set up, your cloud receives [`abha.locker_created`](/docs/hie-cm/webhooks/locker-created) carrying the resulting `auto_approval_id` and `subscription_id` — store both, they identify the standing arrangement.

## Events to handle

| Event | Webhook |
| - | - |
| A consent request's status changed | [`abha.consent_update`](/docs/hie-cm/webhooks/consent-update) |
| Locker (auto-approval + subscription) created | [`abha.locker_created`](/docs/hie-cm/webhooks/locker-created) |
| Subscription updated | [`abha.subscription_modified`](/docs/hie-cm/webhooks/subscription-modify) |
| New care context linked under a subscription | [`abha.subscription_notify`](/docs/hie-cm/webhooks/subscription-notify) |

[Consents overview →](/docs/hie-cm/consents/getting-started) · [M3 flow chart →](/docs/hie-cm/flows/m3)

> **[M3 — Consent Management Web SDK](/api-sdk/hie-cm/sdks/web-sdk/consent-management/get-started)**
>
> The full consent inbox and approval UI as an embeddable component.


# 4 · Discover & Link Records
Source: https://developer.eka.care/docs/hie-cm/phr/discover-and-link

Find the patient's existing records at any ABDM-connected facility and link them to their ABHA address.

This is what makes a PHR app worth installing: the patient searches a hospital or lab they visited, sees records ABDM knows about but that were never linked, and pulls them into their ABHA account with an OTP.

```mermaid theme={null}
sequenceDiagram
  participant P as PHR App
  participant E as EKA / ABDM
  participant H as Facility (HIP)
  P->>E: Search providers
  P->>E: POST /care-contexts/discover
  E->>H: Discovery request
  H-->>P: Unlinked care contexts
  P->>E: POST /care-contexts/discover/link/init (selected contexts)
  H-->>P: OTP to patient's mobile
  P->>E: POST /care-contexts/discover/link/confirm (txn_id + OTP)
  E-->>P: Care contexts linked
```

## Step 1 — Find the facility

The patient picks the hospital, clinic or lab they visited. Providers are ABDM-registered facilities identified by `hip_id`.

| Purpose | API |
| - | - |
| Search providers by name | [`GET /abdm/v1/providers`](/api-sdk/hie-cm/providers/search/providers) |
| Get a single provider's details | [`GET /abdm/v1/provider/{hip_id}`](/api-sdk/hie-cm/providers/provider) |

[Providers overview →](/docs/hie-cm/providers/getting-started)

## Step 2 — Discover unlinked care contexts

Send the patient's verified identifiers to the chosen facility. The facility matches them against its own records and returns the care contexts (visits, prescriptions, lab reports) that are not yet linked.

| Purpose | API |
| - | - |
| Discover unlinked care contexts | [`POST /abdm/v1/care-contexts/discover`](/api-sdk/hie-cm/care-contexts/discover/discover) |

## Step 3 — Link with OTP

The patient selects which care contexts to claim. The facility sends an OTP to their registered mobile; confirming it completes the link.

| Step | API |
| - | - |
| Initiate linking (facility sends OTP) | [`POST /abdm/v1/care-contexts/discover/link/init`](/api-sdk/hie-cm/care-contexts/discover/link-init) |
| Confirm linking with `txn_id` + OTP | [`POST /abdm/v1/care-contexts/discover/link/confirm`](/api-sdk/hie-cm/care-contexts/discover/link-confirm) |

[Care Context Discovery — full flow →](/docs/hie-cm/care-contexts/discover/introduction)

## The other direction: HIP-initiated linking

A facility can also link records to the patient's ABHA address on its own, without the patient discovering anything. The patient then sees an **authorization request** in their inbox.

| Purpose | API |
| - | - |
| List all pending requests (consent, subscription, authorization) | [`GET /abdm/v1/requests`](/api-sdk/hie-cm/patient-requests/list-requests) |
| Get details of one request | [`GET /abdm/v1/request`](/api-sdk/hie-cm/patient-requests/requests-get-details) |

[Patient Requests overview →](/docs/hie-cm/patient-requests/getting-started)

> [!NOTE]
>
> If your PHR app **also** runs facility software (you are a HIP too), the HIP-side APIs are a separate set: [Care Context Link](/api-sdk/hie-cm/care-contexts/link/hip-linking), [On Discover](/api-sdk/hie-cm/care-contexts/discover/on_discover), [On Link Init](/api-sdk/hie-cm/care-contexts/discover/link_on_init), [On Link Confirm](/api-sdk/hie-cm/care-contexts/discover/link_on_confirm), and [Notify unlinked care contexts](/api-sdk/hie-cm/care-contexts/records/notify).

## Stay linked: subscriptions

Discovery is a one-time pull. To keep receiving new records automatically, the PHR app holds a **subscription** on the patient's ABHA address — once granted, every new care context linked by any HIP notifies your cloud.

| Event | Webhook |
| - | - |
| A new care context was linked under an active subscription | [`abha.subscription_notify`](/docs/hie-cm/webhooks/subscription-notify) |
| Subscription period, categories or status changed | [`abha.subscription_modified`](/docs/hie-cm/webhooks/subscription-modify) |

> [!NOTE]
>
> `abha.subscription_notify` tells you a record **exists** — it does not deliver it. To read the document, raise a consent request with [Create Consent](/api-sdk/hie-cm/consents/consent-create), or rely on an auto-approval policy so it happens without prompting the patient. See [Consents & Subscriptions](/docs/hie-cm/phr/consents).


# Build a PHR App
Source: https://developer.eka.care/docs/hie-cm/phr/overview

End-to-end map of every EKA ABDM Connect API you need to build a Personal Health Record (PHR) application, in the order a patient journey needs them.

A **PHR (Personal Health Record) app** is the patient-facing side of ABDM. The patient creates an ABHA, logs in, discovers and links records from every facility they have ever visited, decides who gets to see them, and shares their identity at a facility counter.

PHR is a separate ABDM integration track — not one of the HMIS milestones. But it *reuses* APIs from Milestone 1, Milestone 2 and Milestone 3. This page is the single index of which API belongs to which stage of the PHR journey, so you don't have to reassemble it from the milestone trees.

> [!NOTE]
>
> A PHR app is usually **both a HIP and an HIU**: a HIU when it fetches records from other providers on the patient's behalf, and a HIP when it stores records the patient uploaded themselves (the health locker).

## The two components

Every PHR integration has two halves, and it matters which half calls what.

> **PHR App UI**
>
> The patient's app or web client. Handles ABHA creation, login, consent screens, QR scanning, and record display. Never holds your `client_secret`.

> **PHR App Cloud**
>
> Your backend. Holds credentials, calls EKA's ABDM Connect APIs, and **receives webhooks** — the asynchronous half of ABDM (linking status, consent updates, subscription notifications) only ever reaches your cloud.

## The patient journey

```mermaid theme={null}
flowchart TD
  A["1 · Create ABHA address"] --> B["2 · Login & session"]
  B --> C["3 · Manage profile"]
  C --> D["4 · Discover & link records"]
  C --> E["5 · Scan & Share at a facility"]
  D --> F["6 · Consents & subscriptions"]
  F --> G["7 · Fetch & display records"]
  G --> H["8 · Upload own records (locker)"]
```

## Stage-by-stage API map

> **[1 · ABHA Onboarding](/docs/hie-cm/phr/abha-onboarding)**
>
> Create an ABHA address via mobile OTP, Aadhaar OTP or face auth. Log the patient in and hold an ABHA Gateway session.

> **[2 · Profile Management](/docs/hie-cm/phr/profile)**
>
> Read and update the ABHA profile, run KYC, render the ABHA card and QR, delete the account.

> **[3 · Scan & Share](/docs/hie-cm/phr/scan-and-share)**
>
> Patient scans a facility QR to register instantly and get a token number.

> **[4 · Discover & Link Records](/docs/hie-cm/phr/discover-and-link)**
>
> Search providers, discover unlinked care contexts, and link them to the patient's ABHA address.

> **[5 · Consents & Subscriptions](/docs/hie-cm/phr/consents)**
>
> List, approve, deny and revoke consent requests. Set up auto-approval and the health locker.

> **[6 · Fetch & Display Records](/docs/hie-cm/phr/records)**
>
> List linked providers and care contexts, receive FHIR data, and let the patient upload their own documents.

> **[7 · Webhooks](/docs/hie-cm/phr/webhooks)**
>
> Every asynchronous event a PHR app must handle, in one list.

> **[Errors](/docs/hie-cm/errors)**
>
> ABDM, gateway and EKA error codes and what to show the patient.

## Where each stage comes from

If you are also tracking ABDM certification, this is how the PHR journey maps onto the milestone trees:

| PHR stage | ABDM milestone | EKA API group |
| - | - | - |
| Create ABHA address, login | M1 | [ABHA Creation & Login](/docs/hie-cm/registration/intro) |
| Profile, KYC, card & QR | M1 | [Profile Management](/docs/hie-cm/profile/getting-started) |
| Gateway session | M1 | [User Session](/docs/hie-cm/session/getting-started) |
| Scan & Share | M1 | [Scan & Share](/docs/hie-cm/scan-and-share/getting-started) |
| Discover & link records | M2 | [Care Contexts](/docs/hie-cm/care-contexts/getting-started) |
| Provider search | M2 | [Providers](/docs/hie-cm/providers/getting-started) |
| Pending requests inbox | M2 | [Patient Requests](/docs/hie-cm/patient-requests/getting-started) |
| Consents, auto-approval | M3 | [Consents](/docs/hie-cm/consents/getting-started) |
| Receiving FHIR data | M3 | [Data Sharing](/docs/hie-cm/care-contexts/ecdh-encryption) |

## Before you start

**1. Get credentials**

Sign up on the EKA developer console and provision your `client_id` / `client_secret`, then exchange them for an access token.

[Authorization →](/api-sdk/auth/getting-started)

**2. Register your webhook URL**

A PHR app cannot work on request/response alone — linking results, consent updates and subscription notifications all arrive as webhooks. Share your endpoint with EKA before you begin testing.

[PHR webhooks →](/docs/hie-cm/phr/webhooks)

**3. Understand the ABHA Gateway session**

Most patient-scoped APIs need a live ABHA Gateway session on top of your partner token. When it expires, those APIs return HTTP `491` and you must re-authenticate the patient.

[User Session →](/docs/hie-cm/session/getting-started)


# 2 · Profile Management
Source: https://developer.eka.care/docs/hie-cm/phr/profile

Read and update the patient's ABHA profile, run KYC, and render the ABHA card and QR code.

Once the patient is logged in, the PHR app owns their ABHA profile screen — name, address, linked mobile, KYC status, and the ABHA card they show at a facility.

> [!NOTE]
>
> All profile APIs need a live ABHA Gateway session. Check [`GET /abdm/v1/session/status`](/api-sdk/hie-cm/session/status) before rendering the profile screen; a `491` means you need to re-authenticate.

## Profile details

| Purpose | API |
| - | - |
| Fetch the full ABHA profile | [`GET /abdm/v1/profile`](/api-sdk/hie-cm/profile/details/profile-details) |
| Update profile fields | [`PATCH /abdm/v1/profile`](/api-sdk/hie-cm/profile/details/update-profile) |
| Delete the ABHA account | [`DELETE /abdm/v1/profile`](/api-sdk/hie-cm/profile/details/delete) |
| Search for an ABHA profile | [`POST /abdm/v1/profile/search`](/api-sdk/hie-cm/profile/search/search) |

## ABHA card and QR code

The two assets a patient actually shows at a counter. Render them directly in the app.

| Purpose | API |
| - | - |
| ABHA card image | [`GET /abdm/v1/profile/asset/card`](/api-sdk/hie-cm/profile/cards/abha-card) |
| ABHA QR code | [`GET /abdm/v1/profile/asset/qr`](/api-sdk/hie-cm/profile/cards/qr-code) |

## KYC

An ABHA address created via mobile OTP is not KYC-verified. Run KYC to upgrade it — required before the patient gets a 14-digit ABHA number and full record access.

```mermaid theme={null}
flowchart LR
  A["KYC Init"] --> B["Verify OTP"]
  A --> R["Resend OTP"]
  R --> B
  B --> C["KYC complete"]
```

| Step | API |
| - | - |
| Initiate KYC | [`POST /abdm/v1/profile/kyc/init`](/api-sdk/hie-cm/profile/kyc/kyc-init) |
| Resend OTP | [`POST /abdm/v1/profile/kyc/resend`](/api-sdk/hie-cm/profile/kyc/kyc-resend) |
| Verify OTP | [`POST /abdm/v1/profile/kyc/verify`](/api-sdk/hie-cm/profile/kyc/kyc-verify) |

[Profile Management overview →](/docs/hie-cm/profile/getting-started)

## Link / de-link ABHA address and ABHA number

An ABHA address and a 14-digit ABHA number are linked through KYC — completing Aadhaar KYC on a mobile-created ABHA address associates it with the patient's ABHA number. There is no separate de-link endpoint; deleting the profile is the terminal action.

> **[M1 — ABHA Web SDK](/api-sdk/hie-cm/sdks/web-sdk/abha-sdk/abha-kyc)**
>
> The Web SDK ships the KYC flow as a themeable component if you'd rather not build the OTP screens.


# 6 · Fetch & Display Records
Source: https://developer.eka.care/docs/hie-cm/phr/records

List the patient's linked providers and care contexts, receive FHIR data, and let the patient upload their own documents.

Once records are linked and consent is in place, the PHR app's job is to show them. An ABHA address can carry thousands of documents across dozens of providers, so listing is deliberately two-stage: providers first, then care contexts within a provider.

## Step 1 — List linked providers

```mermaid theme={null}
flowchart LR
  A["GET /care-contexts/providers"] --> B["hip_id + provider name"]
  B --> C["GET /care-contexts/linked?hip_id=…"]
  C --> D["Care contexts for that provider"]
```

| Purpose | API |
| - | - |
| All providers the patient has linked records with | [`GET /abdm/v1/care-contexts/providers`](/api-sdk/hie-cm/care-contexts/providers/providers) |

## Step 2 — List care contexts for a provider

| Purpose | API |
| - | - |
| Linked care contexts under a `hip_id` | [`GET /abdm/v1/care-contexts/linked`](/api-sdk/hie-cm/care-contexts/records/records) |

[Care Contexts overview →](/docs/hie-cm/care-contexts/getting-started)

## Step 3 — Get the actual data

Listing gives you metadata. To read a document, the patient must have granted consent — then the FHIR bundle reaches you one of two ways, depending on how your integration stores data.

> **You store the data**
>
> You receive [`abha.hiu_data_push`](/docs/hie-cm/webhooks/hiu-data-push) with the encrypted FHIR bundle and the `key_information` needed to decrypt it.
>
> Register your public keyset first with [`PATCH /abdm/v1/hiu/keyset`](/api-sdk/hie-cm/care-contexts/hiu-keys) — EKA shares it with the HIP so they can encrypt for you.
>
> Acknowledge parsing status via [`POST /abdm/v1/hiu/care-context/data/on-push`](/api-sdk/hie-cm/care-contexts/data-on-push).

> **EKA stores the data**
>
> Nothing to decrypt. Call [`GET /health/api/v1/fhir/retrieve`](/api-sdk/health-records/retrieve-health-records) with the `care_context_id` as the identifier.
>
> Get the `care_context_id` from [Consent Details](/api-sdk/hie-cm/consents/consent-details) after approval.

[ECDH encryption explained →](/docs/hie-cm/care-contexts/ecdh-encryption)

## Patient-uploaded records (health locker)

A PHR app is also a HIP for anything the patient uploads themselves — a scanned prescription, an old lab report. Uploading through the Medical Records APIs **automatically creates a care context**, so the document becomes discoverable and shareable like any facility record.

| Purpose | API |
| - | - |
| Get an upload authorization | [`POST /mr/api/v1/docs`](/api-sdk/health-records/obtain-authorization) |
| Upload the file | [Step 2: Upload Record](/docs/health-records/upload-records) |
| List the patient's documents | [`GET /mr/api/v1/docs`](/api-sdk/health-records/list-records) |
| Get one document | [`GET /mr/api/v1/docs/{id}`](/api-sdk/health-records/describe-record) |
| Update document metadata | [`PATCH /mr/api/v1/docs/{id}`](/api-sdk/health-records/update-document) |
| Delete a document | [`DELETE /mr/api/v1/docs/{id}`](/api-sdk/health-records/delete-document) |
| Group documents into a case | [`POST /mr/api/v1/cases`](/api-sdk/health-records/create-case) |

| Event | Webhook |
| - | - |
| Upload finished processing | [`rec.uploaded`](/docs/health-records/record-uploaded-webhook) |
| Record list changed | [`rec.refresh`](/docs/health-records/record-refresh-webhook) |

[Medical Records — Add →](/api-sdk/health-records/create-overview) · [Read →](/docs/health-records/read-documents)

> [!NOTE]
>
> Storing records on EKA has a second benefit: when an HIU later requests that care context, EKA serves the data automatically and you never receive the [`abha.hip_data_fetch`](/docs/hie-cm/webhooks/hip-data-fetch) webhook.


# 3 · Scan & Share
Source: https://developer.eka.care/docs/hie-cm/phr/scan-and-share

Let the patient scan a facility QR code to register instantly and receive a token number.

The patient walks up to a registration counter, scans the facility's **Health Facility QR code** in your PHR app, and their ABHA profile lands in the facility's HMIS — no form, no queue. The facility optionally returns a token number.

```mermaid theme={null}
sequenceDiagram
  participant P as PHR App
  participant E as EKA / ABDM
  participant H as Health Facility (HIP)
  P->>E: POST /abdm/v2/profile/share (scanned QR + location)
  E->>H: Patient profile shared
  H-->>E: Token number (optional)
  P->>E: GET /abdm/v2/profile/share/{request_id}
  E-->>P: HIP details, token, expiry
```

## APIs

| Step | API |
| - | - |
| Share the profile with the scanned facility | [`POST /abdm/v2/profile/share`](/api-sdk/hie-cm/scan-and-share/phr-scan-share) |
| Poll for the facility's token number | [`GET /abdm/v2/profile/share/{request_id}`](/api-sdk/hie-cm/scan-and-share/phr-scan-share-token) |

The share request is asynchronous: the first call returns a `request_id`, and the token comes back on the second call once the facility responds. The response carries HIP details, token expiry, and whether the token should be displayed to the patient.

[Scan & Share overview →](/docs/hie-cm/scan-and-share/getting-started)

> [!NOTE]
>
> The **HIP side** of Scan & Share — receiving a scanned token at the facility counter — is a different integration. If your product also runs the facility's software, see [On-Share](/api-sdk/hie-cm/scan-and-share/scan-on-share) and the [Scan and Share Token Received](/docs/hie-cm/webhooks/hip-scan-and-share) webhook.

> **[M1 — ABHA Web SDK](/api-sdk/hie-cm/sdks/web-sdk/abha-sdk/abha-s\&s)**
>
> Scan & Share is also available as a drop-in SDK component, including the QR scanner.


# 7 · PHR Webhooks
Source: https://developer.eka.care/docs/hie-cm/phr/webhooks

Every asynchronous event a PHR app's cloud must handle, in one list.

ABDM is asynchronous. Discovery results, consent decisions and new-record notifications never come back on the request you made — they arrive later, on your webhook endpoint. A PHR app that only does request/response will silently miss records.

> [!NOTE]
>
> There is no self-service API to register an ABDM webhook URL. Share your endpoint with EKA (console or support) before you begin sandbox testing.

Every payload is signed. Verify the `Eka-Webhook-Signature` header before trusting it — see [Webhook Signature](/docs/webhooks/webhook-signature).

## Identity

| Event | What it means | Reference |
| - | - | - |
| `abha.created` | An ABHA address was successfully created. Provision the patient in your database from here rather than the client response. | [ABHA Address Created](/docs/hie-cm/webhooks/abha-created) |

## Locker & subscriptions

| Event | What it means | Reference |
| - | - | - |
| `abha.locker_created` | Health locker set up. Carries `auto_approval_id` and `subscription_id` — store both. | [Locker Created](/docs/hie-cm/webhooks/locker-created) |
| `abha.subscription_modified` | Subscription period, categories or status changed. | [Subscription Updated](/docs/hie-cm/webhooks/subscription-modify) |
| `abha.subscription_notify` | A HIP linked a new care context for this patient. Metadata only — raise consent to read it. | [New Care Context Linked](/docs/hie-cm/webhooks/subscription-notify) |

## Consent & data

| Event | What it means | Reference |
| - | - | - |
| `abha.consent_update` | A consent request changed state (granted, denied, expired, revoked). | [Consent Update](/docs/hie-cm/webhooks/consent-update) |
| `abha.hiu_data_push` | A HIP pushed the encrypted FHIR bundle you asked for. Only if you manage data yourself. | [Health Data Received from HIP](/docs/hie-cm/webhooks/hiu-data-push) |

## Records you store yourself

| Event | What it means | Reference |
| - | - | - |
| `rec.uploaded` | A patient-uploaded document finished processing. | [Record Uploaded](/docs/health-records/record-uploaded-webhook) |
| `rec.refresh` | The patient's record list changed and should be refetched. | [Record Refresh](/docs/health-records/record-refresh-webhook) |

## Turning events into patient notifications

Most of these events are only useful if the patient hears about them. Register the patient's device once, and push from your cloud when a webhook lands.

| Purpose | API |
| - | - |
| Register a device for push | [Add Device](/api-sdk/health-records/notifications/add-device) |
| Remove a device | [Delete Device](/api-sdk/health-records/notifications/delete-device) |
| Configure your FCM credentials | [FCM Credentials](/api-sdk/health-records/notifications/fcm-creds) |

## Also HIP? Then add these

A PHR app that stores patient-uploaded records is a HIP, and if you serve that data yourself rather than letting EKA serve it, you must handle the HIP-side events too.

| Event | Reference |
| - | - |
| `abha.link_care_context` | [Care Context Linking Status](/docs/hie-cm/webhooks/link-care-context) |
| `abha.hip_data_fetch` | [Health Data Requested by HIU](/docs/hie-cm/webhooks/hip-data-fetch) |
| Discovery request received | [Discovery Request Received](/docs/hie-cm/webhooks/discover-care-context) |
| Link initiation — generate OTP | [Link Initiation](/docs/hie-cm/webhooks/discover-link-init) |
| Link confirmation — verify OTP | [Link Confirmation](/docs/hie-cm/webhooks/discover-link-confirm) |
| Scan & Share token received | [Scan and Share Token Received](/docs/hie-cm/webhooks/hip-scan-and-share) |

> [!NOTE]
>
> If you pass FHIR data in the `data` field of the [Link API](/api-sdk/hie-cm/care-contexts/link/hip-linking), or upload via the [Upload API](/api-sdk/health-records/obtain-authorization), EKA serves the data on your behalf and `abha.hip_data_fetch` is never sent to you.


# Overview
Source: https://developer.eka.care/docs/hie-cm/profile/getting-started



The Profile API provides a set of endpoints for managing and accessing user profile information.
The API is designed to be allowing users to retrieve and update their profile details as well as access
associated assets like QR codes.

### ABHA Profile Management:

1. **Get the ABHA QR**

   The ABHA QR code provides a quick and efficient way to share and access ABHA profile details.
   Healthcare providers can scan the code to retrieve your ABHA ID and other vital information directly,
   streamlining processes like patient identification, medical history retrieval, and consent management.

2. **Fetching the ABHA Profile:**

   The API allows to retrieve comprehensive information from a user's ABHA profile.
   This includes personal details like name, date of birth, gender, and contact information, as well as other critical
   data linked to the ABHA ID.

3. **Deleting an ABHA Profile:**

   Deleting an ABHA profile is a significant and irreversible action. When a profile is deleted, all associated
   documents, vital records, and any related data are permanently removed from the system. This means the user will
   lose access to their ABHA ID and any linked medical history, with no option for recovery.

4. **Updating an ABHA Profile:**

   Updating an ABHA profile comes with certain conditions depending on how the profile was verified.

   * If the profile is Aadhaar-based, specific details such as the first\_name, gender, and date\_of\_birth cannot be modified.
     These fields are locked to ensure the accuracy and integrity of KYC (Know Your Customer) information.
   * However, for profiles created or verified through mobile OTP, most of the profile details can be updated.

> [!NOTE]
>
> User Authorization will be required for all these operations.

**1. Retrieve ABHA QR Code Data**

Use the [ABHA QR Code](/api-sdk/hie-cm/profile/cards/qr-code) API to retrieve the data
needed for displaying the ABHA QR code.

**2. Fetch the ABHA Card**

Use the [Fetch ABHA Card](/api-sdk/hie-cm/profile/cards/abha-card) API to retrieve the
user's ABHA card as an image file.

**3. Fetch ABHA Profile Details**

Use the [Profile Details](/api-sdk/hie-cm/profile/details/profile-details) API to fetch
and display personalized information from the user's ABHA profile.

**4. Update ABHA Profile**

Use the [Update Profile](/api-sdk/hie-cm/profile/details/update-profile) API to update
the user's ABHA profile details, ensuring that their information is accurate and up-to-date.

**5. Delete ABHA Profile**

Use the [Delete Profile](/api-sdk/hie-cm/profile/details/delete) API to remove the specified
ABHA profile from the system, including all associated documents, vital records, and related data.


# Overview
Source: https://developer.eka.care/docs/hie-cm/providers/getting-started



### Providers/Health Information Providers (HIP)

The entity that holds or manages the patient’s health records.
Users can retrieve detailed information about healthcare providers,
including their care contexts, and search for providers by name to find and lint their care contexts/documents.
\[!NOTE] User Authorization will be required for all these operations.

**1. Retrieve Provider Details**

Use the [Provider Details](/api-sdk/hie-cm/providers/provider) API to retrieve
comprehensive information about a specific provider, including a detailed list of care contexts available
for the user.

**2. Search for Providers**

Use the [Search Providers](/api-sdk/hie-cm/providers/search/providers) API to search
for providers by name or other criteria, facilitating easier access to healthcare professionals.


# Quickstart
Source: https://developer.eka.care/docs/hie-cm/quickstart

Create a sandbox ABHA from these docs in about ten minutes, without writing code.

Create a sandbox ABHA from these docs in about ten minutes, without writing code. Every step runs from the **Try it** playground on its API page.

## In short

* Get an access token once, then paste it into the **Bearer** field of each playground.
* Six calls: log in, send the Aadhaar number, verify the OTP, pick an address, check it is free, create the ABHA.
* You end with a 14-digit ABHA number, an ABHA address and Eka's patient id, `eka.oid`.
* There is no encryption step. You send the Aadhaar number as plain text and Eka handles ABDM's encryption for you.
* This page walks one case: the patient has no ABHA, and the mobile you send is the one linked to their Aadhaar.

## Create your first ABHA here

Enter your sandbox credentials and a test Aadhaar below; each step calls the sandbox from this page and shows the request and response.

<ol aria-label="Steps to create an ABHA" />

Sandbox: [https://api.dev.eka.care](https://api.dev.eka.care)
Start again

Prefer to call each API yourself? The same calls, step by step:

## Before you start

* **Sandbox credentials.** Create an Eka account, then create an API client in the [Eka Developer Console](https://console.eka.care) under **Manage API Credentials**. Copy the `client_id` and `client_secret`. See [Sandbox credentials](/docs/hie-cm/testing#sandbox-credentials).&#x20;
* **The sandbox server.** Calls go to `https://api.dev.eka.care`. If a playground offers a server choice, pick **Stage/Sandbox**.
* **A sandbox Aadhaar number, and the phone registered to it.** The OTP goes to that phone.&#x20;

## 1. Get an access token

This logs your client in and returns the token every later call sends.

Open [Connect Login](/api-sdk/auth/client-login) and press **Try it**. Paste this body and send it.

```json theme={null}
{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}
```

Copy `access_token` from the response. On each page below, paste it into the playground's **Authorization** Bearer field. `expires_in` is the token's lifetime in seconds. If a call returns `401`, run this step again.

> **Prefer curl?**
>
> ```bash theme={null}
> curl -X POST "https://api.dev.eka.care/connect-auth/v1/account/login" \
>   -H "Content-Type: application/json" \
>   -d '{"client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET"}'
> ```

## 2. Send the Aadhaar number

ABDM sends an OTP to the mobile linked to this Aadhaar.

Open [Generate OTP](/api-sdk/hie-cm/enrollment/aadhaar/initiate-registration) and press **Try it**.

```json theme={null}
{
  "aadhaar_number": "YOUR_AADHAAR"
}
```

Copy `txn_id`. `hint` shows the masked number the OTP went to.

> **Prefer curl?**
>
> ```bash theme={null}
> curl -X POST "https://api.dev.eka.care/abdm/na/v1/registration/aadhaar/init" \
>   -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{"aadhaar_number": "YOUR_AADHAAR"}'
> ```

## 3. Verify the Aadhaar OTP

This proves the patient's identity against Aadhaar and sets the mobile the ABHA will use.

Open [Verify OTP](/api-sdk/hie-cm/enrollment/aadhaar/verify-otp) and press **Try it**. Use the Aadhaar-linked mobile for `mobile`.

```json theme={null}
{
  "txn_id": "TXN_ID_FROM_STEP_2",
  "otp": "YOUR_OTP",
  "mobile": "YOUR_MOBILE"
}
```

Copy the new `txn_id`. Check that `skip_state` is `abha_create` and `abha_profiles` is empty. Any other result is a branch covered on the [workflow page](/docs/hie-cm/workflows/create-abha-aadhaar-otp).

> **Prefer curl?**
>
> ```bash theme={null}
> curl -X POST "https://api.dev.eka.care/abdm/na/v1/registration/aadhaar/verify" \
>   -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{"txn_id": "TXN_ID_FROM_STEP_2", "otp": "YOUR_OTP", "mobile": "YOUR_MOBILE"}'
> ```

## 4. Get suggested ABHA addresses

Eka returns addresses that are free to take. This call has no body.

Open [Suggest ABHA Address](/api-sdk/hie-cm/commons/suggest-abha-address) and press **Try it**. Set the `transactionId` query parameter to `TXN_ID_FROM_STEP_3`.

Copy one entry from `suggestions`. You can type your own address instead.

> **Prefer curl?**
>
> ```bash theme={null}
> curl "https://api.dev.eka.care/abdm/na/v1/registration/suggest?transactionId=TXN_ID_FROM_STEP_3" \
>   -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
> ```

## 5. Check the address is free

This confirms nobody holds the address before you create it.

Open [Does ABHA Address Exist](/api-sdk/hie-cm/commons/does-health-id-exist) and press **Try it**.

```json theme={null}
{
  "abha_address": "YOUR_ABHA_ADDRESS"
}
```

`exists` should be `false`. If it is `true`, pick another address and check again.

> **Prefer curl?**
>
> ```bash theme={null}
> curl -X POST "https://api.dev.eka.care/abdm/na/v1/registration/phr/check" \
>   -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{"abha_address": "YOUR_ABHA_ADDRESS"}'
> ```

## 6. Create the ABHA

This registers the ABHA with ABDM. It creates a real sandbox account, so send it once.

Open [Create](/api-sdk/hie-cm/enrollment/aadhaar/create-abha) and press **Try it**. Send the `txn_id` from step 3.

```json theme={null}
{
  "txn_id": "TXN_ID_FROM_STEP_3",
  "abha_address": "YOUR_ABHA_ADDRESS"
}
```

Copy `profile.abha_number`, `profile.abha_address` and `eka.oid`. Later calls for this patient send `eka.oid` in the `X-Pt-Id` header.

> **Prefer curl?**
>
> ```bash theme={null}
> curl -X POST "https://api.dev.eka.care/abdm/na/v1/registration/aadhaar/create-phr" \
>   -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{"txn_id": "TXN_ID_FROM_STEP_3", "abha_address": "YOUR_ABHA_ADDRESS"}'
> ```

## How this fits your product

These calls are the identity step of [Register a walk-in patient and link the visit](/docs/hie-cm/journeys/hip-register-patient-and-link-visit), the registration desk journey for a HIP. They cover [Milestone 1](/docs/hie-cm/flows/m1). Linking the visit to the new ABHA is [Milestone 2](/docs/hie-cm/flows/m2).

## If a call fails

Start with [By symptom](/docs/hie-cm/errors#by-symptom) on the errors page. It covers OTPs that never arrive, lockouts and `401` responses. For each failure in this flow, the [workflow's failure table](/docs/hie-cm/workflows/create-abha-aadhaar-otp#when-it-fails) says what to do. Which code each call returns is not yet confirmed, so log the code you actually receive.

## Next

* [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp): the other branches, resend, the `abha.created` webhook and the state to persist.
* [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip): link the patient's visit to the new ABHA.
* [Testing](/docs/hie-cm/testing): the happy path for every journey before you go live.


# Overview
Source: https://developer.eka.care/docs/hie-cm/registration/intro



### ABHA Address

An ABHA Address is a memorable username that allows users to access and manage their health records digitally and share them with various healthcare providers.
It follows the format `sudev@abdm` and is essential identifier for all ABDM transactions.

### ABHA Number

The ABHA Number is a unique 14-digit identifier issued after a thorough **KYC process**.
Multiple ABHA Address can be attached to a ABHA Number.

## Creating an ABHA Number with Aadhaar

ABHA Numbers can be generated by authenticating with Aadhaar. Aadhaar serves as the KYC here.

**1. Enter the Aadhaar Number**

Use the [Initiate Aadhaar Registration](/api-sdk/hie-cm/enrollment/aadhaar/initiate-registration) endpoint to start the Aadhaar registration process.

**2. Verify Aadhaar OTP**

Use the [Verify Aadhaar OTP](/api-sdk/hie-cm/enrollment/aadhaar/verify-otp) endpoint to verify the OTP generated for Aadhaar registration.

**3. Verify Mobile Number (Optional)**

If the mobile number provided in the second step differs from the one linked to Aadhaar, use the [Verify New Mobile Number](/api-sdk/hie-cm/enrollment/aadhaar/mobile-verify) endpoint to verify the new mobile number.

**4. Create ABHA Address**

Use the [Create ABHA Address](/api-sdk/hie-cm/enrollment/aadhaar/create-abha) endpoint to generate a new ABHA address.

## Creating ABHA Address using Mobile

**1. Enter Mobile Number**

Use the [Initiate Mobile Registration](/api-sdk/hie-cm/enrollment/mobile/init) endpoint to start the registration process for a mobile number.

**2. Verify Mobile OTP**

Use the [Verify Mobile OTP](/api-sdk/hie-cm/enrollment/mobile/verify) endpoint to verify the OTP sent to the mobile number.

The response from the verification will include the user's existing ABHA Address associated with the mobile number. In the next step, the user can either create a new ABHA Address or log in to the existing ABHA Address.

**3. Create ABHA Address**

* To create a new ABHA Address use [Create ABHA Address](/api-sdk/hie-cm/enrollment/mobile/create).

## Logging into ABHA Address

**1. Initiate Login**

Use the [Login Initiation](/api-sdk/hie-cm/login/init) endpoint to start the login process by entering the mobile number.

**2. Verify Login OTP**

Use the [Verify Login OTP](/api-sdk/hie-cm/login/verify) endpoint to verify the OTP sent to the registered mobile number.

After successful verification, the response will include the user's existing ABHA Address associated with the mobile number.

If the `method` in the **Login init API** is set to **"abha\_address"**, then this API itself will complete the login process, and no further API call is required.

**3. Login to ABHA Address**

Use the [Login](/api-sdk/hie-cm/login/login) endpoint to authenticate and access the ABHA Address.

### Skip State Enum

The **Skip State Enum** in the API response determines the next screen the user should see:

* **abha\_end** – This state indicates that the ABHA registration or login process is complete, and no further action is needed.
* **confirm\_mobile\_otp** – This occurs when a user verifies their Aadhaar OTP but enters a mobile number that is not linked to their Aadhaar. In this case, the user should be taken to the mobile verification page.
* **abha\_select** – If the state is `abha_select`, the user should be taken to the login page, where they have multiple ABHA addresses. They can choose one to proceed with the login.
* **abha\_create** – This indicates that no ABHA address has been created yet, so the user should be directed to the ABHA creation page.


# Overview
Source: https://developer.eka.care/docs/hie-cm/scan-and-share/getting-started



Patients can scan a **Health Facility QR code** available at the facility registration counter.

The User/Patient can share their **ABHA Profile** with the HMIS/LIMS software used by the Health Facility by scanning
a facility specific QR Code. This enables the patients to instantly register themselves, share their ABHA address
and optionally obtain a token number from the facility.

### Get Scan & Share Token

The user can scan a QR code from a hospital or clinic to generate a Scan & Share token, using the extracted IDs
and device location. The response includes HIP details, token expiry, and an option to display the token.

**1. Generate Scan & Share Token**

Use the [Request to generate token](/api-sdk/hie-cm/scan-and-share/phr-scan-share) API to
scan a QR code from a hospital or clinic, then [Get appointment token](/api-sdk/hie-cm/scan-and-share/phr-scan-share-token)
to fetch the facility's response.


# Overview
Source: https://developer.eka.care/docs/hie-cm/session/getting-started



## User Session

Upon registration or creation of an ABHA, a user session is maintained with the ABHA Gateway.
This session expires after a certain period. When the session expires, APIs requiring ABHA Gateway authentication will return a `491` HTTP response code.

A ABHA Gateway Session creation requires a Mobile OTP (One-Time Password) Authentication.

**1. Generate Mobile OTP**

Use the [Initiate Session: Generate Mobile OTP](/api-sdk/hie-cm/session/init) endpoint to start a new session by generating a mobile OTP.
This session is linked to the provided ABHA address, and a `txn_id` (Transaction ID) will be returned for tracking and verification.

**2. Verify Mobile OTP**

Use the [Verify Mobile OTP: Get User Session Token](/api-sdk/hie-cm/session/verify) endpoint to verify the OTP generated in the previous step.
Provide the OTP and `txn_id` associated with the session to receive an access token for further authentication.

***

## Check User Session Status

Before initiating OTP authentication, clients **should first check whether a valid ABHA Gateway session already exists**.

Use the **Session Status API** to get the current authentication status of the user.

* If a valid session exists, continue using the existing session token
* If no valid session exists or the session has expired, users should call:
  * **Generate Mobile OTP**
  * **Verify Mobile OTP**


# Testing
Source: https://developer.eka.care/docs/hie-cm/testing

Run every ABDM Connect journey against sandbox before you go live.

Run the happy path of every journey you support against sandbox before you go live. Each item below links the workflow's own Test it checklist, which also covers the failure cases.

## In short

* Run the happy path of every journey you support against sandbox before you go live.
* Sandbox is `https://api.dev.eka.care`; production is `https://api.eka.care`.
* Log in with your API client to get an access token, and refresh it on a `401`.
* Share a webhook endpoint that sandbox can reach with Eka before you start.
* Each item links the workflow's own Test it checklist.

## Sandbox

| Setting | Value |
| - | - |
| Sandbox base URL | `https://api.dev.eka.care` |
| Production base URL | `https://api.eka.care` |
| Authentication | Bearer token in the `Authorization` header on every call |

The base URLs are the spec's `Stage/Sandbox` and `Production` servers.

## Sandbox credentials

1. Create an Eka account and a workspace. See [Setting up your Eka account](/api-sdk/auth/getting-started#setting-up-your-eka-account).
2. In the [Eka Developer Console](https://console.eka.care), open **Manage API Credentials** and create an API client. Copy the `client_id` and `client_secret`. The secret is shown once.
3. Log in with [Client login](/api-sdk/auth/client-login) to get an access token and a refresh token.
4. When a call returns `401`, the access token has expired. Get a new one with [Refresh token](/api-sdk/auth/refresh-token-v2).

You also need a webhook endpoint that sandbox can reach. Share it with Eka before you start, and allowlist the staging IP addresses if your network restricts inbound traffic. See [Webhooks](/docs/hie-cm/webhooks).

## Test data

## Happy paths

### Register a walk-in patient and link the visit

[Journey](/docs/hie-cm/journeys/hip-register-patient-and-link-visit)

* [ ] [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha#test-it), for a patient who has one
* [ ] [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp#test-it), for a patient who has none
* [ ] [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip#test-it)
* [ ] Optional: [Create an ABHA address with mobile OTP](/docs/hie-cm/workflows/create-abha-mobile-otp#test-it)
* [ ] Optional: [Create an ABHA with face authentication](/docs/hie-cm/workflows/create-abha-face-auth#test-it)
* [ ] Optional: [Receive a scanned profile as a HIP](/docs/hie-cm/workflows/hip-scan-and-share#test-it)
* [ ] If you keep the clinical data yourself: [Serve records on a fetch request](/docs/hie-cm/workflows/serve-data-on-fetch#test-it)

### Let a patient claim their old records

[Journey](/docs/hie-cm/journeys/hip-answer-discovery)

* [ ] [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link#test-it)
* [ ] If you keep the clinical data yourself: [Serve records on a fetch request](/docs/hie-cm/workflows/serve-data-on-fetch#test-it)

### Fetch a patient's records with consent

[Journey](/docs/hie-cm/journeys/hiu-fetch-records-with-consent)

* [ ] [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent#test-it)
* [ ] [Receive and decrypt records as a HIU](/docs/hie-cm/workflows/hiu-receive-data#test-it)

### Gather every health record in a PHR app

[Journey](/docs/hie-cm/journeys/phr-patient-aggregates-records)

* [ ] [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp#test-it) or [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha#test-it)
* [ ] [Hold the ABHA Gateway session](/docs/hie-cm/workflows/hold-gateway-session#test-it)
* [ ] [Manage the ABHA profile and KYC](/docs/hie-cm/workflows/manage-profile-and-kyc#test-it)
* [ ] [Discover and link records from a facility](/docs/hie-cm/workflows/phr-discover-and-link#test-it)
* [ ] [List a patient's linked records](/docs/hie-cm/workflows/phr-list-records#test-it)
* [ ] [Approve, deny or revoke a consent in a PHR app](/docs/hie-cm/workflows/phr-act-on-consent#test-it)
* [ ] [Set up the patient's health locker](/docs/hie-cm/workflows/set-up-health-locker#test-it)
* [ ] [Share a profile at a facility counter](/docs/hie-cm/workflows/phr-scan-and-share#test-it)

### Onboard a facility and its professionals to ABDM

[Journey](/docs/hie-cm/journeys/facility-onboard-to-abdm)

* [ ] [Create an HPR ID with Aadhaar OTP](/docs/hie-cm/workflows/create-hpr-id#test-it)
* [ ] [Register and onboard a facility](/docs/hie-cm/workflows/register-hfr#test-it)
* [ ] Optional: [Log in to HPR with a mobile OTP](/docs/hie-cm/workflows/hpr-mobile-login#test-it)

### Book an in-person doctor visit over UHI

[Journey](/docs/uhi/journeys/uhi-book-physical-consultation)

* [ ] [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha#test-it)
* [ ] [Book a physical consultation over UHI](/docs/uhi/workflows/uhi-book-consultation#test-it)
* [ ] Optional: [Search blood banks over UHI](/docs/uhi/workflows/blood-bank-search#test-it)

### Pay an open bill by scanning the counter QR

[Journey](/docs/uhi/journeys/uhi-scan-and-pay)

* [ ] [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha#test-it)
* [ ] [Pay an open order with Scan and Pay](/docs/uhi/workflows/scan-and-pay#test-it)

## Before go-live

* [ ] Every webhook your workflows consume arrives, its signature verifies, and your endpoint replies `200` within 5 seconds.
* [ ] Your error handling matches [Error codes](/docs/hie-cm/errors), including the By symptom section.


# Webhooks
Source: https://developer.eka.care/docs/hie-cm/webhooks

Every event ABDM Connect sends to your server, when it fires, and which workflow handles it.

ABDM is asynchronous. Many results never come back on the request you made. Eka sends them to your webhook endpoint as events. This page lists all 18 ABDM Connect events. Each event's own page carries its payload.

## In short

* Eka sends results that do not come back on your request to your webhook endpoint as events.
* Your endpoint is a public HTTPS URL that accepts `POST` requests.
* Every event has the same envelope; the fields inside `data` differ per event.
* Verify `Eka-Webhook-Signature` with HMAC-SHA256 when you gave a signing key.
* Reply `200` within 5 seconds, then do the work.

## Delivery, signature and acknowledgement

### Registering your endpoint

Your endpoint is a public HTTPS URL that accepts `POST` requests. See [Getting started with webhooks](/api-sdk/webhooks/getting-started) and [Register a webhook](/api-sdk/webhooks/register-webhook).

The [PHR webhooks guide](/docs/hie-cm/phr/webhooks) says there is no self-service API to register an ABDM webhook URL, and that you share your endpoint with Eka (console or support) before sandbox testing.&#x20;

If your network restricts inbound traffic, allowlist Eka's production and staging IP addresses listed on [Register a webhook](/api-sdk/webhooks/register-webhook).

### What every request carries

Every event is a `POST` with two headers:

* `Content-Type`: `application/json`
* `Eka-Webhook-Signature`: present when you gave a signing key at registration

The body has the same envelope for every event: `service`, `event` (the event name), `event_time`, `transaction_id`, `timestamp`, `business_id`, `client_id`, and `data`. The fields inside `data` differ per event; see each event's page.

### Verifying the signature

Eka signs the payload when you provide a signing key while registering the webhook. Without a key, Eka still sends the event, unsigned. You can use one key for all webhooks or a unique key per webhook.

The ABDM Connect spec marks `Eka-Webhook-Signature` as required on every event, so whether Eka ever delivers an unsigned event is not yet confirmed.&#x20;

The header has the form `t=TIMESTAMP,v1=SIGNATURE`. To verify it:

1. Read `t` and `v1` from `Eka-Webhook-Signature`.
2. Compute an HMAC-SHA256 over `TIMESTAMP.PAYLOAD` with your signing key.
3. Compare your result with `v1`. If they match, the event came from Eka and was not changed.

To block replayed events, reject a request whose `t` is older than your tolerance, for example 3 minutes. [Webhook signature](/docs/webhooks/webhook-signature) has example code.

### Acknowledging

Reply `200` within 5 seconds. Eka retries on any other status. Reply first, then do the work: decrypting records, building FHIR bundles or calling back Eka.

## ABHA

### `abha.created`

Fires when an ABHA address is created. Provision the patient in your database from this event, not only from the API response.

* Payload: [ABHA Address Created](/docs/hie-cm/webhooks/abha-created)
* Consumed by: [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp), [Create an ABHA address with mobile OTP](/docs/hie-cm/workflows/create-abha-mobile-otp), [Create an ABHA with face authentication](/docs/hie-cm/workflows/create-abha-face-auth)

## Health Information Provider (HIP)

### `abha.link_care_context`

Fires after you call the [Care Context Link API](/api-sdk/hie-cm/care-contexts/link/hip-linking), with the result. `data.status` is `LINKED` when the care context is registered with ABDM, or `ERRORED` with the reason in `data.error`.

* Payload: [Care Context Linking Status](/docs/hie-cm/webhooks/link-care-context)
* Consumed by: [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip)

### `abha.care_context_discover`

Fires when a patient asks your facility, from a PHR app, for records not yet linked to their ABHA. Search your system with the details in `data` and answer with [On Discover](/api-sdk/hie-cm/care-contexts/discover/on_discover).

* Payload: [Discovery Request Received](/docs/hie-cm/webhooks/discover-care-context)
* Consumed by: [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link)

### `abha.care_context_discover_link_init`

Fires when the patient chooses which discovered records to link. Generate an OTP, send it to the patient, and call [On Link Init](/api-sdk/hie-cm/care-contexts/discover/link_on_init).

* Payload: [Link Initiation - Generate OTP](/docs/hie-cm/webhooks/discover-link-init)
* Consumed by: [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link)

### `abha.context_discover_link_confirm`

Fires when the patient submits the OTP. Check it against the OTP you sent, then call [On Link Confirm](/api-sdk/hie-cm/care-contexts/discover/link_on_confirm) with the care contexts to link.

* Payload: [Link Confirmation - Verify OTP](/docs/hie-cm/webhooks/discover-link-confirm)
* Consumed by: [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link)

### `abha.hip_data_fetch`

Fires when a Health Information User (HIU) requests data for care contexts you linked. You receive it only if you do not store the health data on Eka. Encrypt the FHIR bundles with the `key_information` in the payload and push them with [Care Context Data On-Fetch](/api-sdk/hie-cm/care-contexts/data-on-fetch).

* Payload: [Health Data Requested by HIU](/docs/hie-cm/webhooks/hip-data-fetch)
* Consumed by: [Serve records on a fetch request](/docs/hie-cm/workflows/serve-data-on-fetch)

### `abha.hip_profile_share`

Fires when a patient scans your facility's QR code with a PHR app and shares their ABHA profile for an OPD token. `data.hip_code` is the counter id.

* Payload: [Scan and Share Token Received](/docs/hie-cm/webhooks/hip-scan-and-share)
* Consumed by: [Receive a scanned profile as a HIP](/docs/hie-cm/workflows/hip-scan-and-share)

## Health Information User (HIU) and consent

### `abha.consent_update`

Fires whenever a consent changes, with the updated details. Expect it more than once for the same consent request; treat the latest status as current.

* Payload: [Consent Update](/docs/hie-cm/webhooks/consent-update)
* Consumed by: [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent), [Approve, deny or revoke a consent in a PHR app](/docs/hie-cm/workflows/phr-act-on-consent)

### `abha.hiu_data_push`

Fires when a HIP pushes encrypted health data for a consent you raised. You receive it only if you manage the data on your side.

* Payload: [Health Data Received from HIP](/docs/hie-cm/webhooks/hiu-data-push)
* Consumed by: [Receive and decrypt records as a HIU](/docs/hie-cm/workflows/hiu-receive-data)

## Health locker

### `abha.locker_created`

Fires when a health locker is set up. Store `data.auto_approval_id` and `data.subscription_id`.

* Payload: [Locker Created](/docs/hie-cm/webhooks/locker-created)
* Consumed by: [Set up the patient's health locker](/docs/hie-cm/workflows/set-up-health-locker)

### `abha.subscription_notify`

Fires when a HIP links a new care context to an ABHA address you hold an active subscription for.

* Payload: [New Care Context Linked (Subscription)](/docs/hie-cm/webhooks/subscription-notify)
* Consumed by: [Set up the patient's health locker](/docs/hie-cm/workflows/set-up-health-locker)

### `abha.subscription_modified`

Fires whenever a subscription is updated.

* Payload: [Subscription Updated](/docs/hie-cm/webhooks/subscription-modify)
* Consumed by: [Set up the patient's health locker](/docs/hie-cm/workflows/set-up-health-locker)

## Unified Health Interface (UHI) bookings

Each UHI call starts a request and returns at once. The result arrives on one of these events. You can also read it with the matching `GET`.

### `doctor.search.results`

Fires with the results of [Search Doctors](/api-sdk/uhi/phys-cons/search-doctors).

* Payload: [Search Doctors](/docs/uhi/webhooks/search-doctors)
* Consumed by: [Book a physical consultation over UHI](/docs/uhi/workflows/uhi-book-consultation)

### `doctor.slot.search.results`

Fires with the results of a doctor's consultation slot search, [Search Slots](/api-sdk/uhi/phys-cons/search-slots).

* Payload: [Search Slots](/docs/uhi/webhooks/search-slots)
* Consumed by: [Book a physical consultation over UHI](/docs/uhi/workflows/uhi-book-consultation)

### `booking.init`

Fires with the result of [Init](/api-sdk/uhi/phys-cons/init): the quote, terms and payment details.&#x20;

* Payload: [Booking Init](/docs/uhi/webhooks/booking-init)
* Consumed by: [Book a physical consultation over UHI](/docs/uhi/workflows/uhi-book-consultation)

### `booking.confirm`

Fires with the result of [Confirm](/api-sdk/uhi/phys-cons/confirm): the booking confirmation and its details.

* Payload: [Booking Confirm](/docs/uhi/webhooks/booking-confirm)
* Consumed by: [Book a physical consultation over UHI](/docs/uhi/workflows/uhi-book-consultation)

### `booking.status`

Fires with the result of [Order Status](/api-sdk/uhi/phys-cons/order-status): the booking's status and details.

* Payload: [Booking Status](/docs/uhi/webhooks/booking-status)
* Consumed by: [Book a physical consultation over UHI](/docs/uhi/workflows/uhi-book-consultation)

### `booking.cancel`

Fires when a booking cancellation requested through [Cancel](/api-sdk/uhi/phys-cons/cancel) completes. `data.status` carries the result.

* Payload: [Booking Cancel](/docs/uhi/webhooks/booking-cancel)
* Consumed by: [Book a physical consultation over UHI](/docs/uhi/workflows/uhi-book-consultation)


# ABHA Address Created
Source: https://developer.eka.care/docs/hie-cm/webhooks/abha-created



Webhook event is sent on successful ABHA Address creation.

### Request

**Headers:**

* `Eka-Webhook-Signature`: `<Eka Webhook Signature>`  [Refer: Webhook Signature](/docs/webhooks/webhook-signature)
* `Content-Type`: `application/json`

**Body:**

```json theme={null}
{
    "service": "abdm",
    "event": "abha.created",
    "event_time": 1749822309,
    "transaction_id": "<webhook transaction id>",
    "timestamp": 1749825214,
    "business_id": "<partner business id>",
    "client_id": "<partner client id>",
    "data": {
        "abha_address": "shyam@abdm",
        "abha_number": "12-2345-6789-0123",
        "hip_id": "<partner hip id>",
        "oid": "<eka user id>",
        "partner_patient_id": "<partner user id>"
    }
}
```


# Consent Update
Source: https://developer.eka.care/docs/hie-cm/webhooks/consent-update

A webhook event is triggered whenever there is an update of the consent, where you receive the updated details of the consent.

A webhook event is triggered whenever there is an update of the consent, where you receive the updated details of the consent.

### Request

**Headers:**

* `Eka-Webhook-Signature`: `<Eka Webhook Signature>`  [Refer: Webhook Signature](/docs/webhooks/webhook-signature)
* `Content-Type`: `application/json`

**Body:**

```json theme={null}
{
  "service": "abha",
  "event": "abha.consent_update",
  "event_time": 1749822309,
  "transaction_id": "<webhook transaction id>",
  "timestamp": 1749825214,
  "business_id": "<partner business id>",
  "client_id": "<partner client id>",
  "data": {
    "timestamp": "<string>",
    "status": "<string>",
    "notification": {
        "consentRequestId": "<string>",
        "status": "<string>",
        "consentArtefacts": {
            "id": "<string>"
        }
    }
  }
}
```


# Discovery Request Received
Source: https://developer.eka.care/docs/hie-cm/webhooks/discover-care-context



This webhook is triggered when a user requests discovery of unlinked care contexts from your HIP. Use the provided user information (ABHA address, mobile number, name, demographics) to search for and return matching unlinked care contexts within your system.

> [!NOTE]
>
> After receiving this webhook, search your system for matching unlinked care contexts and respond by calling the [On Discover API](/api-sdk/hie-cm/care-contexts/discover/on_discover).

### Request

**Headers:**

* `Eka-Webhook-Signature`: `<Eka Webhook Signature>`  [Refer: Webhook Signature](/docs/webhooks/webhook-signature)
* `Content-Type`: `application/json`

**Body:**

```json theme={null}
{
  "service": "abdm",
  "event": "abha.care_context_discover",
  "event_time": 1750317863,
  "transaction_id": "<webhook transaction id>",
  "timestamp": 1750317863,
  "business_id": "77237637763817",
  "client_id": "77237637763817",
  "data": {
    "abha_address": "gajendrasingh5445@sbx",
    "gender": "M",
    "identifiers": [
      {
        "type": "MOBILE",
        "value": "6260413674"
      },
      {
        "type": "ABHA_NUMBER",
        "value": ""
      },
      {
        "type": "abhaAddress",
        "value": "gajendrasingh5445@sbx"
      }
    ],
    "patient_name": "Gajendra Singh",
    "request_id": "a273f8af-3b8e-42ed-8847-fbdb2e4207c3",
    "txn_id": "1fe0a9d8-6737-471a-87b4-867d45707db5",
    "year_of_birth": 2001,
    "hip_id": "<partner hip id>",
    "oid": "<eka user id>",
    "partner_patient_id": "<partner user id>"
  }
}
```


# Link Confirmation - Verify OTP
Source: https://developer.eka.care/docs/hie-cm/webhooks/discover-link-confirm



This webhook is triggered when a user submits the OTP to confirm care context linking. Validate the OTP generated during the [Link Initiation](/docs/hie-cm/webhooks/discover-link-init) step. If valid, proceed to link the care contexts.

> [!NOTE]
>
> After validating the OTP, call the [On Link Confirm API](/api-sdk/hie-cm/care-contexts/discover/link_on_confirm) with the list of care contexts to complete the linking.

### Request

**Headers:**

* `Eka-Webhook-Signature`: `<Eka Webhook Signature>`  [Refer: Webhook Signature](/docs/webhooks/webhook-signature)
* `Content-Type`: `application/json`

**Body:**

```json theme={null}
{
  "service": "abdm",
  "event": "abha.context_discover_link_confirm",
  "event_time": 1750317942,
  "transaction_id": "<webhook transaction id>",
  "timestamp": 1750317942,
  "business_id": "77237637763817",
  "client_id": "77237637763817",
  "data": {
    "linkRefNumber": "temp",
    "request_id": "546f3465-30fa-4894-89f4-b884a2683fdf",
    "token": "111111",
    "hip_id": "<partner hip id>",
    "oid": "<eka user id>",
    "partner_patient_id": "<partner user id>"
  }
}
```


# Link Initiation - Generate OTP
Source: https://developer.eka.care/docs/hie-cm/webhooks/discover-link-init



This webhook is triggered when a user initiates linking of discovered care contexts. Upon receiving this webhook, generate an OTP, send it to the user, and save the care contexts for further processing.

> [!NOTE]
>
> After generating and sending the OTP, call the [On Link Init API](/api-sdk/hie-cm/care-contexts/discover/link_on_init) to notify Eka that the OTP has been dispatched.

### Request

**Headers:**

* `Eka-Webhook-Signature`: `<Eka Webhook Signature>`  [Refer: Webhook Signature](/docs/webhooks/webhook-signature)
* `Content-Type`: `application/json`

**Body:**

```json theme={null}
{
  "service": "abdm",
  "event": "abha.care_context_discover_link_init",
  "event_time": 1750317906,
  "transaction_id": "<webhook transaction id>",
  "timestamp": 1750317906,
  "business_id": "77237637763817",
  "client_id": "77237637763817",
  "data": {
    "abha_address": "gajendrasingh5445@sbx",
    "patient": [
      {
        "care_contexts": [
          {
            "reference_number": "CC101"
          }
        ],
        "count": 1,
        "hi_type": "OPConsultation",
        "id": "",
        "ref_num": "temp"
      }
    ],
    "hip_id": "<partner hip id>",
    "oid": "<eka user id>",
    "partner_patient_id": "<partner user id>",
    "request_id": "7234a162-1c76-486d-be8c-22cdf5c5007f",
    "txn_id": "1fe0a9d8-6737-471a-87b4-867d45707db5"
  }
}
```


# Health Data Requested by HIU
Source: https://developer.eka.care/docs/hie-cm/webhooks/hip-data-fetch



This webhook is sent when an HIU requests health data for care contexts that you have previously linked using the [Care Context Link API](/api-sdk/hie-cm/care-contexts/link/hip-linking).

> [!NOTE]
>
> You will only receive this webhook if you are **not** storing the health data on Eka servers. If you use Eka's Upload API to store records, Eka handles data sharing automatically.

**What to do when you receive this webhook:**

1. Prepare an ABDM-compliant FHIR bundle for each care context listed in the `care_contexts` array.
2. Encrypt the FHIR data using the `key_information` provided in the webhook payload (ECDH-based encryption).
3. Push the encrypted data to the HIU using the [Care Context Data On-Fetch API](/api-sdk/hie-cm/care-contexts/data-on-fetch). Use the `transaction_id` from this webhook in the on-fetch request.

### Request

**Headers:**

* `Eka-Webhook-Signature`: `<Eka Webhook Signature>`  [Refer: Webhook Signature](/docs/webhooks/webhook-signature)
* `Content-Type`: `application/json`

**Body:**

```json theme={null}
{
    "service": "abdm",
    "event": "abha.hip_data_fetch",
    "event_time": 1749822309,
    "transaction_id": "<webhook transaction id>",
    "timestamp": 1749825214,
    "business_id": "<partner business id>",
    "client_id": "<partner client id>",
    "data": {
        "abha_address": "shyam@abdm",
        "oid": "<eka user id>",
        "partner_patient_id": "<partner patient id>",
        "hip_id": "<partner hip id>",
        "transaction_id": "",
        "care_contexts": [
            "care_context_1",
            "care_context_2"
        ],
        "key_information": {
            "crypto_alg": "ECDH",
            "curve": "Curve25519",
            "dh_public_key": {
                "expiry": "2026-03-01T12:00:00.000Z",
                "parameters": "Curve25519/32byte random key",
                "key_value": "base64-encoded public key"
            },
            "nonce": "base64-encoded 32-byte nonce"
        },
        "hi_types": [
            "OPConsultation",
            "Prescription"
        ]
    }
}
```

### Field Descriptions

* **`data`**: Contains additional details related to the event.
  * **`hi_types`**: Health information types requested by HIU
    * Available options: `OPConsultation`, `Prescription`, `DischargeSummary`, `DiagnosticReport`, `ImmunizationRecord`, `HealthDocumentRecord`, `WellnessRecord`

  * **`key_information`** : Contains the cryptographic key material and related parameters required for secure ECDH-based key exchange between HIU and HIP.
    * `crypto_alg` The cryptographic algorithm used for key exchange (e.g., "ECDH").
    * `curve` The elliptic curve used in ECDH key generation (e.g., "Curve25519", "P-256").
    * `dh_public_key` Object containing the HIU’s public key and related metadata:
      * `expiry` The expiration timestamp (in ISO 8601 format) indicating how long the public key is valid.
      * `parameters` Additional parameters related to the ECDH key (optional or curve-specific).
      * `key_value` The base64-encoded public key value generated by the HIU.
    * `nonce` A 32-byte random nonce (Base64-encoded) generated by the HIU, used to ensure uniqueness in the session key derivation.


# Scan and Share Token Received
Source: https://developer.eka.care/docs/hie-cm/webhooks/hip-scan-and-share



Webhook callback is sent to the client when a patient shares their ABHA token via Scan and Share for OPD token generation.

### Request

**Headers:**

* `Eka-Webhook-Signature`: `<Eka Webhook Signature>`  [Refer: Webhook Signature](/docs/webhooks/webhook-signature)
* `Content-Type`: `application/json`

**Body:**

```json theme={null}
{
    "service": "abdm",
    "event": "abha.hip_profile_share",
    "event_time": 1749822309,
    "transaction_id": "<webhook transaction id>",
    "timestamp": 1749825214,
    "business_id": "<partner business id>",
    "client_id": "<partner client id>",
    "data": {
        "abha_address": "shyam@abdm",
        "abha_number": "12-2345-6789-0123",
        "hip_id": "<partner hip id>",
        "oid": "<eka user id>",
        "partner_patient_id": "<partner user id>",
        "hip_code": "<counter id>",
        "req_id": "<request id>"
    }
}
```

### Field Descriptions

* **`data`**: Contains additional details related to the callback response sent to client.
  * **`hip_code`**: Contains the Counter ID.


# Health Data Received from HIP
Source: https://developer.eka.care/docs/hie-cm/webhooks/hiu-data-push



Webhook event is sent when an external HIP pushes encrypted health data to your HIU.

The Health Information User (HIU) can initiate a consent request through the [Consent-API](/api-sdk/hie-cm/consents/consent-create) to get care context data. Once consent is validated, the Health Information Provider (HIP) sends the encrypted health data to the HIU.

### Large pushes

A webhook has a size limit, and a single HIP push can be larger than that. Every entry therefore carries a `content_ref`, and when the webhook would be too large, `content` is sent as an empty string for some entries.

**What to do when you receive this webhook:**

1. For each entry in `data.entries`, check `content`.
2. If `content` is empty, fetch the entry with the [Fetch data push entry API](/api-sdk/hie-cm/care-contexts/data-push-entry), passing `data.transaction_id` and the entry's `content_ref`.
3. Decrypt `content` with `key_information` and your private key, whether it came inline or from the API, and verify `checksum`.

> [!WARNING]
>
> An entry can be fetched for **15 minutes** after the webhook is sent. After that it is deleted and the API returns `404`, so fetch entries as soon as you receive the webhook.

> [!NOTE]
>
> We recommend fetching every entry through the [Fetch data push entry API](/api-sdk/hie-cm/care-contexts/data-push-entry). Inline `content` may be removed from this webhook in a future version.

### Request

**Headers:**

* `Eka-Webhook-Signature`: `<Eka Webhook Signature>`  [Refer: Webhook Signature](/docs/webhooks/webhook-signature)
* `Content-Type`: `application/json`

**Body:**

```json theme={null}
{
    "service": "abdm",
    "event": "abha.hiu_data_push",
    "event_time": 1749822309,
    "transaction_id": "<webhook transaction id>",
    "timestamp": 1749825214,
    "business_id": "<partner business id>",
    "client_id": "<partner client id>",
    "data": {
        "abha_address": "shyam@abdm",
        "abha_number": "",
        "hip_id": "<partner hip id>",
        "oid": "<eka user id>",
        "partner_patient_id": "<partner patient id>",
        "consent_id": "<string>",
        "transaction_id": "<string>",
        "entries": [
            {
                "care_context_id": "<string>",
                "checksum": "<string>",
                "content": "<string>",
                "media": "application/fhir+json",
                "content_ref": "<uuid>"
            }
        ],
        "key_information": {
            "crypto_alg": "<string>",
            "curve": "<string>",
            "dh_public_key": {
                "expiry": "<string>",
                "key_value": "<string>",
                "parameters": "<string>"
            },
            "nonce": "<string>"
        }
    }
}
```

### Field Descriptions

* **`data`**: Contains additional details related to the event.
  * **`consent_id`**: Consent id for the data transfer
  * **`transaction_id`**: Transaction id for the data flow. Use this one, not the top-level `transaction_id`, when calling the [Fetch data push entry API](/api-sdk/hie-cm/care-contexts/data-push-entry).
  * **`entries`**: List of care contexts with encrypted fhir data
    * `care_context_id` The care context this entry belongs to.
    * `checksum` Checksum of the plain-text FHIR data, to verify after decryption.
    * `content` The encrypted FHIR data. Empty when the entry did not fit in the webhook; see [Large pushes](#large-pushes).
    * `media` Media type of the decrypted data, `application/fhir+json`.
    * `content_ref` Reference to fetch this entry with the [Fetch data push entry API](/api-sdk/hie-cm/care-contexts/data-push-entry). Always present. Valid for 15 minutes after the webhook is sent.
  * **`key_information`** : Contains the cryptographic key material and related parameters required for secure ECDH-based key exchange between HIU and HIP.
    * `crypto_alg` The cryptographic algorithm used for key exchange (e.g., "ECDH").
    * `curve` The elliptic curve used in ECDH key generation (e.g., "Curve25519", "P-256").
    * `dh_public_key` Object containing the HIP's (sender's) public key and related metadata:
      * `expiry` The expiration timestamp (in ISO 8601 format) indicating how long the public key is valid.
      * `parameters` Additional parameters related to the ECDH key (optional or curve-specific).
      * `key_value` The base64-encoded public key value generated by the HIP (the sender).
    * `nonce` A 32-byte random nonce (Base64-encoded) generated by the HIP (the sender), used to ensure uniqueness in the session key derivation.


# Care Context Linking Status
Source: https://developer.eka.care/docs/hie-cm/webhooks/link-care-context



This webhook is sent after you call the [Care Context Link API](/api-sdk/hie-cm/care-contexts/link/hip-linking) to notify you of the linking result. Check the `status` field to determine if the care context was successfully linked.

**What to do next:**

* If `status` is `LINKED` — the care context is now registered with ABDM. Other HIUs can request this data through ABDM's consent flow.
* If `status` is `ERRORED` — check the `error` field for the failure reason and retry if needed.

### Request

**Headers:**

* `Eka-Webhook-Signature`: `<Eka Webhook Signature>`  [Refer: Webhook Signature](/docs/webhooks/webhook-signature)
* `Content-Type`: `application/json`

**Body:**

```json theme={null}
{
    "service": "abdm",
    "event": "abha.link_care_context",
    "event_time": 1749822309,
    "transaction_id": "<webhook transaction id>",
    "timestamp": 1749825214,
    "business_id": "<partner business id>",
    "client_id": "<partner client id>",
    "data": {
        "abha_address": "shyam@abdm",
        "hip_id": "<partner hip id>",
        "care_context_id": "c61f74f9-6f58-49b2-be18-8150bf0bd6ab",
        "status": "LINKED",
        "error": null,
        "retry_count":0,
        "oid": "<eka user id>",
        "partner_patient_id": "<partner user id>"
    }
}
```

### Field Descriptions

* **`data`**: Contains additional details related to the event.
  * **`status`**: Care context linking status
    * `LINKED`, `ERRORED`
  * **`error`**: Failure reason in case of status `ERRORED`
  * **`retry_count`**: Number of retries to link


# Locker Created
Source: https://developer.eka.care/docs/hie-cm/webhooks/locker-created



Webhook event is sent on successful locker creation.

### Request

**Headers:**

* `Eka-Webhook-Signature`: `<Eka Webhook Signature>`  [Refer: Webhook Signature](/docs/webhooks/webhook-signature)
* `Content-Type`: `application/json`

**Body:**

```json theme={null}
{
    "service": "abdm",
    "event": "abha.locker_created",
    "event_time": 1749822309,
    "transaction_id": "<webhook transaction id>",
    "timestamp": 1749825214,
    "business_id": "<partner business id>",
    "client_id": "<partner client id>",
    "data": {
        "abha_address": "gajendrasingh2248@sbx",
        "hip_id": "<partner hip id>",
        "oid": "<eka user id>",
        "partner_patient_id": "<partner user id>",
        "auto_approval_id": "7186798d-971c-4fb4-a899-e8e7ebd69866",
        "subscription_id": "3e25fb90-f70e-4180-a966-e7b2a3f2239c"
    }
}
```


# Subscription Updated
Source: https://developer.eka.care/docs/hie-cm/webhooks/subscription-modify



Webhook event is triggered whenever there is an update to a subscription.

### Request

**Headers:**

* `Eka-Webhook-Signature`: `<Eka Webhook Signature>`  [Refer: Webhook Signature](/docs/webhooks/webhook-signature)
* `Content-Type`: `application/json`

**Body:**

```json theme={null}
{
    "service": "abdm",
    "event": "abha.subscription_modified",
    "event_time": 1749822309,
    "transaction_id": "<webhook transaction id>",
    "timestamp": 1749825214,
    "business_id": "<partner business id>",
    "client_id": "<partner client id>",
    "data": {
            "abha_address": "gajendrasingh2248@sbx",
            "oid": "175041983138006",
            "hip_id": "<partner hip id>",
            "partner_patient_id": "<partner user id>",
            "subscription_details": {
                "subscription_id": "3e25fb90-f70e-4180-a966-e7b2a3f2239c",
                "period": {
                    "from": "2025-06-20T11:44:23.624Z",
                    "to": "2125-06-20T11:44:23.624Z"
                },
                "categories": [
                    "DATA",
                    "LINK"
                ],
                "status": "GRANTED"
            }
        }
}
```


# New Care Context Linked (Subscription)
Source: https://developer.eka.care/docs/hie-cm/webhooks/subscription-notify



Webhook event is sent when a new care context is linked to the ABHA address you have an active subscription for.

### Request

**Headers:**

* `Eka-Webhook-Signature`: `<Eka Webhook Signature>`  [Refer: Webhook Signature](/docs/webhooks/webhook-signature)
* `Content-Type`: `application/json`

**Body:**

```json theme={null}
{
    "service": "abdm",
    "event": "abha.subscription_notify",
    "event_time": 1749822309,
    "transaction_id": "<webhook transaction id>",
    "timestamp": 1749825214,
    "business_id": "<partner business id>",
    "client_id": "<partner client id>",
    "data": {
        "abha_address": "neelima0820@sbx",
        "abha_number": "12-2345-6789-0123",
        "oid": "<eka user id>",
        "partner_patient_id": "<partner user id>",
        "hip_id": "<partner hip id>",
        "subscription_meta": {
            "event_id": "<event id>",
            "hip_id": "<care-context producer hip id>",
            "care_contexts": [
                {
                    "care_context_id": "<care-context id>",
                    "patient_reference": "<patient reference id>"
                }
            ]
        }
    }
}

```

### Description

To access the associated medical documents, the HIU must initiate a consent request using the following API:

* **Consent Raise API**: [Consent-API](/api-sdk/hie-cm/consents/consent-create)


# Create an ABHA with Aadhaar OTP
Source: https://developer.eka.care/docs/hie-cm/workflows/create-abha-aadhaar-otp

Verify the patient's Aadhaar with an OTP and create a KYC-verified ABHA number and ABHA address.

## In short

* This workflow gives a KYC-verified ABHA number and ABHA address.
* Send the Aadhaar number, verify the OTP, choose an address, then call Create.
* Each call takes the latest `txn_id`.
* A patient who already has an ABHA on this Aadhaar logs in with Auto Login instead.

## When to use this

The patient has an Aadhaar number and can receive an OTP on the mobile linked to it. This workflow produces a KYC-verified 14-digit ABHA number and an ABHA address such as `shyam@abdm`. Aadhaar is the KYC.

Alternatives:

* The patient will not use Aadhaar: [Create an ABHA address with mobile OTP](/docs/hie-cm/workflows/create-abha-mobile-otp). That address is not KYC-verified.
* Assisted creation where the patient authenticates with their face on a mobile device instead of an OTP: [Create an ABHA with face authentication](/docs/hie-cm/workflows/create-abha-face-auth).
* The patient already knows their ABHA address: [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha).

If the patient already has an ABHA on this Aadhaar, this workflow finds it at the verify step. It then logs them in instead of creating a duplicate.

## Before you start

* A client access token, sent as a Bearer token on every call. See [Client login](/api-sdk/auth/client-login).
* Your facility onboarded as a Health Information Provider (HIP), with its HIP ID. You can send it in the optional `X-Hip-Id` header.
* Your own patient id for this person. You can send it in the optional `X-Partner-Pt-Id` header.&#x20;
* A webhook endpoint registered with Eka, so you receive `abha.created`. See [Register a webhook](/api-sdk/webhooks/register-webhook).
* In hand:
  * the patient's 12-digit Aadhaar number
  * the 10-digit mobile number they want on the ABHA
  * their consent to use Aadhaar, recorded on your side

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant Patient as Patient's phone
  App->>Eka: POST /abdm/na/v1/registration/aadhaar/init
  Eka-->>Patient: OTP to the Aadhaar-linked mobile
  opt OTP did not arrive
    App->>Eka: POST /abdm/na/v1/registration/aadhaar/resend
  end
  App->>Eka: POST /abdm/na/v1/registration/aadhaar/verify
  alt skip_state is confirm_mobile_otp
    Eka-->>Patient: OTP to the mobile you sent
    opt OTP did not arrive
      App->>Eka: POST /abdm/na/v1/registration/aadhaar/mobile/resend
    end
    App->>Eka: POST /abdm/na/v1/registration/aadhaar/mobile/verify
  end
  alt abha_profiles is non-empty, patient picks an existing address
    App->>Eka: POST /abdm/na/v1/registration/aadhaar/auto-login
  else patient creates a new address
    App->>Eka: GET /abdm/na/v1/registration/suggest
    App->>Eka: POST /abdm/na/v1/registration/phr/check
    App->>Eka: POST /abdm/na/v1/registration/aadhaar/create-phr
    Eka-->>App: webhook abha.created
  end
```

## Steps

**1. Send the Aadhaar number**

Send `aadhaar_number` to [Generate OTP](/api-sdk/hie-cm/enrollment/aadhaar/initiate-registration). ABDM sends an OTP to the mobile linked to that Aadhaar. The response carries `txn_id` and a `hint` with the masked mobile number, for example `OTP sent successfully to your mobile number ******90973`. Show the hint to the patient so they know which phone to check.

Keep `txn_id`. Every later call in this workflow takes the `txn_id` from the most recent response.

If the OTP does not arrive, send `txn_id` to [Resend OTP](/api-sdk/hie-cm/enrollment/aadhaar/aadhaar-resend-otp). It returns a `txn_id`; use that one from now on.&#x20;

**2. Verify the Aadhaar OTP**

Send `txn_id`, the `otp` the patient reads out, and `mobile` to [Verify OTP](/api-sdk/hie-cm/enrollment/aadhaar/verify-otp). All three are required. `mobile` is the number the ABHA will be linked to. It can differ from the mobile linked to the Aadhaar.

The response carries a new `txn_id`, `skip_state`, `abha_profiles`, `profile` and `eka.oid`. Read `skip_state` and `abha_profiles` to decide the next call:

* `skip_state` is `confirm_mobile_otp`: the `mobile` you sent is not the one linked to the Aadhaar. Go to the next step to verify it.
* `skip_state` is `abha_create` and `abha_profiles` is empty: the patient has no ABHA address on this Aadhaar. Skip to "Choose an ABHA address".
* `skip_state` is `abha_create` and `abha_profiles` is non-empty: the patient already has one or more ABHA addresses. Show each `abha_address` and `name` from `abha_profiles`. If the patient picks one, go to "Log in to the existing address". If they want a new one, go to "Choose an ABHA address".
* `skip_state` is `abha_select`: the patient has several ABHA addresses and must choose one to log in.&#x20;
* `skip_state` is `abha_end`: the flow is complete; no further call is needed.&#x20;

**3. Verify the new mobile (only if skip\_state is confirm\_mobile\_otp)**

An OTP goes to the `mobile` you sent in the previous step. Send `txn_id` and that `otp` to [Mobile Verify OTP](/api-sdk/hie-cm/enrollment/aadhaar/mobile-verify). The response has the same shape as Verify OTP. Read `skip_state` and `abha_profiles` again and branch exactly as in the previous step.

If this OTP does not arrive, send `txn_id` to [Mobile Resend OTP](/api-sdk/hie-cm/enrollment/aadhaar/mobile-resend-otp) and use the `txn_id` it returns.

**4. Choose an ABHA address**

The patient chooses the ABHA address to create. Two helpers make this reliable.

Call [Suggest ABHA Address](/api-sdk/hie-cm/commons/suggest-abha-address) with `transactionId` set to your current `txn_id`. You can also pass `fn`, `mn`, `ln` and `dob` (format `YYYY-MM-DD`). The response's `suggestions` lists available addresses.

Before you submit, send the chosen `abha_address` to [Does ABHA Address Exist](/api-sdk/hie-cm/commons/does-health-id-exist). If `exists` is `true`, ask the patient for another one.

**5. Log in to the existing address (only if the patient picked one)**

Send `txn_id` and the chosen `abha_address` from `abha_profiles` to [Auto Login](/api-sdk/hie-cm/enrollment/aadhaar/auto-login). Read its response as in [Complete the Aadhaar login](/docs/hie-cm/workflows/login-abha#complete-the-aadhaar-login), and see [Milestone 1](/docs/hie-cm/flows/m1). The patient is logged in. Stop here; do not call Create.

**6. Create the ABHA**

Send `txn_id` and the chosen `abha_address` to [Create](/api-sdk/hie-cm/enrollment/aadhaar/create-abha). Both are required. The response carries:

* `profile.abha_number`: the 14-digit ABHA number, for example `12-3456-7856-8912`.
* `profile.abha_address`: the patient's ABHA address.
* `eka.oid`: Eka's id for this patient. Later calls take it in the `X-Pt-Id` header or the `oid` query parameter.
* `token` and `refresh_token`: the ABHA tokens ABDM issues.&#x20;
* `skip_state`.&#x20;

Eka also sends the [`abha.created`](/docs/hie-cm/webhooks/abha-created) webhook to your server. Its `data` carries `abha_address`, `abha_number`, `oid`, `hip_id` and `partner_patient_id`. Use the webhook, not only the API response, to provision the patient in your database. Acknowledge it and verify its signature as described in [Webhooks](/docs/hie-cm/webhooks#delivery-signature-and-acknowledgement).&#x20;

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `txn_id` | The latest response in this workflow | Until Create or Auto Login returns | Every call in this workflow |
| `eka.oid` | Verify, Mobile Verify, Create or Auto Login; also `data.oid` on `abha.created` | Permanently, on the patient record | The `X-Pt-Id` header or `oid` query on every later ABDM Connect call for this patient |
| `profile.abha_address` | Create or Auto Login; also `data.abha_address` on `abha.created` | Permanently, on the patient record | Care context linking, gateway session, login |
| `profile.abha_number` | Create or Auto Login; also `data.abha_number` on `abha.created` | Permanently, on the patient record | Printing the ABHA card, KYC, login by ABHA number |
| `transaction_id` | `abha.created` webhook | Until processed | Ignoring a repeated delivery of the same event |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Error responses carry `code`, `error` and `source_error`. `source_error.code` holds codes such as `MIS-1013`.&#x20;

| Situation | Code | Do |
| - | - | - |
| Wrong OTP | `MIS-1013` | Ask the patient to re-enter the OTP. |
| Too many OTP requests or wrong attempts | `ABDM-1100` | Tell the patient to try again in 30 minutes. Start again from Generate OTP. |
| Patient blocked | `ABDM-1027` | Tell the patient to try again after 24 hours. |
| Too many requests | `ABDM-1022` | Back off and retry. |
| Expired or unknown transaction | `ABDM-1017`, `MIS-1026` | Start again from Generate OTP. |
| Aadhaar number not found | `ABDM-1112` | Ask the patient to check the number. |
| Malformed request, for example a missing `mobile` on Verify | `ABDM-1006`, `ABDM-1010` | Fix the request body against the reference page. |
| ABHA address already taken | `ABDM-1101` | Ask for another address. Call Does ABHA Address Exist before Create to avoid this. |
| Mobile verification still pending | `ABDM-1102` | Complete the Mobile Verify OTP step before Create. |
| Mobile number already claimed by another account | `EKA-1002` | Not documented yet. |
| ABDM or a dependent service is down or slow | `ABDM-1019`, `ABDM-1024`, `ABDM-1007`, `ABDM-1004` | Retry later. |
| `abha.created` never arrives | none | Use the Create response to proceed. |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

* [ ] Happy path: Generate OTP, Verify OTP with `mobile` set to the Aadhaar-linked number, Suggest, Does ABHA Address Exist returns `exists: false`, Create. The response has `profile.abha_number` and `eka.oid`.
* [ ] `abha.created` arrives with the same `abha_address` and `oid`, and its signature verifies.
* [ ] Wrong OTP once, then the correct OTP: `MIS-1013`, then success. Record the code you receive; the expected code is not confirmed.
* [ ] Verify OTP with a `mobile` that is not the Aadhaar-linked one: `skip_state` is `confirm_mobile_otp`, then Mobile Verify OTP succeeds.
* [ ] Resend on both OTPs: each returns a `txn_id` that the next call accepts.
* [ ] Second run with the same Aadhaar: Verify OTP returns `abha_create` with a non-empty `abha_profiles`; Auto Login succeeds.
* [ ] Create with an address that Does ABHA Address Exist reports as taken: `ABDM-1101`. Record the code you receive; the expected code is not confirmed.


# Create an ABHA with face authentication
Source: https://developer.eka.care/docs/hie-cm/workflows/create-abha-face-auth

Assisted ABHA creation where the patient authenticates with their face on a mobile device instead of an OTP.

## In short

* Face authentication on the patient's device replaces the Aadhaar OTP.
* Show the QR code from Face Auth Init, then poll Capture Face until `Verified`.
* Verify Face returns the identity, and Create uses the Aadhaar Create call.
* That create call is not yet confirmed for face authentication.

## When to use this

Use this for assisted ABHA creation with Aadhaar face authentication instead of an OTP. The patient scans a QR code you show and completes face authentication on a mobile device. The verified identity then creates a KYC-verified ABHA.&#x20;

Alternatives:

* The patient will use an Aadhaar OTP instead: [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp).
* The patient will not use Aadhaar: [Create an ABHA address with mobile OTP](/docs/hie-cm/workflows/create-abha-mobile-otp).

## Before you start

* A client access token, sent as a Bearer token on every call. See [Client login](/api-sdk/auth/client-login).
* Your facility onboarded as a Health Information Provider (HIP). You can send its HIP ID in the optional `X-Hip-Id` header and your own patient id in the optional `X-Partner-Pt-Id` header.
* A webhook endpoint registered with Eka, so you receive `abha.created`. See [Register a webhook](/api-sdk/webhooks/register-webhook).
* A screen that can show a QR code to the patient, and a mobile device on which the patient completes face authentication.&#x20;
* In hand: the patient's 12-digit Aadhaar number.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant Patient as Patient's device
  App->>Eka: POST /abdm/na/v1/face-auth/init
  App-->>Patient: Show the QR code from url
  Patient->>Patient: Scan and complete face authentication
  loop Until status is Verified
    App->>Eka: POST /abdm/na/v1/face-auth/capture
  end
  App->>Eka: POST /abdm/na/v1/face-auth/verify
  opt Mobile not linked with Aadhaar (not yet confirmed for face auth)
    App->>Eka: POST /abdm/na/v1/registration/aadhaar/mobile/verify
    opt OTP did not arrive
      App->>Eka: POST /abdm/na/v1/registration/aadhaar/mobile/resend
    end
  end
  App->>Eka: GET /abdm/na/v1/registration/suggest
  App->>Eka: POST /abdm/na/v1/registration/phr/check
  App->>Eka: POST /abdm/na/v1/registration/aadhaar/create-phr
  Eka-->>App: webhook abha.created
```

## Steps

**1. Start face authentication**

Call [Face Auth Init](/api-sdk/hie-cm/enrollment/face-auth/face-auth-init). It takes no request body. The response carries `txn_id` and `url`. Show `url` to the patient as a QR code to scan with their mobile device.&#x20;

Keep `txn_id`; every later call takes the `txn_id` from the most recent response.

**2. Poll until the face is verified**

Send `txn_id` to [Capture Face](/api-sdk/hie-cm/enrollment/face-auth/face-auth-capture) repeatedly while the patient completes face authentication. The response carries `status`, `message` and `txn_id`. Keep polling while `status` is `Pending`. Stop when it is `Verified`.&#x20;

**3. Fetch the verified identity**

Send `txn_id` and `aadhaar` (the patient's Aadhaar number) to [Verify Face](/api-sdk/hie-cm/enrollment/face-auth/face-auth-verify). The response carries a new `txn_id`, `skip_state`, `abha_profiles`, `profile` and `eka.oid`. `profile` holds the patient's name, date of birth, gender and address from Aadhaar.

Read `skip_state` and `abha_profiles`:

* `abha_create` with an empty `abha_profiles`: go to the next step.
* `abha_create` with a non-empty `abha_profiles`: the patient already has ABHA addresses.&#x20;
* `confirm_mobile_otp`: go to "Verify the mobile".&#x20;

**4. Verify the mobile (only if skip\_state is confirm\_mobile\_otp)**

> [!NOTE]
>
> This step is not yet confirmed for face authentication. flows/m1 draws a "Mobile linked with Aadhaar?" branch after Verify Face, with Mobile Verify OTP and Mobile Resend OTP, as in the Aadhaar OTP flow. Whether these calls accept the face-auth `txn_id` is not yet confirmed.

Send `txn_id` and the `otp` the patient receives to [Mobile Verify OTP](/api-sdk/hie-cm/enrollment/aadhaar/mobile-verify). If the OTP does not arrive, send `txn_id` to [Mobile Resend OTP](/api-sdk/hie-cm/enrollment/aadhaar/mobile-resend-otp) and use the `txn_id` it returns.&#x20;

**5. Create the ABHA**

> [!NOTE]
>
> The create call after face authentication is not yet confirmed. Verify Face returns the same `txn_id`, `skip_state`, `abha_profiles` and `eka` shape as the Aadhaar OTP Verify call. flows/m1 draws the same mobile check, then create, path for both. On that evidence this step uses the Aadhaar Create call.

The patient chooses an ABHA address. You can use [Suggest ABHA Address](/api-sdk/hie-cm/commons/suggest-abha-address) and [Does ABHA Address Exist](/api-sdk/hie-cm/commons/does-health-id-exist) as in [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp).

Send `txn_id` and `abha_address` to [Create](/api-sdk/hie-cm/enrollment/aadhaar/create-abha). The response carries `profile.abha_number`, `profile.abha_address`, `eka.oid`, `token`, `refresh_token` and `skip_state`.

Eka also sends the [`abha.created`](/docs/hie-cm/webhooks/abha-created) webhook with `abha_address`, `abha_number`, `oid`, `hip_id` and `partner_patient_id` in `data`. Acknowledge it and verify its signature as described in [Webhooks](/docs/hie-cm/webhooks#delivery-signature-and-acknowledgement).

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `txn_id` | The latest response in this workflow | Until Create returns | Every call in this workflow |
| `eka.oid` | Verify Face or Create; also `data.oid` on `abha.created` | Permanently, on the patient record | The `X-Pt-Id` header or `oid` query on every later call for this patient |
| `profile.abha_address` | Create; also `data.abha_address` on `abha.created` | Permanently, on the patient record | Care context linking, gateway session, login |
| `profile.abha_number` | Create; also `data.abha_number` on `abha.created` | Permanently, on the patient record | ABHA card, KYC, login by ABHA number |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Error responses carry `code`, `error` and `source_error`. `source_error.code` holds the ABDM code. See [Error codes](/docs/hie-cm/errors).&#x20;

| Situation | Code | Do |
| - | - | - |
| Patient never completes face authentication | Capture keeps returning `Pending` | Stop polling after your timeout and start again from Face Auth Init. |
| Aadhaar number does not match the face authenticated | Not documented | Ask the patient to check the number. |
| Expired or unknown transaction | `ABDM-1017`, `MIS-1026` | Start again from Face Auth Init. |
| Too many requests | `ABDM-1022` | Back off and retry. |
| ABHA address already taken | `ABDM-1101` | Ask for another address. |
| ABDM or a dependent service is down | `ABDM-1019`, `ABDM-1024`, `ABDM-1007` | Retry later. |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

Run against the sandbox base URL `https://api.dev.eka.care`.&#x20;

* [ ] Happy path: Face Auth Init, show `url`, poll Capture Face until `Verified`, Verify Face, Create. The response has `profile.abha_number` and `eka.oid`.
* [ ] `abha.created` arrives with the same `abha_address` and `oid`, and its signature verifies.
* [ ] Abandon face authentication: Capture Face stays `Pending` and your timeout restarts the flow.
* [ ] Verify Face with a different Aadhaar number from the one authenticated: record the code it returns in the failure table.


# Create an ABHA address with mobile OTP
Source: https://developer.eka.care/docs/hie-cm/workflows/create-abha-mobile-otp

Create an ABHA address, without KYC, for a patient who cannot or will not use Aadhaar.

## In short

* This workflow creates an ABHA address from a mobile OTP, without Aadhaar.
* The address is not KYC-verified and comes with no 14-digit ABHA number.
* Send the mobile number, verify the OTP, choose an address, then call Create with the patient's profile.
* Each call takes the latest `txn_id`.

## When to use this

The patient will not use Aadhaar, or does not have it. This workflow verifies their mobile number with an OTP and creates an ABHA address such as `shyam@abdm`. The address is not KYC-verified, and the patient gets no 14-digit ABHA number from it.

Alternatives:

* The patient has Aadhaar and its linked mobile: [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp) gives a KYC-verified ABHA number.
* The patient already has an ABHA address: [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha).
* The patient wants to upgrade the address to KYC later: [Manage the ABHA profile and KYC](/docs/hie-cm/workflows/manage-profile-and-kyc).

## Before you start

* A client access token, sent as a Bearer token on every call. See [Client login](/api-sdk/auth/client-login).
* Your facility onboarded as a Health Information Provider (HIP). You can send its HIP ID in the optional `X-Hip-Id` header and your own patient id in the optional `X-Partner-Pt-Id` header.
* A webhook endpoint registered with Eka, so you receive `abha.created`. See [Register a webhook](/api-sdk/webhooks/register-webhook).
* In hand: the patient's mobile number, first name, gender, full date of birth and pincode. Middle name, last name and address are optional.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant Patient as Patient's phone
  App->>Eka: POST /abdm/na/v1/registration/mobile/init
  Eka-->>Patient: OTP to the mobile number
  opt OTP did not arrive
    App->>Eka: POST /abdm/na/v1/registration/mobile/resend
  end
  App->>Eka: POST /abdm/na/v1/registration/mobile/verify
  App->>Eka: GET /abdm/na/v1/registration/suggest
  App->>Eka: POST /abdm/na/v1/registration/phr/check
  App->>Eka: POST /abdm/na/v1/registration/mobile/create-phr
  Eka-->>App: webhook abha.created
```

## Steps

**1. Send the mobile number**

Send `mobile_number` to [Generate OTP](/api-sdk/hie-cm/enrollment/mobile/init). The patient receives an OTP. The response carries `txn_id` and a `hint` with the masked number.

Keep `txn_id`. Every later call takes the `txn_id` from the most recent response.

If the OTP does not arrive, send `txn_id` to [Resend OTP](/api-sdk/hie-cm/enrollment/mobile/resend) and use the `txn_id` it returns.&#x20;

**2. Verify the OTP**

Send `txn_id` and the `otp` to [Verify OTP](/api-sdk/hie-cm/enrollment/mobile/verify). The response carries a new `txn_id`, `skip_state`, `eka.oid` and `abha_profiles`.

`abha_profiles` is present when ABHA addresses already exist on this mobile. If it is non-empty, show each `abha_address` and `name`, and ask whether the patient wants one of those or a new address. To use an existing one, switch to [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha).&#x20;

If the patient wants a new address, continue.

**3. Choose an ABHA address**

Call [Suggest ABHA Address](/api-sdk/hie-cm/commons/suggest-abha-address) with `transactionId` set to your current `txn_id`, plus `fn`, `mn`, `ln` and `dob` (format `YYYY-MM-DD`) from the patient's details. The response's `suggestions` lists available addresses.

Send the chosen `abha_address` to [Does ABHA Address Exist](/api-sdk/hie-cm/commons/does-health-id-exist). If `exists` is `true`, ask the patient for another one.

**4. Create the ABHA address**

Send `txn_id`, `abha_address` and `profile` to [Create](/api-sdk/hie-cm/enrollment/mobile/create). `profile` requires `first_name`, `gender` (`M`, `F` or `O`), `year_of_birth`, `month_of_birth`, `day_of_birth` and `pincode`. It also takes `middle_name`, `last_name` and `address`.

The response carries `success`, `profile`, `eka.oid`, `skip_state`, `token` and `refresh_token`.&#x20;

Eka also sends the [`abha.created`](/docs/hie-cm/webhooks/abha-created) webhook with `abha_address`, `oid`, `hip_id` and `partner_patient_id` in `data`. Reply `200` within 5 seconds; Eka retries on any other status. Verify the `Eka-Webhook-Signature` header as described in [Webhook signature](/docs/webhooks/webhook-signature).&#x20;

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `txn_id` | The latest response in this workflow | Until Create returns | Every call in this workflow |
| `eka.oid` | Verify OTP or Create; also `data.oid` on `abha.created` | Permanently, on the patient record | The `X-Pt-Id` header or `oid` query on every later call for this patient |
| `profile.abha_address` | Create; also `data.abha_address` on `abha.created` | Permanently, on the patient record | Care context linking, gateway session, login |
| `profile.kyc_verified` | Create | Until the patient completes KYC | Deciding whether to offer KYC later |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Error responses carry `code`, `error` and `source_error`. `source_error.code` holds codes such as `MIS-1013`. See [Error codes](/docs/hie-cm/errors).&#x20;

| Situation | Code | Do |
| - | - | - |
| Wrong OTP | `MIS-1013` | Ask the patient to re-enter the OTP. |
| Too many OTP requests or wrong attempts | `ABDM-1100` | Tell the patient to try again in 30 minutes. Start again from Generate OTP. |
| Patient blocked | `ABDM-1027` | Tell the patient to try again after 24 hours. |
| Too many requests | `ABDM-1022` | Back off and retry. |
| Expired or unknown transaction | `ABDM-1017`, `MIS-1026` | Start again from Generate OTP. |
| Invalid mobile number | `ABDM-1014` | Ask the patient to check the number. |
| Missing or invalid `profile` field | `ABDM-1006`, `ABDM-1010` | Fix the request body against the reference page. |
| ABHA address already taken | `ABDM-1101` | Ask for another address. Call Does ABHA Address Exist first. |
| ABDM or a dependent service is down | `ABDM-1019`, `ABDM-1024`, `ABDM-1004` | Retry later. |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

Run against the sandbox base URL `https://api.dev.eka.care`.&#x20;

* [ ] Happy path: Generate OTP, Verify OTP, Suggest, Does ABHA Address Exist returns `exists: false`, Create. The response has `success: true` and `eka.oid`.
* [ ] `abha.created` arrives with the same `abha_address` and `oid`, and its signature verifies.
* [ ] Wrong OTP once, then the correct one: `MIS-1013`, then success. Record the code you receive; the expected code is not confirmed.
* [ ] Resend OTP, then verify with the new OTP and the returned `txn_id`.
* [ ] Second run with the same mobile: Verify OTP returns a non-empty `abha_profiles`.
* [ ] Create with an address that Does ABHA Address Exist reports as taken: `ABDM-1101`. Record the code you receive; the expected code is not confirmed.


# Create an HPR ID with Aadhaar OTP
Source: https://developer.eka.care/docs/hie-cm/workflows/create-hpr-id

Verify a healthcare professional's Aadhaar and linked mobile, reuse their HPR ID if one exists, or create a new one from a suggested handle.

## In short

* Verify the professional's Aadhaar with an OTP, then check the Aadhaar-linked mobile.
* If Get HPR Info finds an existing HPR ID, save it and stop.
* Otherwise the professional picks a handle and you call Create HPR.
* Create takes `txnId` and `hprId` in camel case.

## When to use this

A doctor, nurse or other healthcare professional at the facility needs a Healthcare Professional Registry (HPR) ID. You want them to get it without leaving your HMS. The flow:

1. Verifies their Aadhaar with an OTP.
2. Confirms the mobile they give is the one linked to Aadhaar.
3. Returns the HPR ID they already have, or creates a new one.

A professional may already have an HPR ID and want to sign in with their mobile. For them, use [Log in to HPR with a mobile OTP](/docs/hie-cm/workflows/hpr-mobile-login). You can also create HPR IDs by hand on the [ABDM portal](https://nhpr.abdm.gov.in/nhpr/v4/login).

## Before you start

* A bearer token for the Eka API. See [Authorization](/api-sdk/auth/getting-started).
* The headers your integration sends on ABDM Connect calls. Each operation in this workflow accepts `X-Pt-Id`, `X-Partner-Pt-Id` and `X-Hip-Id`.&#x20;
* The professional's Aadhaar number, the mobile linked to it, and their consent to use Aadhaar, recorded on your side.
* The professional's category and sub-category, email, pincode and a password, which Create needs.&#x20;

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant Phone as Professional's phone
  App->>Eka: POST /abdm/nhpr/v1/hpr/aadhaar/init
  Eka-->>Phone: OTP to the Aadhaar-linked mobile
  App->>Eka: POST /abdm/nhpr/v1/hpr/aadhaar/verify
  App->>Eka: POST /abdm/nhpr/v1/hpr/aadhaar/demo/verify
  App->>Eka: POST /abdm/nhpr/v1/hpr/aadhaar/check/exist
  alt No HPR ID yet
    App->>Eka: POST /abdm/nhpr/v1/hpr/aadhaar/suggest
    App->>Eka: POST /abdm/nhpr/v1/hpr/aadhaar/create
  end
```

## Steps

**1. Send the Aadhaar OTP**

Send `aadhaar` to [Get Aadhaar OTP](/api-sdk/hie-cm/nhpr-abdm/hpr/get-aadhar-otp). The response `data` carries `txn_id`, `mobile_num` and `hint`. Keep `txn_id`; every later call in this workflow needs it. The professional receives an OTP on the mobile linked to their Aadhaar.

**2. Verify the Aadhaar OTP**

Send `txn_id` and the `otp` the professional reads out to [Verify Aadhaar OTP](/api-sdk/hie-cm/nhpr-abdm/hpr/verify-aadhar-otp). The response `data` carries `txn_id`. Use the `txn_id` from this response in the next call.&#x20;

**3. Verify the linked mobile**

Send `txn_id` and the `mobile_num` the professional gives to [Verify Mobile](/api-sdk/hie-cm/nhpr-abdm/hpr/verify-mobile). Read `verified` in the response `data`. If `verified` is false, stop and show `reason`; the mobile does not match Aadhaar. If it is true, keep `txnId`. The response can also carry `hpr.hprId` and `suggested_hpr_ids`.&#x20;

**4. Check for an existing HPR ID**

Send `txn_id` and `mobile_num` to [Get HPR Info](/api-sdk/hie-cm/nhpr-abdm/hpr/check-hpr-exist). The response `data` carries the professional's profile (`first_name`, `last_name`, `category_id`, `pincode` and others), `hpr_id`, `hpr_id_number`, `new`, `token` and `txn_id`. If an HPR ID already exists, save `hpr_id` and `hpr_id_number` on the staff record and stop; do not create a second one. Otherwise continue to Suggest.&#x20;

**5. Get suggested HPR IDs**

Send `txn_id` to [Suggest IDs](/api-sdk/hie-cm/nhpr-abdm/hpr/suggest-ids). The response `data` is a list of suggested HPR ID handles. Show them to the professional and let them pick one, or type their own.&#x20;

**6. Create the HPR ID**

Send `txnId`, the chosen `hprId`, and the professional's details to [Create HPR](/api-sdk/hie-cm/nhpr-abdm/hpr/create-hpr). Note the field names: this body uses `txnId` and `hprId` in camel case, where earlier calls use `txn_id`. Prefill `first_name`, `middle_name`, `last_name` and `pincode` from the Get HPR Info response. The response `data` carries `hprId` and `hpr_id_number`. Save both on the staff record.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `txn_id` | Get Aadhaar OTP, then Verify Aadhaar OTP | Until Create returns | Every call in this workflow; sent as `txnId` to Create |
| `mobile_num` | The professional, checked by Verify Mobile | Until Get HPR Info returns | Verify Mobile and Get HPR Info |
| Profile fields (`first_name`, `last_name`, `pincode`) | Get HPR Info | Until Create returns | Prefilling the Create body |
| `hprId` or `hpr_id` | Create, or Get HPR Info for an existing ID | Permanently, on the staff record | Registering the facility, and identifying the professional in later ABDM calls |
| `hpr_id_number` | Create, or Get HPR Info for an existing ID | Permanently, on the staff record | Display and reconciliation with the HPR registry |
| `token` | Get HPR Info | | |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Errors come back as `4XX` or `5XX` with a body carrying `code`, `error` and `source_error` (`code`, `message`). Read `source_error.code` for the upstream code, and look it up on the [errors page](/docs/hie-cm/errors).

| Situation | Code | Do |
| - | - | - |
| Malformed body, such as a missing `aadhaar` | `ABDM-1006` | Fix the request; do not retry unchanged |
| Wrong OTP | `MIS-1013` | Let the professional enter it again |
| Too many OTP requests or attempts | `ABDM-1100` | Wait 30 minutes, then restart from Get Aadhaar OTP; show the professional the lockout |
| Transaction expired or unknown | `ABDM-1017` or `MIS-1026` | Restart from Get Aadhaar OTP |
| Mobile does not match Aadhaar | Verify Mobile returns `verified` false with `error_code` and `reason` | Show `reason`; ask for the Aadhaar-linked mobile |
| HPR ID handle already taken | | Offer another suggested handle |
| ABDM registry unavailable | `ABDM-1019` or `ABDM-1024` | Retry later |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

Run against the sandbox base URL `https://api.dev.eka.care`.&#x20;

* [ ] Happy path for a new professional: Get Aadhaar OTP, Verify Aadhaar OTP, then Verify Mobile with `verified` true. Get HPR Info shows no existing ID, then Suggest IDs, then Create returns `hprId` and `hpr_id_number`
* [ ] Second run with the same Aadhaar: Get HPR Info returns the existing `hpr_id`, and your app stops without calling Create
* [ ] Wrong OTP once, then the correct OTP
* [ ] A mobile that is not linked to the Aadhaar: Verify Mobile returns `verified` false and your app shows `reason`
* [ ] Create with a handle that is already taken


# Answer discovery and link old records
Source: https://developer.eka.care/docs/hie-cm/workflows/hip-discovery-and-link

Let a patient find and claim records your facility created before they were linked to their ABHA.

## In short

* You answer three Eka webhooks in turn, each with one call back to Eka.
* First return the patient's unlinked records, then send an OTP by SMS.
* When the OTP matches, call On Link Confirm and ABDM links the records.

## When to use this

A patient searches for their records at your facility from a PHR app, such as the ABHA app. The records exist in your system but were never linked to their ABHA. You answer three webhooks in turn:

1. You return the matching records.
2. You send the patient an OTP.
3. You confirm the link once the OTP checks out.

## Before you start

* A client access token, sent as a Bearer token. See [Authorization](/api-sdk/auth/getting-started).
* Your facility onboarded as a Health Information Provider (HIP), with its HIP ID. ABDM routes discovery requests by HIP ID.
* A webhook URL registered with Eka that can receive the three discovery events, and the means to verify the [webhook signature](/docs/webhooks/webhook-signature). Acknowledge each event as described in [Webhooks](/docs/hie-cm/webhooks#delivery-signature-and-acknowledgement).
* A patient search in your system by mobile number, name, gender and year of birth.
* A way to generate an OTP and send it by SMS to the patient's registered mobile number. You send this OTP yourself.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant PHR as Patient's PHR app
  participant ABDM as ABDM gateway
  participant Eka
  participant App as Your app
  PHR->>ABDM: Discover records at your HIP
  ABDM->>Eka: Discovery request
  Eka-->>App: webhook abha.care_context_discover
  App->>Eka: POST /abdm/v1/care-contexts/on-discover
  Eka->>ABDM: Matching care contexts
  PHR->>ABDM: Link the selected care contexts
  ABDM->>Eka: Link request
  Eka-->>App: webhook abha.care_context_discover_link_init
  App-->>PHR: OTP by SMS to the patient's mobile
  App->>Eka: POST /abdm/v1/care-contexts/discover/link/on-init
  PHR->>ABDM: Patient enters the OTP
  ABDM->>Eka: Link confirmation
  Eka-->>App: webhook abha.context_discover_link_confirm
  App->>Eka: POST /abdm/v1/care-contexts/discover/link/on-confirm
  Eka->>ABDM: Linked care contexts
```

## Steps

**1. Answer the discovery request**

Eka sends the [`abha.care_context_discover`](/docs/hie-cm/webhooks/discover-care-context) webhook.

From `data`, read `abha_address`, `patient_name`, `gender`, `year_of_birth` and the `identifiers` list (`MOBILE`, `ABHA_NUMBER`, `abhaAddress`). Keep `request_id` and `txn_id`.

Search your system with these identifiers. Collect the care contexts for this patient that are not yet linked: visits, prescriptions, lab reports.

Call [On Discover](/api-sdk/hie-cm/care-contexts/discover/on_discover) with `request_id` and `txn_id` from the webhook, and `patients`. Each entry carries:

* `ref_num`: your patient reference number
* `display`: a display name
* `hi_type`
* `care_contexts`, each with `ref_num` and `display`

If you find no match, send `error` with `code` and `message` instead of `patients`. The call returns `204 No Content`.

You may save `abha_address` to the matched patient's record. ABDM leaves that to you. Saving it lets you [link future records directly](/docs/hie-cm/workflows/link-care-context-hip).

**2. Send the OTP and report it**

When the patient selects records to link, Eka sends the [`abha.care_context_discover_link_init`](/docs/hie-cm/webhooks/discover-link-init) webhook.

From `data`, read `patient`: each entry carries `ref_num`, `hi_type`, `count` and `care_contexts` (each with `reference_number`). Save these as the care contexts to link. Keep `request_id` and `txn_id`.

Generate an OTP and send it to the patient's registered mobile number. Record when it expires.

Call [On Link Init](/api-sdk/hie-cm/care-contexts/discover/link_on_init) with `request_id` and `txn_id` from this webhook, the patient's `ref_num`, and `otp_expiry`. If you cannot send the OTP, send `error` instead. The call returns `204 No Content`.

**3. Verify the OTP and confirm the link**

When the patient enters the OTP in the PHR app, Eka sends the [`abha.context_discover_link_confirm`](/docs/hie-cm/webhooks/discover-link-confirm) webhook.

From `data`, read `token` (the OTP the patient entered), `linkRefNumber`, `request_id` and `hip_id`. Find the pending link from step 2 and compare `token` with the OTP you generated. Check it has not expired.

If the OTP is valid, call [On Link Confirm](/api-sdk/hie-cm/care-contexts/discover/link_on_confirm) with `request_id` from this webhook. Send `patients`: the care contexts to link, in the same shape as on-discover. ABDM then registers the link under the patient's ABHA, against the HIP in `hip_id`. Mark those care contexts as linked in your system. The call returns `204 No Content`.

If the OTP is wrong or expired, call On Link Confirm with `error` instead of `patients`.

Once linked, if you keep their data yourself, see [Serve records on a fetch request](/docs/hie-cm/workflows/serve-data-on-fetch).

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `txn_id` | `abha.care_context_discover` | Until on-confirm returns | Every reply in this transaction; it ties discovery to link init |
| `request_id` | Each webhook | Until that webhook's reply returns | The reply to that webhook; each webhook has its own |
| Care contexts returned, with `ref_num` | Your on-discover reply | Until on-confirm returns | Checking what the patient selected |
| Selected `reference_number` values | `abha.care_context_discover_link_init` | Until on-confirm returns | The `patients` list in on-confirm |
| OTP and its expiry | You, in step 2 | Until the confirm webhook arrives or the OTP expires | Checking `token` |
| `abha_address` | `abha.care_context_discover` | Forever, on the patient record, if you choose to save it | Linking future records directly |
| Linked flag per care context | You, after on-confirm | Forever | Leaving it out of the next discovery answer |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Error responses carry `code`, `error` and `source_error`.

| Situation | Code | Do |
| - | - | - |
| Reply body malformed or `txn_id` or `request_id` missing | `ABDM-1006`, `ABDM-1010` | Check both ids are copied from the webhook and resend |
| Request id or transaction id not recognised | `ABDM-1030`, `ABDM-1052` | Use the `request_id` from the webhook you are answering, not an earlier one |
| Request id already used | `ABDM-1064` | Do not reply twice to the same webhook |
| Care context count does not match | `ABDM-1037` | Check the care contexts in on-confirm match those the patient selected |
| Link token invalid or mismatched | `ABDM-1026`, `ABDM-1038` | Not documented |
| Your system did not answer | `ABDM-1028`, `ABDM-1401`, `ABDM-1402` | Acknowledge each webhook within 5 seconds and reply promptly |
| Gateway timeout | `ABDM-1048` | Not documented |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

* [ ] Create a test patient in your system with an unlinked visit. Use the same mobile, name, gender and year of birth as a sandbox ABHA
* [ ] Discover your HIP from a sandbox PHR app; receive `abha.care_context_discover` and reply with the visit
* [ ] Select the visit; receive `abha.care_context_discover_link_init`, send the OTP, reply with on-init
* [ ] Enter the OTP; receive `abha.context_discover_link_confirm`, reply with on-confirm, and see the record linked in the PHR app
* [ ] Discover with an ABHA that matches no patient and reply with `error`
* [ ] Enter a wrong OTP and reply with `error`


# Receive a scanned profile as a HIP
Source: https://developer.eka.care/docs/hie-cm/workflows/hip-scan-and-share

Accept the profile a patient shares by scanning your counter QR, and reply with a token.

## In short

* Eka sends a profile shared from your facility QR on `abha.hip_profile_share`.
* Match or register the patient, and issue an OPD token for the counter in `hip_code`.
* Reply with On-Share, sending the webhook's `req_id` as `request_id`.

## When to use this

A patient at your registration counter scans the facility's Health Facility QR code with a PHR app and shares their ABHA profile. Eka sends you the profile on a webhook. You register or match the patient, issue an OPD token, and reply with it. The PHR app shows the patient the token.

This replaces asking the patient for their ABHA at the counter. If the patient has no PHR app, register them at the desk. Use [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha) or [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp).

The PHR app's side of this exchange, scanning and fetching the token, is a separate workflow: [Share a profile at a facility counter](/docs/hie-cm/workflows/phr-scan-and-share).

## Before you start

* A client access token, sent as a Bearer token. See [Authorization](/api-sdk/auth/getting-started).
* Your facility onboarded as a Health Information Provider (HIP), with its HIP ID.
* A Health Facility QR code displayed at each counter, each with its counter id (`hip_code`).
* A webhook URL registered with Eka that can receive `abha.hip_profile_share`, and the means to verify the [webhook signature](/docs/webhooks/webhook-signature).
* A way to issue OPD token numbers in your system.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant PHR as Patient's PHR app
  participant Eka
  participant App as Your app
  PHR->>Eka: Scan facility QR and share profile
  Eka-->>App: webhook abha.hip_profile_share
  App->>Eka: POST /abdm/v1/hip/patient/profile/on-share
  Eka-->>PHR: Token for the patient
```

## Steps

**1. Receive the shared profile**

Eka sends the [`abha.hip_profile_share`](/docs/hie-cm/webhooks/hip-scan-and-share) webhook. Acknowledge it with HTTP `200` within 5 seconds; Eka retries on any other status.

From `data`, keep `req_id`, `abha_address`, `abha_number`, `hip_code` (the counter the patient scanned), `hip_id`, `oid` and `partner_patient_id`.

Look the patient up by `abha_address` or `abha_number`. If you find them, use that record. If not, register a new patient and save `abha_address`, `abha_number` and `oid` on the record. Issue an OPD token for the counter in `hip_code`.

**2. Reply with the token**

Call [On-Share](/api-sdk/hie-cm/scan-and-share/scan-on-share). Send the patient's `oid` in `X-Pt-Id`, your patient id in `X-Partner-Pt-Id` and your HIP ID in `X-Hip-Id`. In the body send:

* `request_id`: the `req_id` from the webhook.
* `abha_address`: from the webhook.
* `hip_code`: the counter id from the webhook.
* `token`: with `token_number` (required) and `expires_at`.

If you cannot register the patient or issue a token, send `error` with `code` and `message` instead of `token`.

The call returns `202 Accepted`. Eka passes the token to the patient's PHR app.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `req_id` | `abha.hip_profile_share` | Until on-share returns `202` | `request_id` in the on-share reply |
| `hip_code` | `abha.hip_profile_share` | Until on-share returns `202` | Issuing the token for the right counter, and the reply |
| `abha_address`, `abha_number`, `oid` | `abha.hip_profile_share` | Forever, on the patient record | Linking this visit as a care context, and every later ABDM call |
| `token_number` | Your token system | For the visit | Calling the patient at the counter |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), 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](/docs/hie-cm/errors).

| Situation | Code | Do |
| - | - | - |
| On-share body malformed or a field missing | `ABDM-1006`, `ABDM-1010` | Check `request_id` and `abha_address` are set and resend |
| Request id not recognised | `ABDM-1030`, `ABDM-1052` | Check you sent the webhook's `req_id` |
| Share could not reach the hospital | `ABDM-1018` | Retry later; register the patient at the desk meanwhile |
| Profile share keys invalid | `ABDM-1049`, `ABDM-1050` | Not documented |
| Your webhook did not answer within 5 seconds | No code; Eka retries the webhook | Acknowledge first, then register and reply |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

* [ ] Scan your sandbox facility QR from a PHR app with a test ABHA and receive `abha.hip_profile_share`
* [ ] Reply with a `token_number` and get `202 Accepted`; the PHR app shows the token
* [ ] Share the same ABHA again and confirm you match the existing patient instead of creating a duplicate
* [ ] Reply with `error` instead of `token` and check what the PHR app shows


# Receive and decrypt records as a HIU
Source: https://developer.eka.care/docs/hie-cm/workflows/hiu-receive-data

Take the encrypted FHIR records a HIP pushes after consent, decrypt them, and report which ones you could read.

## In short

* Acknowledge `abha.hiu_data_push` within 5 seconds, then decrypt.
* Decrypt each entry with your stored `private_key` and `nonce`.
* Report each entry's result with Push FHIR parsing status.
* If Eka stores the data for you, read the records from the records product instead.

## When to use this

The patient has granted a consent you raised in [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent), and you manage the data on your side. Each HIP encrypts the approved records with your public keyset and Eka delivers them to you on a webhook. This workflow decrypts them and tells Eka which care contexts you could parse.

If Eka stores the data for you, nothing arrives on a webhook. Read each approved care context with [Retrieve Health Records](/api-sdk/health-records/retrieve-health-records) in the records product, passing the `care_context_id` from Consent Details as the identifier. That call belongs to the records product and is documented there.

## Before you start

* A bearer token for the API. See [Authorization](/api-sdk/auth/getting-started).
* Your public keyset registered, and the matching `private_key` and `nonce` stored on your side. See the keyset steps in [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent).
* A granted consent, with its `consent_id` and the approved `care_contexts[].id`.
* A webhook endpoint registered with Eka that verifies the `Eka-Webhook-Signature` header. See [Webhook signature](/docs/webhooks/webhook-signature).
* A way to decrypt: either the [Ecdh decrypt](/api-sdk/hie-cm/care-contexts/ecdh/decrypt) call, or the [abdm-ecdh library](/docs/hie-cm/care-contexts/ecdh-encryption) in Go, Python or Java.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant HIP
  participant Eka
  participant App as Your app
  HIP->>Eka: encrypted records for the consent
  Eka-->>App: webhook abha.hiu_data_push
  App-->>Eka: 200 within 5 seconds
  App->>Eka: POST /abdm/v1/ecdh/decrypt
  App->>Eka: POST /abdm/v1/hiu/care-context/data/on-push
```

## Steps

**1. Receive the push and acknowledge it**

Eka sends [`abha.hiu_data_push`](/docs/hie-cm/webhooks/hiu-data-push) when a HIP pushes records for your consent. Verify the signature and reply `200` within 5 seconds; Eka retries on any other status. Decrypt after you reply, so the 5 seconds are not spent on decryption.

From `data`, keep:

* `consent_id` and `transaction_id`: you send both back in the acknowledge step. The webhook carries a top-level `transaction_id` and a `data.transaction_id`; which of the two fields on-push expects is not yet confirmed.

- `entries`: one per care context, each with `care_context_id`, `content` (the encrypted FHIR bundle), `checksum` and `media` (`application/fhir+json`).
- `key_information`: the sender's key material, with `dh_public_key.key_value` and `nonce`.
- `hip_id`, `abha_address` and `oid`: which HIP and which patient the records belong to.

Match `consent_id` against the consents you raised.

**2. Decrypt each entry**

Call [Ecdh decrypt](/api-sdk/hie-cm/care-contexts/ecdh/decrypt) once per entry, or decrypt locally with the [abdm-ecdh library](/docs/hie-cm/care-contexts/ecdh-encryption). Map the fields like this:

| Decrypt field | Value |
| - | - |
| `encrypted_data` | `entries[].content` |
| `sender_public_key` | `key_information.dh_public_key.key_value` |
| `sender_nonce` | `key_information.nonce` |
| `receiver_private_key` | your stored `private_key` |
| `receiver_nonce` | your stored `nonce` |

`key_information.dh_public_key` is the HIP's (sender's) public key; your own key is the private key you registered with your keyset.

The response carries `decrypted_data`, the FHIR bundle as plain text. Hash the decrypted bundle and compare the result with `entries[].checksum`: the checksum is computed over the plain-text FHIR data, not the encrypted content. Parse the bundle as JSON.

**3. Report the parsing status**

Call [Push FHIR parsing status](/api-sdk/hie-cm/care-contexts/data-on-push) with:

* `consent_id`.
* The `transaction_id` from the webhook. Which of the two fields is not yet confirmed.
* One `status_response` item per entry, with `care_context_id`, `success` (`true` if you decrypted and parsed it), and a `description` when it failed.

Eka returns `202 Accepted`.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `consent_id` | `abha.hiu_data_push` | As long as you keep the records | The on-push call; tying records to the consent for audit |
| `transaction_id` (which of the two fields is not yet confirmed) | `abha.hiu_data_push` | Until on-push returns `202` | The on-push call |
| `care_context_id` | each entry | As long as you keep the record | On-push status; matching the record to the consent |
| Decrypted FHIR bundle | Ecdh decrypt | Until the consent expires or is revoked | Showing the record to your users |
| `hip_id` | `abha.hiu_data_push` | With the record | Knowing which facility a record came from |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Error responses carry `code`, `error` and `source_error` (`code`, `message`). Codes are listed on the [errors page](/docs/hie-cm/errors).

| Situation | Code | Do |
| - | - | - |
| Your endpoint does not reply `200` within 5 seconds | none | Eka retries; reply first, decrypt after |
| Decryption fails | none from Eka if you use the library | Check you used the private key and nonce registered at the time of the consent; report the entry with `success` `false` |
| Ecdh decrypt rejects the body | `ABDM-1006`, `ABDM-1010` | Check every field is the Base64 value from the webhook or your store |
| Consent artefact expired | `ABDM-1061` | Do not use the records; raise a new consent |
| Transaction not recognised on on-push | `ABDM-1017`, `ABDM-1052` | Send the `transaction_id` from the same webhook; which of the two fields is not yet confirmed |
| HIP unavailable or no acknowledgement from the HIP | `ABDM-1401`, `ABDM-1402` | No records arrive from that HIP |
| No webhook arrives after the consent is granted | none | Check your keyset is registered and your webhook endpoint is reachable; check whether Eka stores the data for you |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

Sandbox base URL: `https://api.dev.eka.care`.&#x20;

* [ ] Run [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent) to a granted consent
* [ ] `abha.hiu_data_push` arrives; your endpoint replies `200` within 5 seconds
* [ ] Each entry decrypts to a FHIR bundle with Ecdh decrypt and with the abdm-ecdh library, and both give the same result
* [ ] On-push with every entry `success` `true` returns `202`
* [ ] Decrypt with a wrong private key; report that entry with `success` `false`


# Request a patient's consent as a HIU
Source: https://developer.eka.care/docs/hie-cm/workflows/hiu-request-consent

Register your encryption key, raise a consent request for a patient's records, and track it until the patient grants or denies it.

## In short

* Register your keyset once, unless Eka stores the data for you.
* Create the consent request and keep `consent_init_id`.
* `abha.consent_update` reports the patient's decision, and Consent List gives the `consent_id`.

## When to use this

You are a Health Information User (HIU) and you need a patient's records from one or more Health Information Providers (HIPs). This workflow raises the consent request and follows it to a decision. Once the patient approves, Eka drives the ABDM gateway callbacks that ask each HIP for the data; you do nothing in between. Receiving the records is the next workflow, [Receive and decrypt records as a HIU](/docs/hie-cm/workflows/hiu-receive-data).

A PHR app that pulls records on the patient's behalf is also a HIU and uses the same calls.

## Before you start

* A bearer token for the API. See [Authorization](/api-sdk/auth/getting-started).
* Your software set up as a HIU, with the facility onboarded on Eka.&#x20;
* A webhook endpoint registered with Eka that verifies the `Eka-Webhook-Signature` header. See [Webhook signature](/docs/webhooks/webhook-signature).
* The patient's ABHA address (`health_id`), and the patient's Eka user id (`oid`) if they are registered on Eka.
* Your `clinic_id` and the requesting doctor's `d_oid`.&#x20;
* The HIP ids and care context references you want, if you know them.
* A decision on where the records go. If you manage the data on your side, you need the keyset steps. If Eka stores the data for you, skip them.&#x20;

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant GW as ABDM gateway and HIPs
  participant Patient as Patient's PHR app
  App->>Eka: GET /abdm/v1/ecdh/keys
  App->>Eka: PATCH /abdm/v1/hiu/keyset
  App->>Eka: POST /abdm/v1/consents/create
  Eka->>GW: consent request
  GW-->>Patient: request appears in the inbox
  Patient-->>GW: approve or deny
  Eka-->>App: webhook abha.consent_update
  App->>Eka: POST /abdm/v1/consents/list
  App->>Eka: POST /abdm/v1/consents/details
```

## Steps

**1. Generate a key pair (once)**

Call [Ecdh keys](/api-sdk/hie-cm/care-contexts/ecdh/keys) to generate a key pair. The response carries `private_key`, `public_key` and `nonce`. Store `private_key` and `nonce` securely on your side; you need both to decrypt every record you receive. You can generate the key material locally with the [abdm-ecdh library](/docs/hie-cm/care-contexts/ecdh-encryption) instead of calling Eka.

Skip this step and the next if Eka stores the data for you.

**2. Register your public keyset (once, and on rotation)**

Send `public_key` and `nonce` to [Update public keyset](/api-sdk/hie-cm/care-contexts/hiu-keys). Both fields are required. Eka shares them with each HIP so the HIP can encrypt the records for you. You can update the keyset at any time.

**3. Create the consent request**

Call [Consent Create](/api-sdk/hie-cm/consents/consent-create). The body names:

* `patient`: the patient's `health_id` (ABHA address) and `oid`.
* `hiu`: your `clinic_id`, `d_oid` and the `requester`.
* `purpose`: one of `Self Requested`, `Care management`, `Public Health`, `Disease Specific Health Research`.
* `record_types`: the record types you want, such as `Prescription` or `DischargeSummary`.
* `period`: `from` and `to` for the records' date range, and `expiry` for when the consent ends.
* `hip_identifier` and `care_contexts`: the HIP and the care contexts (`cc_ref`, `patient_ref`) to fetch from.

Keep `consent_init_id` from the response.

**4. Wait for the patient's decision**

Wait for the [`abha.consent_update`](/docs/hie-cm/webhooks/consent-update) webhook. Acknowledge it as described in [Webhooks](/docs/hie-cm/webhooks#delivery-signature-and-acknowledgement). Read `data.notification.consentRequestId`, `data.notification.status` and `data.notification.consentArtefacts.id`.

The webhook fires whenever the consent is updated, so expect it more than once for the same request. Treat the latest status as current.

**5. Find the consent and its status**

Call [Consent List](/api-sdk/hie-cm/consents/consent-list) with the same `hiu` (`clinic_id`, `d_oid`) and `patient` (`health_id`, `oid`) you used in Create. Each entry in `consents` carries `consent_init_id`, `consent_id`, `status`, `hi_types` and `period`. Match on `consent_init_id` and keep `consent_id`.

If `status` shows the request was denied or has expired, stop here and close the request on your side.

**6. Read what the patient approved**

Call [Consent Details](/api-sdk/hie-cm/consents/consent-details) with `consent_id` and the patient's `health_id`. Each entry in `data` names one `hip` (`id`, `name`) and the `care_contexts` the patient approved from it, each with `id`, `display`, `status` and `documents`.

Keep each `care_contexts[].id`. [Receive and decrypt records as a HIU](/docs/hie-cm/workflows/hiu-receive-data) uses it for either storage choice.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `private_key` | Ecdh keys, or the abdm-ecdh library | As long as any consent registered under it can still deliver records | Decrypting every record on `abha.hiu_data_push` |
| `nonce` | Ecdh keys, or the abdm-ecdh library | Same as `private_key` | Decrypting every record |
| `consent_init_id` | Consent Create | Until the consent ends | Matching the request in Consent List |
| `consent_id` | Consent List | Until the consent ends, and as long as you keep records fetched under it for audit | Consent Details, matching `abha.hiu_data_push`, acknowledging on-push |
| `consentArtefacts.id` | `abha.consent_update` | Until the consent ends | Tying a status change to a HIP's artefact |
| `care_contexts[].id` | Consent Details | As long as you keep the records | Matching pushed entries, or reading them from Eka's records product |
| `status` | `abha.consent_update`, Consent List | Until the consent ends | Whether you may still use the records |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Error responses carry `code`, `error` and `source_error` (`code`, `message`).

| Situation | Code | Do |
| - | - | - |
| Malformed or incomplete body | `ABDM-1006`, `ABDM-1010` | Fix the request against the reference page and resend |
| Date range rejected | `ABDM-1063` | Check that `period.from` is before `period.to` |
| Purpose rejected | `ABDM-1046`, `ABDM-1047` | Send one of the four `purpose` values exactly as the spec writes them |
| HIU id not recognised | `ABDM-1040` | Check your facility's HIU onboarding |
| Consent id not recognised | `ABDM-1039` | Check you sent `consent_id` from Consent List, not `consent_init_id` |
| Consent not granted or expired | `ABDM-1062`, `ABDM-1061` | Raise a new consent request; do not retry the old one |
| Too many requests | `ABDM-1022` | Back off and retry |
| Gateway or HIP unavailable | `ABDM-1024`, `ABDM-1028`, `ABDM-1401` | Retry later |
| `abha.consent_update` never arrives | none | Check your webhook registration and signature check, then read the status from Consent List |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

* [ ] Generate a key pair and register the keyset; the call returns `200`
* [ ] Create a consent request for a sandbox patient; keep `consent_init_id`
* [ ] Approve the request as the patient; `abha.consent_update` arrives and your endpoint replies `200` within 5 seconds
* [ ] Consent List shows the request with a `consent_id`; Consent Details lists the approved care contexts
* [ ] Deny a second request as the patient; your app closes it
* [ ] Send a `period` with `from` after `to`; confirm the error code


# Hold the ABHA Gateway session
Source: https://developer.eka.care/docs/hie-cm/workflows/hold-gateway-session

Check whether the patient's ABHA Gateway session is live and renew it with a mobile OTP when it has expired.

## In short

* Patient-scoped calls without a live ABHA Gateway session return HTTP `491`.
* Check the session with Status, and renew it with Init and Verify on a mobile OTP.
* Once the session is live, retry the call that returned `491`.

## When to use this

Registering or creating an ABHA opens a session for the patient with the ABHA Gateway. Whether logging in also opens one is not yet confirmed.  The session expires after a period. Patient-scoped calls made without a live session return HTTP `491`. Run this workflow before a patient-scoped call such as fetching the profile, and whenever a call returns `491`.

This workflow renews a session for a patient whose ABHA you already hold. To find or create the ABHA in the first place, use [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha) or one of the create workflows.

## Before you start

* A client access token, sent as a Bearer token on every call. See [Client login](/api-sdk/auth/client-login).
* The patient's `oid` and `abha_address`, stored when the ABHA was created or the patient logged in. Session Status needs the `oid` in the `X-Pt-Id` header.
* Access to the patient's phone for the mobile OTP.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant Patient as Patient's phone
  App->>Eka: GET /abdm/v1/session/status
  alt logged_in is true
    Note over App,Eka: Session is live, continue with your call
  else logged_in is false, or a call returned 491
    App->>Eka: POST /abdm/v1/session/init
    Eka-->>Patient: Mobile OTP
    App->>Eka: POST /abdm/v1/session/verify
  end
```

## Steps

**1. Check the session**

Call [Status](/api-sdk/hie-cm/session/status) with the patient's `oid` in the `X-Pt-Id` header. The response carries `logged_in`, `kyc_verified` and `hpr_id`.

* `logged_in` is `true`: the session is live. Continue with the patient-scoped call you were about to make.
* `logged_in` is `false`: renew the session with the next two steps.

**2. Send the mobile OTP**

Send the patient's `abha_address` to [Init](/api-sdk/hie-cm/session/init), with the `oid` in the `X-Pt-Id` header or the `oid` query parameter. An OTP goes to the patient's mobile. The response carries `txn_id`.&#x20;

**3. Verify the OTP**

Send `txn_id` and `otp` to [Verify](/api-sdk/hie-cm/session/verify), with the same `oid`. The response carries `token`, the user's access token, and `refresh_token`. The session is live again. Retry the call that returned `491`.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `oid` | The create or login workflow | Permanently, on the patient record | `X-Pt-Id` header on every call here |
| `abha_address` | The create or login workflow | Permanently, on the patient record | Session Init |
| `txn_id` | Session Init | Until Session Verify returns | Session Verify |
| `token` | Session Verify | Until the session expires | Not documented |
| `refresh_token` | Session Verify | Not documented | Not documented |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Error responses carry `code`, `error` and `source_error`. `source_error.code` holds codes such as `MIS-1013`. See [Error codes](/docs/hie-cm/errors).&#x20;

| Situation | Code | Do |
| - | - | - |
| Session expired on a patient-scoped call | HTTP `491` | Run Session Init and Session Verify, then retry the call. |
| Session Status called without `X-Pt-Id` | Not documented | Send the patient's `oid` in `X-Pt-Id`. |
| Wrong OTP | `MIS-1013` | Ask the patient to re-enter the OTP. |
| Too many OTP requests or wrong attempts | `ABDM-1100` | Tell the patient to try again in 30 minutes. |
| No ABHA found for the address | `ABDM-1012`, `ABDM-1110` | Check the stored `abha_address` against the patient record. |
| Expired or unknown transaction | `ABDM-1017`, `MIS-1026` | Start again from Session Init. |
| ABDM or a dependent service is down | `ABDM-1019`, `ABDM-1024`, `ABDM-1004` | Retry later. |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

Run against the sandbox base URL `https://api.dev.eka.care`, with an ABHA you created on sandbox.&#x20;

* [ ] Straight after creating an ABHA, Session Status returns `logged_in: true`.
* [ ] After the session expires, Session Status returns `logged_in: false`. Session Init and Session Verify return a `token`; Session Status returns `logged_in: true` again.
* [ ] A patient-scoped call such as [Profile Details](/api-sdk/hie-cm/profile/details/profile-details) returns `491` on an expired session and succeeds after renewal.
* [ ] Wrong OTP on Session Verify: `MIS-1013`. Record the code you receive; the expected code is not confirmed.


# Log in to HPR with a mobile OTP
Source: https://developer.eka.care/docs/hie-cm/workflows/hpr-mobile-login

Verify a returning healthcare professional with an OTP to their mobile and check their HPR ID.

## When to use this

A healthcare professional who has registered before signs in to your HMS with their mobile rather than Aadhaar. You send an OTP to their mobile, verify it, and check the HPR ID. This is the alternative entry for returning professionals.

For a first-time registration, use [Create an HPR ID with Aadhaar OTP](/docs/hie-cm/workflows/create-hpr-id).

## Before you start

* A bearer token for the Eka API. See [Authorization](/api-sdk/auth/getting-started).
* The headers your integration sends on ABDM Connect calls. Each operation accepts `X-Pt-Id`, `X-Partner-Pt-Id` and `X-Hip-Id`.&#x20;
* The professional's mobile number.
* The professional's HPR ID, which Check If HPR is Available takes as `hprId`.&#x20;

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant Phone as Professional's phone
  App->>Eka: POST /abdm/nhpr/v1/hpr/aadhaar/mobile/init
  Eka-->>Phone: OTP to the mobile
  App->>Eka: POST /abdm/nhpr/v1/hpr/aadhaar/mobile/verify
  App->>Eka: POST /abdm/nhpr/v1/hpr/aadhaar/check/available
```

## Steps

**1. Send the mobile OTP**

Send `mobile_num` to [Get Mobile OTP](/api-sdk/hie-cm/nhpr-abdm/hpr/get-mobile-otp). The body also accepts `txn_id`.  The response carries `txn_id`, `mobile_num` and `hint`. Unlike the other NHPR calls, the spec does not wrap this response in `data`.&#x20;

Keep `txn_id`. The professional receives an OTP.

**2. Verify the mobile OTP**

Send `txnId` (the `txn_id` from step 1, in camel case) and the `otp` the professional reads out to [Verify Mobile OTP](/api-sdk/hie-cm/nhpr-abdm/hpr/verify-mobile-otp). The response `data` carries `txn_id`, `mobile_num` and `hint`.

**3. Check the HPR ID**

Send `hprId` to [Check If HPR is Available](/api-sdk/hie-cm/nhpr-abdm/hpr/check-hpr-available). Read `available` in the response `data`.&#x20;

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `txn_id` | Get Mobile OTP | Until Verify Mobile OTP returns | Sent as `txnId` to Verify Mobile OTP |
| `mobile_num` | The professional | On the staff record | Next login |
| `hprId` | The staff record, saved by [Create an HPR ID with Aadhaar OTP](/docs/hie-cm/workflows/create-hpr-id) | Permanently, on the staff record | Check If HPR is Available |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Errors come back as `4XX` or `5XX` with a body carrying `code`, `error` and `source_error` (`code`, `message`). Read `source_error.code` and look it up on the [errors page](/docs/hie-cm/errors).

| Situation | Code | Do |
| - | - | - |
| Malformed body, such as a missing `mobile_num` | `ABDM-1006` | Fix the request; do not retry unchanged |
| Mobile not registered with HPR | | Send the professional to [Create an HPR ID with Aadhaar OTP](/docs/hie-cm/workflows/create-hpr-id) |
| Wrong OTP | `MIS-1013` | Let the professional enter it again |
| Too many OTP requests or attempts | `ABDM-1100` | Wait 30 minutes, then restart from Get Mobile OTP |
| Transaction expired or unknown | `ABDM-1017` or `MIS-1026` | Restart from Get Mobile OTP |
| ABDM registry unavailable | `ABDM-1019` or `ABDM-1024` | Retry later |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

Run against the sandbox base URL `https://api.dev.eka.care`.&#x20;

* [ ] Happy path: Get Mobile OTP, Verify Mobile OTP, Check If HPR is Available returns `available` for the professional's `hprId`
* [ ] Wrong OTP once, then the correct OTP
* [ ] A mobile with no HPR account


# Link a care context as a HIP
Source: https://developer.eka.care/docs/hie-cm/workflows/link-care-context-hip

Register a visit, test or document against the patient's ABHA so it can be discovered and shared.

## 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](/docs/hie-cm/workflows/serve-data-on-fetch).

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](/docs/hie-cm/workflows/hip-discovery-and-link).

## Before you start

* A client access token, sent as a Bearer token. See [Authorization](/api-sdk/auth/getting-started).
* Your facility onboarded as a Health Information Provider (HIP), with its HIP ID. See [Milestone 4](/docs/hie-cm/flows/m4).
* A webhook URL registered with Eka that can receive `abha.link_care_context`, and the means to verify the [webhook signature](/docs/webhooks/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](/docs/hie-cm/workflows/create-abha-aadhaar-otp) or [Log in to an existing ABHA](/docs/hie-cm/workflows/login-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

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant ABDM as ABDM gateway
  App->>Eka: POST /abdm/v1/care-contexts/link
  Eka-->>App: 202 Accepted
  Eka->>ABDM: Link care context
  ABDM-->>Eka: Linking result
  Eka-->>App: webhook abha.link_care_context
  opt Notify the patient (timing not yet confirmed)
    App->>Eka: POST /abdm/v1/care-contexts/sms/notify
  end
```

## Steps

**1. Link the care context**

Call [Care context linking](/api-sdk/hie-cm/care-contexts/link/hip-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](/docs/hie-cm/workflows/serve-data-on-fetch) 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`](/docs/hie-cm/webhooks/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](/api-sdk/hie-cm/care-contexts/records/notify) 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

| Field | From | Keep | For |
| - | - | - | - |
| `abha_address`, `oid` | ABHA creation or login | Forever, on the patient record | Every link call for this patient |
| `care_context_id` | You, sent in the link call | Forever, on the visit or document | Matching the status webhook; answering `abha.hip_data_fetch` later |
| Whether `data` was sent | Your decision in step 1 | Forever, on the care context | Knowing whether you must serve this care context on a fetch request |
| `status` | `abha.link_care_context` | Forever, on the care context | Showing the visit as linked; retrying when `ERRORED` |
| The FHIR bundle, if you keep the data | Your clinical system | As long as the care context is linked | Serving it on a fetch request |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), 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](/docs/hie-cm/errors); match the one you receive there.

| Situation | Code | Do |
| - | - | - |
| Request body malformed or a field invalid | `ABDM-1006`, `ABDM-1010` | Fix the request against the reference page and resend |
| ABHA address or number not recognised | `ABDM-1051` | Check the `abha_address` saved on the patient record |
| Wrong HIP ID | `ABDM-1035` (Invalid HIP ID) | `ABDM-1035` also means "OTP does not match" on the errors page. Tell them apart by HTTP status (`500` for Invalid HIP ID, `400` for the OTP) and `source_error.message`. For Invalid HIP ID, check the `X-Hip-Id` header against your onboarded HIP ID |
| Too many requests | `ABDM-1022` | Back off and retry |
| Gateway or a dependent service down | `ABDM-1019`, `ABDM-1024`, `ABDM-1048` | Retry later |
| Status webhook reports `ERRORED` | `data.error` in the webhook | Read the reason; correct and link again |

## Test it

The [testing page](/docs/hie-cm/testing) 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


# Log in to an existing ABHA
Source: https://developer.eka.care/docs/hie-cm/workflows/login-abha

Log a patient in to an ABHA they already hold, by ABHA address, Aadhaar or mobile.

## In short

* Log in by ABHA address, mobile or Aadhaar, each with an OTP.
* Every route ends with `skip_state` set to `abha_end` and the patient's `oid`.
* Each call takes the `txn_id` from the most recent response.

## When to use this

The patient already has an ABHA and can identify it by one of: their ABHA address, their Aadhaar number, or a mobile number. They authenticate with an OTP. All three routes end with `skip_state` set to `abha_end` and give you the patient's `oid`.

Pick the route from what the patient can offer:

* **ABHA address** (`shyam@abdm`): two calls, init and verify.
* **Mobile number**: init, verify, then pick one of the ABHA addresses on that mobile.
* **Aadhaar number**: init, verify, then auto-login into one of the ABHA addresses on that Aadhaar.

If the patient has no ABHA, use [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp) or [Create an ABHA address with mobile OTP](/docs/hie-cm/workflows/create-abha-mobile-otp).

## Before you start

* A client access token, sent as a Bearer token on every call. See [Client login](/api-sdk/auth/client-login).
* Your facility onboarded as a Health Information Provider (HIP).
* In hand: the patient's ABHA address, Aadhaar number or mobile number, and access to the phone that receives the OTP.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant Patient as Patient's phone
  opt ABHA address route, check which methods are allowed
    App->>Eka: POST /abdm/na/v1/profile/login/methods
  end
  opt Search route, find KYC-verified ABHAs by mobile
    App->>Eka: POST /abdm/v1/profile/search
  end
  App->>Eka: POST /abdm/na/v1/profile/login/init
  Eka-->>Patient: OTP
  App->>Eka: POST /abdm/na/v1/profile/login/verify
  alt ABHA address route
    Note over App,Eka: skip_state is abha_end, login complete
  else Mobile route
    App->>Eka: POST /abdm/na/v1/profile/login/phr
  else Aadhaar route
    App->>Eka: POST /abdm/na/v1/registration/aadhaar/auto-login
  end
```

## Steps

**1. Check the login methods (ABHA address route)**

Send `abha_address` to [Search Auth Methods](/api-sdk/hie-cm/login/methods). The response carries `auth_methods` and `blocked_methods`. Offer the patient only methods in `auth_methods`.&#x20;

**2. Search by mobile (search route, optional)**

Send `mobile` to [Search](/api-sdk/hie-cm/profile/search/search). It returns KYC-verified ABHA profiles on that mobile in `profiles`, each with an `index` and `abha_address`, plus a `txn_id`. The patient picks one. Pass its `index` as `identifier` and the `txn_id` to the next step with `method` set to `search`.&#x20;

**3. Send the OTP**

Send `method`, `identifier` and `otp_system` to [Generate OTP](/api-sdk/hie-cm/login/init):

* ABHA address route: `method` is `phr_address`, `identifier` is the ABHA address.
* Mobile route: `method` is `mobile`, `identifier` is the mobile number.
* Aadhaar route: `method` is `aadhaar_number`, `identifier` is the Aadhaar number.
* `method` also accepts `abha_number`.&#x20;

`otp_system` is `abdm` or `aadhaar`.&#x20;

The response carries `txn_id` and a `hint`. Keep `txn_id`; every later call takes the `txn_id` from the most recent response.

**4. Verify the OTP**

Send `txn_id` and `otp` to [Verify OTP](/api-sdk/hie-cm/login/verify). The response carries `skip_state`, `abha_profiles`, `profile`, `eka.oid` and a new `txn_id`. Branch on the route and `skip_state`:

* ABHA address route: `skip_state` is `abha_end`. Login is complete. Stop here.
* Mobile route: `abha_profiles` lists the ABHA addresses on the mobile. The patient picks one. Go to "Complete the mobile login".&#x20;
* Aadhaar route: `skip_state` is `abha_create`. If `abha_profiles` is non-empty, the patient picks one and you go to "Complete the Aadhaar login". If it is empty, the patient has no ABHA address on this Aadhaar; create one.&#x20;

**5. Complete the mobile login**

Send `txn_id` and the chosen address as `phr_address` to [Login](/api-sdk/hie-cm/login/login). The response carries `skip_state` set to `abha_end`, `profile` and `eka.oid`.

**6. Complete the Aadhaar login**

Send `txn_id` and the chosen `abha_address` to [Auto Login](/api-sdk/hie-cm/enrollment/aadhaar/auto-login). The response carries `skip_state` set to `abha_end`, `profile`, `eka.oid`, `token` and `refresh_token`.

Whether login also opens the patient's ABHA Gateway session is not yet confirmed; the session overview names only registration and creation.  When a session expires, renew it with [Hold the ABHA Gateway session](/docs/hie-cm/workflows/hold-gateway-session) rather than logging in again.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `txn_id` | The latest response in this workflow | Until login completes | Every call in this workflow |
| `eka.oid` | The call that returns `abha_end` | Permanently, on the patient record | The `X-Pt-Id` header or `oid` query on every later call for this patient |
| `profile.abha_address` | The call that returns `abha_end` | Permanently, on the patient record | Care context linking, gateway session |
| `profile.abha_number` | The call that returns `abha_end` | Permanently, on the patient record, when present | ABHA card, later logins |
| `token`, `refresh_token` | Auto Login | Not documented | Not documented |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Error responses carry `code`, `error` and `source_error`. `source_error.code` holds codes such as `MIS-1013`. See [Error codes](/docs/hie-cm/errors).&#x20;

| Situation | Code | Do |
| - | - | - |
| Wrong OTP | `MIS-1013` | Ask the patient to re-enter the OTP. |
| Too many OTP requests or wrong attempts | `ABDM-1100` | Tell the patient to try again in 30 minutes. |
| Patient blocked | `ABDM-1027` | Tell the patient to try again after 24 hours. |
| No ABHA found for the identifier | `ABDM-1110`, `ABDM-1012` | Offer to create an ABHA instead. |
| Invalid ABHA number | `ABDM-1013` | Ask the patient to check the number. |
| Mobile or Aadhaar not found | `ABDM-1111`, `ABDM-1112` | Ask the patient to check it, or try another route. |
| Method not allowed for this ABHA | `ABDM-1113`, `ABDM-1114`, `ABDM-1115` | Offer a method from `auth_methods` in Search Auth Methods. |
| Expired or unknown transaction | `ABDM-1017`, `MIS-1026` | Start again from Generate OTP. |
| Too many requests | `ABDM-1022` | Back off and retry. |
| ABDM or a dependent service is down | `ABDM-1019`, `ABDM-1024`, `ABDM-1004` | Retry later. |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

Use an ABHA you created on sandbox through one of the create workflows.&#x20;

* [ ] ABHA address route: Search Auth Methods, Generate OTP with `phr_address`, Verify OTP returns `abha_end` and `eka.oid`.
* [ ] Mobile route: Generate OTP with `mobile`, Verify OTP, Login with one address from `abha_profiles` returns `abha_end`.
* [ ] Aadhaar route: Generate OTP with `aadhaar_number`, Verify OTP returns `abha_create` with a non-empty `abha_profiles`, Auto Login returns `abha_end`.
* [ ] The `eka.oid` from login equals the one stored when the ABHA was created.
* [ ] Wrong OTP once: `MIS-1013`. Record the code you receive; the expected code is not confirmed.
* [ ] Unknown ABHA address on Search Auth Methods: an error from the failure table.


# Manage the ABHA profile and KYC
Source: https://developer.eka.care/docs/hie-cm/workflows/manage-profile-and-kyc

Read and update the patient's ABHA profile, show the ABHA card and QR code, run KYC on a mobile-created address, and delete the profile.

## In short

* Cache the profile, QR code and card; evict them after an update or KYC.
* Update Profile must send every field Profile Details returned.
* After KYC, check that `kyc_verified` is `true` and `abha_number` is set.

## When to use this

The patient has an ABHA and is logged in. Use this workflow to:

* show their ABHA profile, card and QR code
* correct their details
* run KYC on an ABHA address that was created with a mobile OTP.

Deleting the profile is also here; it is irreversible.

These calls are independent. Run the ones your screen needs, in any order, except that KYC is a sequence of init then verify.

## Before you start

* A client access token, sent as a Bearer token on every call. See [Client login](/api-sdk/auth/client-login).
* The patient's `oid`, stored when the ABHA was created or the patient logged in. Every call here except Search takes it in the `X-Pt-Id` header or the `oid` query parameter.
* A live ABHA Gateway session for the patient. Check it first with [Hold the ABHA Gateway session](/docs/hie-cm/workflows/hold-gateway-session); a `491` means the session has expired.
* For KYC: the patient's 14-digit ABHA number or 12-digit Aadhaar number, and access to the phone that receives the OTP.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant Patient as Patient's phone
  App->>Eka: GET /abdm/v1/profile
  App->>Eka: GET /abdm/v1/profile/asset/qr
  App->>Eka: GET /abdm/v1/profile/asset/card
  opt Patient corrects their details
    App->>Eka: PATCH /abdm/v1/profile
  end
  opt kyc_verified is not true
    App->>Eka: POST /abdm/v1/profile/kyc/init
    Eka-->>Patient: OTP
    opt OTP did not arrive
      App->>Eka: POST /abdm/v1/profile/kyc/resend
    end
    App->>Eka: POST /abdm/v1/profile/kyc/verify
  end
  opt Patient deletes their profile
    App->>Eka: DELETE /abdm/v1/profile
  end
```

## Steps

**1. Fetch the profile**

Call [Profile Details](/api-sdk/hie-cm/profile/details/profile-details). The response carries the patient's `abha_address`, `abha_number` and `kyc_verified`, with the other profile fields listed on the reference page.

Cache the response on your side. Do not call it on every page load. Evict the cache when the profile is updated.

**2. Show the QR code**

Call [ABHA QR Code](/api-sdk/hie-cm/profile/cards/qr-code). The response is JSON with no fixed structure; it varies with how the ABHA was created. Generate the QR code from the whole response body rather than from named fields. Cache it and evict it when the profile is updated.&#x20;

**3. Show the ABHA card**

Call [ABHA card](/api-sdk/hie-cm/profile/cards/abha-card). The response is the card as a PNG image (`image/png`). Cache it and evict it when the profile is updated.

**4. Update the profile**

Send the profile to [Update Profile](/api-sdk/hie-cm/profile/details/update-profile). The request must include every field that Profile Details returned, not only the changed ones. A successful update returns `204` with no body. Evict your cached profile, QR code and card.

For a KYC-verified ABHA, name, gender and date of birth cannot be changed.&#x20;

**5. Start KYC (only if kyc\_verified is not true)**

Send `method` and `identifier` to [Kyc Init](/api-sdk/hie-cm/profile/kyc/kyc-init). `method` is `abha-number` with the 14-digit ABHA number as `identifier`, or `aadhaar` with the 12-digit Aadhaar number. The request also takes `user_x_token`, the user authorization token.&#x20;

An OTP goes to the patient. The response carries `txn_id`. If the OTP does not arrive, send `txn_id` to [Kyc Resend](/api-sdk/hie-cm/profile/kyc/kyc-resend) and use the `txn_id` it returns.&#x20;

**6. Verify KYC**

Send `txn_id`, `otp` and `user_x_token` to [Kyc Verify](/api-sdk/hie-cm/profile/kyc/kyc-verify). The response carries `txn_id`. Fetch the profile again and check that `kyc_verified` is `true` and `abha_number` is set. Evict your cached QR code and card.&#x20;

**7. Delete the profile (only on the patient's request)**

Call [Delete Profile](/api-sdk/hie-cm/profile/details/delete). It removes the profile and every associated document, vital record and related data from Eka, with no recovery. The ABHA metadata stays in the ABDM system, because ABDM offers no delete. A successful delete returns `204`. Ask the patient to confirm before you call it, and clear the `oid` and cached assets from your patient record afterwards.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| Profile response | Profile Details | Until the next Update Profile or KYC Verify | Showing the profile without calling the API on every page load; the full body for Update Profile |
| QR code response | ABHA QR Code | Until the next Update Profile or KYC Verify | Showing the QR code |
| ABHA card image | ABHA card | Until the next Update Profile or KYC Verify | Showing or printing the card |
| `kyc_verified` | Profile Details | With the cached profile | Deciding whether to offer KYC and which fields can be edited |
| `txn_id` | Kyc Init or Kyc Resend | Until Kyc Verify returns | Kyc Resend and Kyc Verify |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Error responses carry `code`, `error` and `source_error`. `source_error.code` holds codes such as `MIS-1013`. See [Error codes](/docs/hie-cm/errors).&#x20;

| Situation | Code | Do |
| - | - | - |
| Gateway session expired | HTTP `491` | Renew it with [Hold the ABHA Gateway session](/docs/hie-cm/workflows/hold-gateway-session), then retry. |
| Update Profile missing fields | `ABDM-1006`, `ABDM-1010` | Send every field Profile Details returned. |
| Wrong KYC OTP | `MIS-1013` | Ask the patient to re-enter the OTP. |
| Too many OTP requests or wrong attempts | `ABDM-1100` | Tell the patient to try again in 30 minutes. |
| ABHA address does not match the KYC details | `ABDM-1043` | Not documented yet. |
| Invalid ABHA number on KYC | `ABDM-1013` | Ask the patient to check the number. |
| Expired or unknown KYC transaction | `ABDM-1017`, `MIS-1026` | Start again from Kyc Init. |
| ABDM or a dependent service is down | `ABDM-1019`, `ABDM-1024` | Retry later. |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

Use a patient whose ABHA you created on sandbox and whose session is live.&#x20;

* [ ] Profile Details returns the `abha_address` you stored at creation.
* [ ] ABHA QR Code returns JSON you can encode as a QR code; ABHA card returns an image.
* [ ] Update Profile with every field from Profile Details and one changed value returns `204`; Profile Details shows the change.
* [ ] On a mobile-created address: Kyc Init, Kyc Verify, then Profile Details shows `kyc_verified: true`.
* [ ] Wrong OTP on Kyc Verify: `MIS-1013`. Record the code you receive; the expected code is not confirmed.
* [ ] Profile Details on an expired session returns `491`.
* [ ] Delete Profile on a throwaway sandbox ABHA returns `204`; Profile Details for that `oid` then fails.


# Approve, deny or revoke a consent in a PHR app
Source: https://developer.eka.care/docs/hie-cm/workflows/phr-act-on-consent

Show the patient their pending consent requests, record their decision with their consent PIN, and revoke access later.

## In short

* Show the patient each pending request, then approve or deny it after their consent PIN.
* Approval creates one consent artefact per HIP.
* The patient can later revoke any artefact on its own.
* Whether `abha.consent_update` reaches a PHR app is not confirmed; fall back to List Requests.

## When to use this

Your app is a personal health record (PHR) app. A Health Information User (HIU) such as a doctor, hospital, insurer or another PHR app has asked for the patient's records. This workflow shows the patient the request, records their decision, and lets them revoke a granted consent later. On approval, ABDM generates one consent artefact per Health Information Provider (HIP), and the patient can revoke each artefact on its own.

To stop asking the patient for every request from a trusted source, set up auto-approval instead: [Set up the patient's health locker](/docs/hie-cm/workflows/set-up-health-locker).

## Before you start

* A bearer token for the API. See [Authorization](/api-sdk/auth/getting-started).
* A live ABHA Gateway session for the patient. Every consent operation needs one. See [User Session](/docs/hie-cm/session/getting-started).
* The patient's Eka user id (`oid`), sent as the `X-Pt-Id` header.&#x20;
* A webhook endpoint registered with Eka that verifies the `Eka-Webhook-Signature` header. See [Webhook signature](/docs/webhooks/webhook-signature).

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your PHR app
  participant Eka
  participant GW as ABDM gateway
  App->>Eka: GET /abdm/v1/requests
  App->>Eka: GET /abdm/v1/request
  App->>Eka: GET /abdm/v1/consents/pin/exists
  App->>Eka: POST /abdm/v1/consents/pin/set
  App->>Eka: POST /abdm/v1/consents/pin/verify
  alt Patient approves
    App->>Eka: POST /abdm/v1/consents/approve
    Eka->>GW: consent artefacts, one per HIP
  else Patient denies
    App->>Eka: POST /abdm/v1/consents/deny
  end
  Eka-->>App: webhook abha.consent_update (not yet confirmed)
  App->>Eka: POST /abdm/v1/consents/revoke
  Eka-->>App: webhook abha.consent_update (not yet confirmed)
```

## Steps

**1. List the patient's pending requests**

Call [List Requests](/api-sdk/hie-cm/patient-requests/list-requests) with `type` set to `consent` and `status` set to `requested`. Both parameters are required.

Show the patient who is asking (`hiu`, `requester`) and why (`purpose`). Keep the `id` of the request they open. To show granted consents they can revoke, call again with `status` set to `granted`.

**2. Show the request's details**

Call [Requests Get Details](/api-sdk/hie-cm/patient-requests/requests-get-details) with `id` and `type` set to `consent`. The response carries `hi_types` (the record types asked for), `duration` (`from`, `to`), `erase_at`, `access_mode` and `providers`. Each provider names a `hip` (`id`, `name`), its `care_contexts` (`id`, `display`) and, once granted, its `consent_artefact_id`.

Let the patient choose which providers, care contexts and record types to share.

**3. Check whether the patient has a consent PIN**

Call [Consent pin exists](/api-sdk/hie-cm/consents/pin/exists). If `exist` is `true`, go to the verify step. If `false`, set one first.

**4. Set a consent PIN (first time only)**

Ask the patient to choose a PIN and send it as `pin` to [Consent pin set](/api-sdk/hie-cm/consents/pin/set). Eka returns `204`.

**5. Verify the consent PIN**

Ask the patient for their PIN and send it as `pin` to [Consent pin verify](/api-sdk/hie-cm/consents/pin/verify) before you approve or revoke. Eka returns `204`.

**6. Approve or deny**

**To approve,** call [Consent Approve](/api-sdk/hie-cm/consents/consent-approve). Send `id` (the request id) and `consent_artefacts`, both required. Add one `consent_artefacts` item per HIP the patient chose, with `hip_id`, the chosen `care_contexts` (`id`, `display`), `hi_types`, `access_mode` (`view`), `duration` and `erase_at`. Eka returns `204`.

**To deny,** call [Consent Deny](/api-sdk/hie-cm/consents/consent-deny) with `id` and, optionally, the patient's `reason` in plain text. Eka returns `204`.

Then update the request in your inbox. Whether a PHR app receives [`abha.consent_update`](/docs/hie-cm/webhooks/consent-update) for requests the patient acts on is not yet confirmed. If it arrives, reply `200` within 5 seconds and read `data.notification.status`. If it does not, call [List Requests](/api-sdk/hie-cm/patient-requests/list-requests) with `type` set to `consent` and `status` set to `granted`, or `denied` after a denial. Find the request by `id`.

**7. Revoke a granted consent (later)**

When the patient wants to cut off a HIP, call [Requests Get Details](/api-sdk/hie-cm/patient-requests/requests-get-details) for the granted request and read `providers[].consent_artefact_id`. Verify the PIN again, then send the artefact ids to cut off as `consent_artefacts` to [Consent Revoke](/api-sdk/hie-cm/consents/consent-revoke). Eka returns `204`. Artefacts you leave out stay granted.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| Request `id` | List Requests | Until the patient acts, then as long as you show the request in history | Get Details, Approve, Deny |
| `consent_artefact_id` per HIP | Get Details, after grant | Until the artefact is revoked or expires | Revoke |
| Request `status` | `abha.consent_update`, or List Requests | Until it changes | Showing the inbox correctly |
| Whether a PIN is set | Consent pin exists | | Choosing set or verify |

The patient's PIN is not state. Do not store it.

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Error responses carry `code`, `error` and `source_error` (`code`, `message`).

| Situation | Code | Do |
| - | - | - |
| ABHA Gateway session expired | HTTP `491` | Re-run the session OTP, then retry. See [User Session](/docs/hie-cm/session/getting-started) |
| Wrong PIN | Not documented yet | Let the patient retry |
| Patient forgot the PIN | none | Use [Consent pin forgot init](/api-sdk/hie-cm/consents/pin/forgot-init), [Consent pin forgot verify](/api-sdk/hie-cm/consents/pin/forgot-verify) and [Consent pin reset](/api-sdk/hie-cm/consents/pin/reset) |
| Patient wants to change the PIN | none | Send `old` and `new` to [Consent pin change](/api-sdk/hie-cm/consents/pin/change) |
| Missing `id` or `consent_artefacts` | `ABDM-1006`, `ABDM-1010` | Fix the body and resend |
| Request expired before the patient acted | `ABDM-1061` | Tell the patient; the HIU must raise a new request |
| Consent request id not recognised | `ABDM-1039` | Refresh the inbox from List Requests |
| Gateway unavailable | `ABDM-1024`, `ABDM-1048` | Retry later |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

* [ ] Raise a request against a sandbox patient with [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent)
* [ ] It appears in List Requests with `status` `requested`; Get Details shows its providers and care contexts
* [ ] Pin exists returns `false` for a new patient; set a PIN; exists now returns `true`
* [ ] Verify the PIN and approve one care context. Record whether `abha.consent_update` arrives (not yet confirmed); otherwise List Requests with `status` `granted` shows the request
* [ ] Get Details now shows a `consent_artefact_id`; revoke it
* [ ] Deny a second request with a reason
* [ ] Let the session expire and confirm the `491` path


# Discover and link records from a facility
Source: https://developer.eka.care/docs/hie-cm/workflows/phr-discover-and-link

Find a facility, ask it for the patient's unlinked care contexts, and link the ones the patient picks with an OTP.

## In short

* Find the facility, discover its unlinked care contexts, then link them with an OTP.
* The facility sends the link OTP to the patient's registered mobile.
* An empty `patient` list means the facility found nothing; retry with a `ref_id`.
* Each call takes the `txn_id` from the call before it.

## When to use this

The patient uses your PHR app to claim records that a facility holds against them but never linked to their ABHA. You search for the facility and ask it for unlinked care contexts. The patient picks the ones to link and enters an OTP the facility sends.

This is the PHR side of discovery. If your software is the facility answering these requests, use [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link) instead.

## Before you start

* A client access token, sent as a Bearer token. See [Authorization](/api-sdk/auth/getting-started).
* A logged-in patient and their Eka user id (`oid`). It comes from [Create an ABHA with Aadhaar OTP](/docs/hie-cm/workflows/create-abha-aadhaar-otp), [Create an ABHA address with mobile OTP](/docs/hie-cm/workflows/create-abha-mobile-otp) or [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha). Every call here takes it as the `X-Pt-Id` header or the `oid` query parameter.&#x20;
* A live ABHA gateway session for the patient. See [Hold an ABHA gateway session](/docs/hie-cm/workflows/hold-gateway-session).&#x20;
* The patient's mobile, to receive the facility's OTP.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant HIP as Facility (HIP)
  participant Patient as Patient's phone
  alt Patient searches by name
    App->>Eka: GET /abdm/v1/providers
  else You already hold the hip_id
    App->>Eka: GET /abdm/v1/provider/{hip_id}
  end
  App->>Eka: POST /abdm/v1/care-contexts/discover
  Eka->>HIP: Discovery request through the ABDM gateway
  HIP-->>Eka: Unlinked care contexts
  App->>Eka: POST /abdm/v1/care-contexts/discover/link/init
  Eka->>HIP: Link request through the ABDM gateway
  HIP-->>Patient: OTP via SMS
  App->>Eka: POST /abdm/v1/care-contexts/discover/link/confirm
  Eka->>HIP: OTP through the ABDM gateway
  HIP-->>Eka: Care context linked
```

## Steps

**1. Find the facility**

If the patient searches by name, call [Search Providers](/api-sdk/hie-cm/providers/search/providers) with `name`, at least three characters. The response is a list of facilities, each with `hip_id`, `hip_name`, `city` and `state`. Show the list and keep the `hip_id` the patient picks.

If you already hold a `hip_id`, for example from an earlier link, call [Get Provider Details](/api-sdk/hie-cm/providers/provider) with it instead. It returns the same four fields for that one facility.&#x20;

**2. Discover unlinked care contexts**

Send `hip_id` to [Discover unlinked care-contexts](/api-sdk/hie-cm/care-contexts/discover/discover). Add `ref_id` if the patient knows the identifier the facility holds for them, such as a registration number or the phone number they gave there. The facility matches the patient's verified ABHA identifiers against its records.

The response carries `txn_id` and a `patient` list. Each `patient` entry has an `id`, a `display` name and `care_contexts`, each with its own `id` and `display`. Keep `txn_id` and both ids. If `patient` is empty or null, the facility found nothing: let the patient retry with a `ref_id`, or pick another facility.&#x20;

**3. Start linking**

Send `txn_id` from Discover, `patient_ref_id` and `cc_ref_id` to [Initialise Linking](/api-sdk/hie-cm/care-contexts/discover/link-init). The facility sends an OTP to the patient's registered mobile. Keep the new `txn_id` from the response. &#x20;

**4. Confirm with the OTP**

Send `txn_id` from Link Init and the `otp` the patient enters to [Confirm Linking](/api-sdk/hie-cm/care-contexts/discover/link-confirm). The response carries `cc_ref_id`, the care context now linked to the patient's ABHA. It appears under the facility in [List a patient's linked records](/docs/hie-cm/workflows/phr-list-records).&#x20;

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `oid` | ABHA creation or login | On the patient record, for as long as the patient uses your app | `X-Pt-Id` or `oid` on every call |
| `hip_id` | Search Providers or Get Provider Details | On the patient record once a link succeeds | Discover again later; list records under that facility |
| `txn_id` (Discover) | Discover | Until Link Init returns | Link Init |
| `patient[].id`, `care_contexts[].id` | Discover | Until Link Confirm returns | `patient_ref_id` and `cc_ref_id` on Link Init |
| `txn_id` (Link Init) | Link Init | Until Link Confirm returns | Link Confirm |
| `cc_ref_id` | Link Confirm | On the patient record | Match the linked care context in later lists |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Errors come back as HTTP 4XX or 5XX with a `GenericError` body: `code`, `error` and `source_error`. The codes below are from the [errors page](/docs/hie-cm/errors).&#x20;

| Situation | Code | Do |
| - | - | - |
| Search name shorter than three characters | HTTP 4XX | Ask the patient for a longer name before calling |
| Malformed request or missing field | [`ABDM-1006`](/docs/hie-cm/errors), [`ABDM-1010`](/docs/hie-cm/errors) | Fix the request; do not retry unchanged |
| Patient's gateway session expired | HTTP `491` | Run [Hold an ABHA gateway session](/docs/hie-cm/workflows/hold-gateway-session), then repeat the step |
| Facility found no records | [`ABDM-1012`](/docs/hie-cm/errors), or an empty `patient` list | Retry with a `ref_id`, or try another facility |
| Wrong OTP | [`ABDM-1035`](/docs/hie-cm/errors) (OTP does not match) | Let the patient re-enter it |
| Too many OTP attempts | [`ABDM-1100`](/docs/hie-cm/errors) | Stop; the message says to try again in 30 minutes |
| Transaction expired or unknown | [`ABDM-1017`](/docs/hie-cm/errors), [`ABDM-1052`](/docs/hie-cm/errors) | Restart from Discover |
| Facility unreachable or did not acknowledge | [`ABDM-1028`](/docs/hie-cm/errors), [`ABDM-1401`](/docs/hie-cm/errors), [`ABDM-1402`](/docs/hie-cm/errors), [`ABDM-1048`](/docs/hie-cm/errors) | Tell the patient the facility is not responding |
| Rate limit | [`ABDM-1022`](/docs/hie-cm/errors) | Back off |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

Run against the Stage/Sandbox server, `https://api.dev.eka.care`.&#x20;

* [ ] Search Providers with a three-character name returns the sandbox facility
* [ ] Discover with its `hip_id` returns a `txn_id` and at least one care context
* [ ] Link Init with that care context returns a new `txn_id`
* [ ] Link Confirm with the OTP returns `cc_ref_id`
* [ ] The facility and care context appear in [List a patient's linked records](/docs/hie-cm/workflows/phr-list-records)
* [ ] Wrong OTP once, then the correct OTP
* [ ] Link Confirm with a stale `txn_id` fails, and a fresh Discover recovers


# List a patient's linked records
Source: https://developer.eka.care/docs/hie-cm/workflows/phr-list-records

List the facilities a patient has linked records with, then the care contexts under each one.

## In short

* Listing takes two calls: linked facilities first, then one facility's care contexts.
* Each care context's `status` shows where it is in the consent and data flow.
* This lists metadata only; reading a record needs consent and a data transfer.

## When to use this

Your PHR app shows the patient what is linked to their ABHA. An ABHA address can carry thousands of care contexts across many facilities. So listing takes two calls: the facilities first, then the care contexts under the one the patient opens.

This lists metadata only. Reading a record's contents needs the patient's consent and a data transfer. See [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent) and [Receive and decrypt records as a HIU](/docs/hie-cm/workflows/hiu-receive-data).

## Before you start

* A client access token, sent as a Bearer token. See [Authorization](/api-sdk/auth/getting-started).
* The patient's Eka user id (`oid`), sent as the `X-Pt-Id` header or the `oid` query parameter. It comes from ABHA creation or [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha).&#x20;
* A live ABHA gateway session, if these calls need one. See [Hold an ABHA gateway session](/docs/hie-cm/workflows/hold-gateway-session).&#x20;
* At least one linked care context, from [Discover and link records from a facility](/docs/hie-cm/workflows/phr-discover-and-link) or linked by a facility.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  App->>Eka: GET /abdm/v1/care-contexts/providers
  Eka-->>App: providers with hip_id and hip_name
  App->>Eka: GET /abdm/v1/care-contexts/linked
  Eka-->>App: care_contexts for one hip_id
```

## Steps

**1. List linked facilities**

Call [Get Linked Providers](/api-sdk/hie-cm/care-contexts/providers/providers). The response carries `providers`, each with `hip_id` and `hip_name`. Show the list. If `providers` is empty or null, the patient has nothing linked yet; offer [Discover and link records from a facility](/docs/hie-cm/workflows/phr-discover-and-link).

**2. List care contexts for one facility**

When the patient opens a facility, send its `hip_id` as the required `hip_id` query parameter to [Get Linked CareContexts](/api-sdk/hie-cm/care-contexts/records/records). The response carries `care_contexts`, each with `care_context_id`, `display`, `created_at` and `status`.

`status` is one of `ConsentRaised`, `ConsentGranted`, `ConsentError`, `DataRequested`, `DataReceived`, `DataProcessing`, `DataProcessed`, `InvalidDataReceived` or `NoDataAvailable`. Use it to show where each record is in the consent and data flow. &#x20;

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `oid` | ABHA creation or login | On the patient record, for as long as the patient uses your app | `X-Pt-Id` or `oid` on both calls |
| `hip_id` | Get Linked Providers | For the screen, or cached on the patient record | Get Linked CareContexts |
| `care_context_id` | Get Linked CareContexts | On the patient record | Matching consent requests and received data to the record |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Errors come back as HTTP 4XX or 5XX with a `GenericError` body: `code`, `error` and `source_error`. Codes are on the [errors page](/docs/hie-cm/errors).&#x20;

| Situation | Code | Do |
| - | - | - |
| `hip_id` missing from Get Linked CareContexts | HTTP 4XX | Send the `hip_id` from Get Linked Providers |
| Patient's gateway session expired | HTTP `491` | Run [Hold an ABHA gateway session](/docs/hie-cm/workflows/hold-gateway-session), then repeat the call |
| Nothing linked under the ABHA address | [`ABDM-1012`](/docs/hie-cm/errors), or an empty list | Offer discovery and linking |
| Server or gateway error | HTTP 5XX, for example [`ABDM-1019`](/docs/hie-cm/errors) | Show the last list you have and retry later |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

Run against the Stage/Sandbox server, `https://api.dev.eka.care`.&#x20;

* [ ] Link one care context with [Discover and link records from a facility](/docs/hie-cm/workflows/phr-discover-and-link)
* [ ] Get Linked Providers returns that facility's `hip_id`
* [ ] Get Linked CareContexts with that `hip_id` returns the care context with a `status`
* [ ] Get Linked CareContexts without `hip_id` fails with a 4XX
* [ ] A patient with nothing linked gets an empty list or `ABDM-1012`, and the app offers discovery. Record the code you receive; the expected code is not confirmed.


# Share a profile at a facility counter
Source: https://developer.eka.care/docs/hie-cm/workflows/phr-scan-and-share

The patient scans a facility's QR code, your PHR app shares their ABHA profile with that counter, and you poll for the token number.

## In short

* Share the patient's profile with the counter whose QR code they scanned.
* The share returns `202` and a `request_id`; poll with it for the token.
* On `success`, show `token_number` and `expiry`; on `failed`, offer to scan again.

## When to use this

The patient is at a facility's registration counter and scans its Health Facility QR code in your PHR app. You share their ABHA profile with that counter, so the facility's software registers them without a form. Then you show the token number the facility issues.

This is the PHR side. If your software runs the facility's counter and receives the scanned profile, use [Receive a scanned profile as a HIP](/docs/hie-cm/workflows/hip-scan-and-share) instead.

## Before you start

* A client access token, sent as a Bearer token. See [Authorization](/api-sdk/auth/getting-started).
* A logged-in patient and their Eka user id (`oid`), sent as the `X-Pt-Id` header or the `oid` query parameter. See [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha).&#x20;
* A live ABHA gateway session, if this call needs one. See [Hold an ABHA gateway session](/docs/hie-cm/workflows/hold-gateway-session).&#x20;
* A QR scanner in your app, and permission to read the device location.
* The patient's profile: ABHA address, name, gender, day, month and year of birth, and mobile. See [Manage the ABHA profile and KYC](/docs/hie-cm/workflows/manage-profile-and-kyc).

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant Patient as Patient's phone
  participant App as Your app
  participant Eka
  participant HIP as Facility (HIP)
  Patient->>App: Scans the facility QR code
  App->>Eka: POST /abdm/v2/profile/share
  Eka-->>App: 202 with request_id
  Eka->>HIP: Profile shared through the ABDM gateway
  HIP-->>Eka: Token number
  loop Until status is no longer processing
    App->>Eka: GET /abdm/v2/profile/share/{request_id}
  end
  Eka-->>App: token_number and expiry
```

## Steps

**1. Share the profile**

Read `hip_id` and `counter_id` from the scanned QR code. Send both, the device's `latitude` and `longitude` in `location`, and the patient's profile in `patient`, to [Request to generate token](/api-sdk/hie-cm/scan-and-share/phr-scan-share). In `patient`, `abha_address`, `name`, `gender`, `day_of_birth`, `month_of_birth`, `year_of_birth` and `mobile` are required.

The call is asynchronous. It returns HTTP `202` with `request_id` and `status`. Keep `request_id`. &#x20;

**2. Poll for the token**

Call [Get appointment token](/api-sdk/hie-cm/scan-and-share/phr-scan-share-token) with `request_id` in the path. The response carries `status`, `token_number` and `expiry`.

The spec gives `status` three values: `success`, `processing` and `failed`. While it is `processing`, the facility has not answered; call again. When it is `success`, show `token_number` and its `expiry` to the patient. When it is `failed`, tell the patient the share did not go through and offer to scan again.   &#x20;

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `oid` | ABHA creation or login | On the patient record, for as long as the patient uses your app | `X-Pt-Id` or `oid` on both calls |
| `hip_id`, `counter_id` | The scanned QR code | Until polling ends | Share request; show the patient which facility they checked in at |
| `request_id` | Share response | Until `status` is `success` or `failed` | Every poll |
| `token_number`, `expiry` | Poll response | Until `expiry` | Show the patient their token at the counter |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Errors come back as HTTP 4XX or 5XX with a `GenericError` body: `code`, `error` and `source_error`. Codes are on the [errors page](/docs/hie-cm/errors).&#x20;

| Situation | Code | Do |
| - | - | - |
| `hip_id` or `counter_id` missing, or a required `patient` field missing | HTTP 4XX, for example [`ABDM-1010`](/docs/hie-cm/errors) | Rescan the QR code; fill the profile fields |
| QR code from an unknown facility | [`ABDM-1035`](/docs/hie-cm/errors) (Invalid HIP ID) | Ask the patient to scan the counter's QR code again |
| Patient's gateway session expired | HTTP `491` | Run [Hold an ABHA gateway session](/docs/hie-cm/workflows/hold-gateway-session), then share again |
| Unknown `request_id` on the poll | [`ABDM-1030`](/docs/hie-cm/errors) | Use the `request_id` from the share response; if lost, share again |
| Poll returns `failed`, for example because the profile could not reach the facility | `status: failed` on the poll. Share returns `202` and the facility answers later, so a failure such as [`ABDM-1018`](/docs/hie-cm/errors) (Unable to share the details with Hospital) or [`ABDM-1028`](/docs/hie-cm/errors) is not returned to your app as an error | Retry later; register the patient at the desk meanwhile |
| Facility never answers | `status` stays `processing` | Stop polling at your limit and tell the patient |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

Run against the Stage/Sandbox server, `https://api.dev.eka.care`.&#x20;

* [ ] Share with the test `hip_id`, `counter_id`, a location and the patient's profile returns `202` and a `request_id`
* [ ] Polling with that `request_id` moves from `processing` to `success` with a `token_number` and `expiry`
* [ ] Share without `counter_id` fails with a 4XX
* [ ] Poll with an unknown `request_id` fails
* [ ] A facility that does not answer: polling stops at your limit and the app tells the patient


# Register and onboard a facility
Source: https://developer.eka.care/docs/hie-cm/workflows/register-hfr

Find the facility in the Health Facility Registry or register it, link it to the Eka Bridge, and onboard it to Eka as a HIP.

## In short

* Search HFR, register the facility if absent, link it to the Eka Bridge, then onboard it to Eka.
* The onboarding call returns the HIP ID your HMS uses on every later HIP call.
* It is a one-time setup per facility.

## When to use this

A facility needs to act as a Health Information Provider (HIP) through Eka. You take four steps:

* Search the Health Facility Registry (HFR) for it.
* Register it if it is not there.
* Link it to the Eka Bridge.
* Onboard it to Eka.

The last call returns the HIP ID your HMS uses on every later HIP call. This is a one-time setup per facility.

If the facility was registered on the [ABDM portal](https://nhpr.abdm.gov.in/nhpr/v4/login) and linked there under Software Linkage with the Eka Bridge ID, skip to the last step.

## Before you start

* A bearer token for the Eka API. See [Authorization](/api-sdk/auth/getting-started).
* The headers your integration sends on ABDM Connect calls. The three HFR operations accept `X-Pt-Id`, `X-Partner-Pt-Id` and `X-Hip-Id`.&#x20;
* At least one professional at the facility with an HPR ID, from [Create an HPR ID with Aadhaar OTP](/docs/hie-cm/workflows/create-hpr-id). Registering a facility needs the authorizing doctor's OID.
* The facility's HFR ID if it has one, and your own `clinic_id` for it.
* The facility's name, for the onboarding call.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  App->>Eka: GET /abdm/nhpr/v1/hfr/search/{hfrId}
  alt Facility not in HFR
    App->>Eka: POST /abdm/nhpr/v1/hfr/onboard
  end
  App->>Eka: POST /abdm/nhpr/v1/hfr/link
  App->>Eka: POST /abdm/v1/hip/onboard
```

## Steps

**1. Search for the facility**

Call [Search HFR](/api-sdk/hie-cm/nhpr-abdm/hfr/search-facility) with the HFR ID in the path as `hfrId`. If the facility exists, the response `data` carries `facilityId`, `facilityName`, `facilityStatus`, `facilityType`, `ownership` and the address fields. Check `facilityName` and the address with the admin before you go on. If it exists, skip to Link.&#x20;

**2. Register the facility if it is absent**

Call [Onboard HFR](/api-sdk/hie-cm/nhpr-abdm/hfr/onboard-facility). The spec gives this body only `clinic_id` and `hfr_id`. The response `data` carries `facility_id`. Keep it as the facility's HFR ID.&#x20;

**3. Link the facility to the Eka Bridge**

Send `hfr_id` and `clinic_id` to [Link HFR](/api-sdk/hie-cm/nhpr-abdm/hfr/link-facility). Use `facilityId` from Search, or `facility_id` from Onboard HFR, as `hfr_id`. The response `data` echoes `hfr_id` and `clinic_id`; check `success` is true. This connects the facility to the Eka Bridge so it can exchange health data.&#x20;

**4. Onboard the facility to Eka**

Send `hip_id` and `name`, both required, and your `clinic_id` to [Onboard facility](/api-sdk/hie-cm/nhpr-abdm/onboarding). The response carries `hip_id`, `hip_code`, `hip_name` and `scan_share_url`. Save them on the facility record.&#x20;

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| HFR ID (`facilityId` or `facility_id`) | Search HFR, or Onboard HFR | Permanently, on the facility record | Link HFR as `hfr_id`, and the HIP ID for onboarding |
| `clinic_id` | Your own system | Permanently, on the facility record | Link HFR and Onboard facility |
| `hip_id` | Onboard facility | Permanently, on the facility record | The `X-Hip-Id` header on later HIP calls |
| `hip_code` | Onboard facility | Permanently, on the facility record | |
| `scan_share_url` | Onboard facility | Permanently, on the facility record | The facility's Scan and Share link |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Errors come back as `4XX` or `5XX` with a body carrying `code`, `error` and `source_error` (`code`, `message`). Read `source_error.code` and look it up on the [errors page](/docs/hie-cm/errors).

| Situation | Code | Do |
| - | - | - |
| Malformed body, such as a missing `hip_id` or `name` on Onboard facility | `ABDM-1006` | Fix the request; do not retry unchanged |
| Facility not in HFR | | Register it with Onboard HFR |
| Facility already registered | `ABDM-1053` | Search for it and continue from Link |
| Invalid HIP ID on Onboard facility | `ABDM-1035` (the [errors page](/docs/hie-cm/errors) lists two meanings: Invalid HIP ID on a 500, and OTP does not match on a 400; tell them apart by HTTP status and `source_error.message`) | Check the `hip_id` you sent |
| Facility not yet approved | | Wait for approval, then retry from Link |
| ABDM registry unavailable | `ABDM-1019` or `ABDM-1024` | Retry later |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

Run against the sandbox base URL `https://api.dev.eka.care`.&#x20;

* [ ] Existing facility: Search HFR returns it, Link HFR returns `success` true, Onboard facility returns `hip_id` and `scan_share_url`
* [ ] New facility: Search HFR finds nothing, Onboard HFR returns `facility_id`, then Link and Onboard facility
* [ ] Onboard facility without `name`: the call fails and your app shows the error
* [ ] Run Onboard facility twice for the same facility&#x20;


# Serve records on a fetch request
Source: https://developer.eka.care/docs/hie-cm/workflows/serve-data-on-fetch

Answer Eka's request for records you keep yourself: encrypt the FHIR bundle and push it.

## In short

* Use this only if you link care contexts without sending their FHIR data to Eka.
* Eka sends `abha.hip_data_fetch`; acknowledge it within 5 seconds.
* Encrypt each bundle for the HIU, then push it with on-fetch.
* Send back the `transaction_id` from the webhook.

## When to use this

You linked care contexts without sending their FHIR data to Eka, so you hold the records yourself. When a Health Information User (HIU) requests those records after the patient grants consent, Eka sends you a webhook. You build the FHIR bundles, encrypt them for the HIU, and push them back.

Eka serves the data itself, and you never receive this webhook, in two cases:

* You send the base64 FHIR bundle in the `data` field when you [link a care context](/docs/hie-cm/workflows/link-care-context-hip).
* You upload records through the [Upload API](/api-sdk/health-records/obtain-authorization).

Then you do not need this workflow.

## Before you start

* A client access token, sent as a Bearer token. See [Authorization](/api-sdk/auth/getting-started).
* Your facility onboarded as a Health Information Provider (HIP), with its HIP ID.
* Care contexts linked without `data`, through [Link a care context as a HIP](/docs/hie-cm/workflows/link-care-context-hip) or [Answer discovery and link old records](/docs/hie-cm/workflows/hip-discovery-and-link).
* A webhook URL registered with Eka that can receive `abha.hip_data_fetch`, and the means to verify the [webhook signature](/docs/webhooks/webhook-signature).
* A way to produce an ABDM-compliant FHIR bundle for each care context you linked.
* A choice of how to encrypt: the open-source `abdm-ecdh` library in your own code, described in [Encryption](/docs/hie-cm/care-contexts/ecdh-encryption), or Eka's ECDH endpoints. The library keeps your private key on your server. The [Ecdh encrypt](/api-sdk/hie-cm/care-contexts/ecdh/encrypt) endpoint takes your private key in the request body.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant HIU
  participant Eka
  participant App as Your app
  HIU->>Eka: Data request under a granted consent
  Eka-->>App: webhook abha.hip_data_fetch
  App->>Eka: GET /abdm/v1/ecdh/keys
  App->>Eka: POST /abdm/v1/ecdh/encrypt
  App->>Eka: POST /abdm/v1/hip/care-context/data/on-fetch
  Eka->>HIU: Encrypted data
```

If you use the `abdm-ecdh` library, the two `/abdm/v1/ecdh/` calls run in your own code instead. [Encryption](/docs/hie-cm/care-contexts/ecdh-encryption) shows the library's calls and their outputs.

## Steps

**1. Receive the fetch request**

Eka sends the [`abha.hip_data_fetch`](/docs/hie-cm/webhooks/hip-data-fetch) webhook. Acknowledge it with HTTP `200` within 5 seconds; Eka retries on any other status. Do the rest of the work after you acknowledge.

From `data`, keep:

* `care_contexts`: the ids of the care contexts to send, the same ids you linked.
* `hi_types`: the health information types the HIU asked for.
* `key_information`: the HIU's key material. You need `dh_public_key.key_value`, `dh_public_key.expiry` and `nonce`.
* `transaction_id`: you send it back in the push.
* `abha_address`, `oid`, `partner_patient_id` and `hip_id`: to find the patient and for the push headers.

**2. Generate your key material**

Call [Ecdh keys](/api-sdk/hie-cm/care-contexts/ecdh/keys). The response carries `private_key`, `public_key` and `nonce` for your side of the exchange.

**3. Encrypt each care context's bundle**

Build the FHIR bundle for each id in `care_contexts`. Call [Ecdh encrypt](/api-sdk/hie-cm/care-contexts/ecdh/encrypt) once per bundle with:

* `plain_text_data`: the FHIR bundle as a string.
* `sender_private_key`, `sender_public_key`, `sender_nonce`: your key material from the previous step.
* `receiver_public_key`: `key_information.dh_public_key.key_value` from the webhook.
* `receiver_nonce`: `key_information.nonce` from the webhook.

The response carries `encrypted_data` and `key_to_share`.

Compute a checksum of the plain-text bundle before you encrypt it; the push needs it.

**4. Push the encrypted data**

Call [Push care context data to HIU](/api-sdk/hie-cm/care-contexts/data-on-fetch). Send the patient's `oid` in `X-Pt-Id`, your patient id in `X-Partner-Pt-Id` and your HIP ID in `X-Hip-Id`. In the body send:

* `transaction_id` from the webhook.
* `entries`: one per care context, each with `care_context_id`, `content` set to `encrypted_data`, `media` set to `application/fhir+json`, and `checksum`.
* `key_information`: your side of the exchange, with `crypto_alg` `ECDH`, `curve` `Curve25519`, `dh_public_key` (`key_value`, `expiry`, `parameters`) and `nonce` set to your `nonce`.
* `page_number` and `page_count`.

The call returns `202 Accepted`.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `care_context_id` and its FHIR source | Your link call | As long as the care context is linked | Building the bundle when a fetch arrives |
| `transaction_id` | `abha.hip_data_fetch` | Until the last page is accepted | Every on-fetch call for this request |
| `key_information` | `abha.hip_data_fetch` | Until the last page is accepted | Encrypting each bundle |
| `private_key`, `public_key`, `nonce` | Your key material | Until the last page is accepted | Encrypting and the push's `key_information` |
| Plain-text checksum per bundle | You | Until the push is accepted | The `checksum` field |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Error responses carry `code`, `error` and `source_error`.

| Situation | Code | Do |
| - | - | - |
| Push body malformed or a field invalid | `ABDM-1006`, `ABDM-1010` | Fix the request against the reference page and resend |
| Transaction id unknown | `ABDM-1017`, `ABDM-1052` | Check you sent the `transaction_id` from the webhook |
| Consent expired or not granted | `ABDM-1061`, `ABDM-1062` | Stop; do not send data for this request |
| HIU unavailable | `ABDM-1033` | Retry later |
| Gateway timeout or dependent service down | `ABDM-1048`, `ABDM-1019` | Retry later |
| Your webhook did not answer within 5 seconds | No code; Eka retries the webhook | Acknowledge first, then build and push |
| Encryption fails or the HIU cannot decrypt | Not documented | Check the receiver key and nonce came from this webhook's `key_information` |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

* [ ] Link a care context without `data`, then raise a consent request for it from a sandbox HIU and receive `abha.hip_data_fetch`
* [ ] Encrypt one bundle with `GET /abdm/v1/ecdh/keys` and `POST /abdm/v1/ecdh/encrypt`, push it, and get `202 Accepted`
* [ ] Repeat with the `abdm-ecdh` library and compare the result
* [ ] Round-trip the library on its own first: generate two key sets, `encrypt` with one, `decrypt` with the other, as in [Encryption](/docs/hie-cm/care-contexts/ecdh-encryption)
* [ ] Return a non-`200` from your webhook once and confirm Eka retries


# Set up the patient's health locker
Source: https://developer.eka.care/docs/hie-cm/workflows/set-up-health-locker

Turn on auto-approval so the patient's PHR app is notified of each new record, and handle the locker and subscription webhooks.

## In short

* Turn on auto-approval once, and your app becomes the patient's health locker.
* Store `auto_approval_id` and `subscription_id` from `abha.locker_created`.
* `abha.subscription_notify` tells you each time a HIP links a new care context.
* The notification carries no records; fetch them with a consent request.

## When to use this

Your app is a personal health record (PHR) app, and the patient wants new records from their facilities to arrive without approving each one. An auto-approval policy lets the patient authorise a class of requests once. With it in place, your app is the patient's health locker. Eka sets up an auto-approval and a subscription. It tells you each time a Health Information Provider (HIP) links a new care context to the patient's ABHA address.

For one request at a time, the patient approves or denies by hand: [Approve, deny or revoke a consent in a PHR app](/docs/hie-cm/workflows/phr-act-on-consent).

## Before you start

* A bearer token for the API. See [Authorization](/api-sdk/auth/getting-started).
* A live ABHA Gateway session for the patient. Every consent operation needs one. See [User Session](/docs/hie-cm/session/getting-started).
* The patient's Eka user id (`oid`).
* A webhook endpoint registered with Eka that verifies the `Eka-Webhook-Signature` header. See [Webhook signature](/docs/webhooks/webhook-signature).
* Your keyset registered, if you manage the data on your side, so records fetched for the locker can be encrypted for you. See [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent).

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your PHR app
  participant Eka
  participant HIP
  App->>Eka: GET /abdm/v1/consents/auto-approval
  App->>Eka: PATCH /abdm/v1/consents/auto-approval
  Eka-->>App: webhook abha.locker_created
  HIP->>Eka: new care context linked
  Eka-->>App: webhook abha.subscription_notify
  Eka-->>App: webhook abha.subscription_modified
```

## Steps

**1. Check the current policy**

Call [Get Status](/api-sdk/hie-cm/consents/auto-approval/get-status) with the patient's `oid`. The response carries `status`, either `enabled` or `disabled`. If it is `enabled`, the locker is already set up; skip to handling the webhooks.

**2. Turn on auto-approval**

Call [Update Auto Approval Policy](/api-sdk/hie-cm/consents/auto-approval/update-auto-approval-policy). The body is `application/x-www-form-urlencoded` and carries the patient's `oid`. The response carries the new `status`.

**3. Store the locker ids**

Wait for [`abha.locker_created`](/docs/hie-cm/webhooks/locker-created). Reply `200` within 5 seconds; Eka retries on any other status. Store `data.auto_approval_id` and `data.subscription_id` against the patient (`data.oid`, `data.abha_address`). Together they identify the standing arrangement.

**4. Handle new care contexts**

Each time a HIP links a new care context to the patient's ABHA address, Eka sends [`abha.subscription_notify`](/docs/hie-cm/webhooks/subscription-notify). Reply `200` within 5 seconds. Read `data.subscription_meta`: `hip_id` (the HIP that created the record), `event_id`, and `care_contexts`, each with `care_context_id` and `patient_reference`.

The notification carries no records. To fetch them:

1. Raise a consent request for those care contexts with [Request a patient's consent as a HIU](/docs/hie-cm/workflows/hiu-request-consent).
2. Receive them with [Receive and decrypt records as a HIU](/docs/hie-cm/workflows/hiu-receive-data).

**5. Handle subscription changes**

When the subscription changes, Eka sends [`abha.subscription_modified`](/docs/hie-cm/webhooks/subscription-modify). Reply `200` within 5 seconds. Read `data.subscription_details`: `subscription_id`, `period` (`from`, `to`), `categories` (such as `DATA` and `LINK`) and `status` (such as `GRANTED`). Update your stored subscription to match.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `auto_approval_id` | `abha.locker_created` | As long as the locker is active | Identifying the auto-approval behind the locker |
| `subscription_id` | `abha.locker_created` | As long as the subscription is active | Matching `abha.subscription_modified` to the patient |
| Subscription `status`, `period`, `categories` | `abha.subscription_modified` | Until the next update | Whether new care contexts will be notified |
| `care_context_id`, `hip_id` | `abha.subscription_notify` | Until you have fetched the records | Raising the consent request for the new records |
| `event_id` | `abha.subscription_notify` | | Deduplicating retried deliveries |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Error responses carry `code`, `error` and `source_error` (`code`, `message`). Codes are listed on the [errors page](/docs/hie-cm/errors).

| Situation | Code | Do |
| - | - | - |
| ABHA Gateway session expired | HTTP `491` | Re-run the session OTP, then retry. See [User Session](/docs/hie-cm/session/getting-started) |
| `oid` missing or not recognised | `ABDM-1023`, `ABDM-1110` | Check you sent the patient's Eka user id |
| Subscription request id not recognised | `ABDM-1054` | Not documented yet |
| Your endpoint does not reply `200` within 5 seconds | none | Eka retries; reply first, process after |
| Gateway unavailable | `ABDM-1024`, `ABDM-1048` | Retry later |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

Sandbox base URL: `https://api.dev.eka.care`.&#x20;

* [ ] Get Status returns `disabled` for a new sandbox patient
* [ ] Update Auto Approval Policy returns `enabled`; `abha.locker_created` arrives with `auto_approval_id` and `subscription_id`
* [ ] Get Status now returns `enabled`
* [ ] Link a new care context at a sandbox HIP; `abha.subscription_notify` arrives with its `care_context_id`
* [ ] Raise a consent for that care context and confirm whether it is approved without a prompt
* [ ] Let the session expire and confirm the `491` path


# Build with AI
Source: https://developer.eka.care/docs/models/build-with-ai

Set up a coding agent to build with Document Parsing: the reference skill.

Use the reference skill to have a coding assistant build your Document Parsing integration. It hands the assistant the same facts as these docs.

> [!NOTE]
>
> Check what the assistant writes against these docs, and test it in the sandbox before it reaches a patient.

> **[Reference skill](#install-the-skill)**
>
> Every operation, its hosts, auth and headers, in one install.

## Before you start

Three things have to be in place before anything on this page works.

| What you need | Why |
| - | - |
| A coding assistant | Claude Code, Cursor, Codex or ChatGPT. Any one is enough. Pick one and stay on it. |
| A paid plan on it | Free tiers stop partway through a long task. |
| Your own project open in it | The assistant reads and writes the folder it is opened in. Open the repository you are building in first. |

Then work down this page in order: install the skill, connect the MCP server where there is one, and ask for one flow at a time in plain language. Read what the assistant writes before you run it.

## Install the skill

The `eka-document-parsing` skill carries the hosts, auth and headers, and every Document Parsing operation, each with a link to its page here. It is built from these docs, so it changes when they do.

In Claude Code:

```bash theme={null}
/plugin marketplace add eka-care/eka-docs
/plugin install eka-document-parsing@eka-docs
```

In Cursor, Codex or another agent, copy the [skill folder](https://github.com/eka-care/eka-docs/tree/main/plugins/eka-document-parsing/skills/eka-document-parsing) into the folder your agent loads skills from. Its map is [`SKILL.md`](https://raw.githubusercontent.com/eka-care/eka-docs/main/plugins/eka-document-parsing/skills/eka-document-parsing/SKILL.md).

## Read these docs as an agent

Every page here is also plain text an agent can read.

* [`llms.txt`](https://developer.eka.care/llms.txt) is a map of every page.
* [`llms-full.txt`](https://developer.eka.care/llms-full.txt) is every page's text in one file.
* The menu at the top of each page copies it as Markdown, or opens it in Claude or ChatGPT.


# Datasets
Source: https://developer.eka.care/docs/models/datasets



# Empowering Indian Healthcare AI with High-Quality Data

At Eka Care, we believe that advancing healthcare in India requires AI solutions built specifically for Indian populations. To support this vision, we share anonymized, expert-annotated healthcare datasets with the research community. All datasets are in the [EkaCare Medical Public Datasets](https://huggingface.co/collections/ekacare/ekacare-medical-public-datasets) collection on Hugging Face and on the [India AI AIKosh platform](https://aikosh.indiaai.gov.in).

| Dataset | Category | Size | Links |
| - | - | - | - |
| Eka Medical ASR Evaluation | Speech | 3,900+ recordings | [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/eka_medical_asr_evaluation_dataset.html) · [HF](https://huggingface.co/datasets/ekacare/eka-medical-asr-evaluation-dataset) |
| Clinical Note Generation | Clinical documentation | 156+ conversations | [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/eka_clinical_note_generation_dataset.html) · [HF](https://huggingface.co/datasets/ekacare/clinical_note_generation_dataset) |
| Medical History Summarisation | Clinical documentation | 58 cases | [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/ekacare_medical_history_summarisation.html) · [HF](https://huggingface.co/datasets/ekacare/ekacare_medical_history_summarisation) |
| Medical Records Parsing Validation | Documents | 288 documents | [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/eka_medical_records_parsing_validation_set.html) · [HF](https://huggingface.co/datasets/ekacare/medical_records_parsing_validation_set) |
| Eka-IndicMTEB | Embeddings | 2,532 queries, 8 languages | [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/ekaindicmteb.html) · [HF](https://huggingface.co/datasets/ekacare/Eka-IndicMTEB) |
| Indian Drug MCQA | Medical knowledge | 1,512 questions | [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/indian_drug_mcqa.html) · [HF](https://huggingface.co/datasets/ekacare/indian_drug_mcqa) |
| Eka NFI MCQA | Medical knowledge | 925 questions | [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/eka_nfi_mcqa.html) · [HF](https://huggingface.co/datasets/ekacare/Eka_NFI_MCQA) |
| Medical Calculator Eval | Clinical reasoning | 1,066 questions, 358 calculators | [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/medical_calculator_eval.html) · [HF](https://huggingface.co/datasets/ekacare/medical_calculator_eval) |
| Indian Protocols Clinical Q\&A | Clinical reasoning | Rubric-graded | [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/indian_protocols_based_clinical_qna.html) · [HF](https://huggingface.co/datasets/ekacare/indian_protocols_based_clinical_QnA) |
| BODHI-S | Knowledge graph | 779 conditions, 4,037 symptoms | [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/bodhi_s.html) · [HF](https://huggingface.co/datasets/ekacare/BODHI-S) |
| BODHI-M | Knowledge graph | 2,471 concepts, 1,186 drugs, 812 labs | [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/bodhi_m.html) · [HF](https://huggingface.co/datasets/ekacare/BODHI-M) |
| NidaanKosh | Population health | 100K subjects, 6.8M+ readings | [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/nidaankosha_100k_v1.html) · [HF](https://huggingface.co/datasets/ekacare/NidaanKosha-100k-V1.0) |
| Spandan | Population health | 1M+ PPG signals | [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/spandan_1m_v1_raw.html) · [HF](https://huggingface.co/datasets/ekacare/spandan-1M-V1.0-raw) |

***

## Speech

### Eka Medical ASR Evaluation Dataset

* A curated collection of 3,900+ English and Hindi medical speech recordings designed to benchmark and improve speech-to-text performance for Indian healthcare use cases.
* Built with diverse accents and real clinical terminology, with per-term medical entity annotations and a published leaderboard on the dataset card. Used by Google Health, ElevenLabs and academic groups for fine-tuning and benchmarking.
* [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/eka_medical_asr_evaluation_dataset.html) | [Hugging Face](https://huggingface.co/datasets/ekacare/eka-medical-asr-evaluation-dataset)

***

## Clinical Documentation

### Clinical Note Generation Dataset

* A multilingual dataset of 156+ transcribed doctor–patient conversations (English, Hindi, Marathi) designed to evaluate AI systems that convert medical dialogues into structured, entity-level clinical records.
* Expert-annotated ground truth JSON and rubric-based LLM evaluation ensure accurate benchmarking of structured note generation for EHR-ready medical documentation.
* [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/eka_clinical_note_generation_dataset.html) | [Hugging Face](https://huggingface.co/datasets/ekacare/clinical_note_generation_dataset)

***

### EkaCare Medical History Summarisation

* A curated set of 58 real-world medical cases designed to evaluate AI systems in generating concise, clinically relevant summaries of patient histories.
* Expert-defined rubrics and reference summaries ensure objective assessment of key developments, historical context, and critical care insights from the most recent six months of medical data.
* [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/ekacare_medical_history_summarisation.html) | [Hugging Face](https://huggingface.co/datasets/ekacare/ekacare_medical_history_summarisation)

***

## Medical Documents

### Medical Records Parsing Validation Set

* A curated dataset of 288 de-identified lab reports and prescriptions designed to evaluate AI systems that extract structured data from unstructured medical documents.
* Expert-annotated with rubric-based LLM evaluation, it ensures clinically accurate benchmarking across diverse Indian healthcare document formats.
* [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/eka_medical_records_parsing_validation_set.html) | [Hugging Face](https://huggingface.co/datasets/ekacare/medical_records_parsing_validation_set)

***

## Embeddings & Retrieval

### Eka-IndicMTEB

* A multilingual medical embedding benchmark with 2,532 doctor-verified queries across 8 Indic languages, aligned to SNOMED CT for concept-level evaluation.
* Designed to benchmark and improve cross-lingual medical retrieval and semantic search systems across India's diverse linguistic landscape.
* [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/ekaindicmteb.html) | [Hugging Face](https://huggingface.co/datasets/ekacare/Eka-IndicMTEB) | [Launch blog](https://info.eka.care/services/introducing-parrotlet-e-and-eka-indicmteb-bridging-indias-multilingual-healthcare-gap)

***

## Medical Knowledge (MCQ)

### Indian Drug MCQA

* 1,512 multiple-choice questions on Indian branded medications across 20+ therapeutic classes, testing whether a model can identify the generic composition from a brand name.
* Includes hard-difficulty variants with alternative distractor strategies and phrasings.
* [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/indian_drug_mcqa.html) | [Hugging Face](https://huggingface.co/datasets/ekacare/indian_drug_mcqa)

***

### Eka NFI MCQA

* 925 multiple-choice questions derived from the National Formulary of India (NFI) 2011, covering indications, contraindications, dosing, precautions, pregnancy safety and drug schedules.
* Evaluates drug pharmacology knowledge as defined by the Indian government reference rather than Western formularies.
* [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/eka_nfi_mcqa.html) | [Hugging Face](https://huggingface.co/datasets/ekacare/Eka_NFI_MCQA)

***

## Clinical Reasoning

### Medical Calculator Evaluation Dataset

* 1,066 questions across 358 medical calculators (BMI, GFR, APACHE II, drug dosing and more) in 24 domains, testing whether LLMs can compute numeric medical values from parametric memory and inline arithmetic alone.
* Structured JSON Q\&A with numeric comparison and per-row tolerance for evaluation.
* [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/medical_calculator_eval.html) | [Hugging Face](https://huggingface.co/datasets/ekacare/medical_calculator_eval)

***

### Indian Protocols-Based Clinical Q\&A

* A rubric-graded evaluation set built from Indian and international clinical guideline documents. Each sample is a realistic doctor-side query against a known protocol.
* Rubrics grade both whether the system retrieved the correct guideline content and whether the final answer is clinically complete and safe, stress-testing protocol-grounded question answering.
* [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/indian_protocols_based_clinical_qna.html) | [Hugging Face](https://huggingface.co/datasets/ekacare/indian_protocols_based_clinical_QnA)

***

## Clinical Knowledge Graphs (BODHI)

[BODHI](https://github.com/eka-care/BODHI) (Bharat Ontology for Disease & Healthcare Informatics) is a set of open, clinician-validated knowledge graphs for grounding healthcare AI in verified medical facts. Available in Neo4j, CSV, PyTorch Geometric and RDF formats. Read the [launch blog](https://info.eka.care/services/bodhi-bharat-ontology-for-disease-healthcare-informatics).

### BODHI-S — Condition–Symptom Graph

* Maps 779 clinical conditions to 4,037 symptom variants, 39 specialities and inter-condition risk relationships (13,204 relationships in total), with triage levels and demographic likelihood scores on every node.
* Built and validated by expert clinicians and has powered production symptom checking and differential diagnosis across millions of patient interactions in India.
* [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/bodhi_s.html) | [Hugging Face](https://huggingface.co/datasets/ekacare/BODHI-S) | [GitHub](https://github.com/eka-care/BODHI)

***

### BODHI-M — Concept–Drug–Lab Graph

* Maps 2,471 SNOMED-coded clinical concepts to 1,186 generic drugs and 812 LOINC-coded lab investigations, organised in a three-level System → Group → Granular hierarchy.
* Supports soft inference at broader levels when a drug or lab result cannot pinpoint a specific disease, and reverse inference of likely conditions from a medication list.
* [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/bodhi_m.html) | [Hugging Face](https://huggingface.co/datasets/ekacare/BODHI-M) | [GitHub](https://github.com/eka-care/BODHI)

***

## Population Health

### NidaanKosh

* A comprehensive laboratory investigation dataset of 100,000 Indian subjects with 6.8 million+ readings.
* Covers common biomarkers and laboratory values specific to Indian populations, enabling population-level reference ranges and screening research.
* [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/nidaankosha_100k_v1.html) | [Hugging Face](https://huggingface.co/datasets/ekacare/NidaanKosha-100k-V1.0)

***

### Spandan

* A large photoplethysmography (PPG) signal dataset of 1 million+ Indian subjects, with raw signals captured from diverse demographic groups across India.
* Essential for developing accurate cardiovascular monitoring algorithms for Indian populations.
* [AIKosh](https://aikosh.indiaai.gov.in/home/datasets/details/spandan_1m_v1_raw.html) | [Hugging Face](https://huggingface.co/datasets/ekacare/spandan-1M-V1.0-raw)

***

## Why These Datasets Matter

### Bridging the Data Gap

Majority healthcare AI models developed today are trained on Western datasets, which may not accurately represent Indian patients' unique characteristics. These datasets address this critical gap.

### Enabling Homegrown Innovation

With access to high-quality Indian healthcare data, researchers and developers can build AI solutions tailored specifically to Indian healthcare challenges.

### Advancing Healthcare Equity

By democratizing access to these datasets, we aim to support broader participation in healthcare AI development across India.

***

## How to Use These Datasets

1. **Access**: All datasets are on [Hugging Face](https://huggingface.co/collections/ekacare/ekacare-medical-public-datasets) and the [India AI AIKosh platform](https://aikosh.indiaai.gov.in). A few require accepting the terms on Hugging Face before download.
2. **Evaluate**: Use [KARMA – OpenMedEvalKit](https://github.com/eka-care/karMA-OpenMedEvalKit), our open-source medical AI evaluation framework, to benchmark models on these datasets.
3. **Documentation**: Each dataset card describes the data structure, collection methodology, and suggested applications.

***

## Ethics & Privacy

All datasets have been rigorously anonymized following industry best practices and ethical guidelines. No personally identifiable information is included in any dataset.

***

## Research Collaboration

We welcome collaboration opportunities with academic institutions, research organizations, and industry partners. If you're using our datasets for your research:

* Please cite our datasets in your publications
* Share your findings with us — see who is already [building on Eka open assets](/docs/models/spotlight)
* Consider opportunities for joint research initiatives

[Contact our research team](mailto:sankalp@eka.care)

***

*These datasets are provided for research and development purposes. For terms of use and licensing information, please refer to the license on each dataset card.*


# Medical Document Parsing
Source: https://developer.eka.care/docs/models/medical-document-parsing

Extract structured clinical data from lab report documents

## Medical Document Parsing

The **Medical Document Parsing API** allows you to upload lab report documents (PDF or image formats) and extract **structured clinical data** from unstructured files. It converts scanned or digital lab reports into machine-readable formats suitable for downstream clinical and analytical workflows.

Read more : ([API Reference - Medical Document Parsing](/docs/models/technologies/document-parsing)) section.

***

## What It Extracts

Parsed results include:

* Lab test names
* Measured values
* Units of measurement
* Normal reference ranges
* Associated clinical metadata

The output is available in:

* **FHIR format**
* **Enhanced JSON format**

***

## Use Cases

* Digitizing scanned lab reports
* Enriching patient health records
* Enabling search and analytics on lab data
* Powering clinical workflows and decision support systems

***

## How It Works

1. **Upload Report**\
   Upload a scanned lab report (PDF or image).\
   You receive a `document_id` for the uploaded file.

2. **Retrieve Parsed Report**\
   Use the `document_id` to fetch structured results in:
   * FHIR format, or
   * Enhanced JSON format

3. **Delete Report**\
   Remove the uploaded document using its `document_id`.

***

## Key Characteristics

* Supports both PDF and image-based lab reports
* Produces structured, machine-readable clinical data
* Designed for integration into clinical systems and AI workflows
* Informational extraction only; no clinical interpretation

***

## Scope & Limitations

* Focused on laboratory report parsing
* Accuracy depends on document quality and scan clarity
* Parsed data should be clinically verified before use

Read more : ([API Reference - Medical Document Parsing](/docs/models/technologies/document-parsing)) section.


# Classification webhook
Source: https://developer.eka.care/docs/models/medical-document-parsing/classification-webhook



Webhook event is sent when classification of document processing completes.

### Request

**Headers:**

* `Eka-Webhook-Signature`: `<Eka Webhook Signature>`  [Refer: Webhook Signature](/docs/webhooks/webhook-signature)
* `Content-Type`: `application/json`

**Body:**

```json theme={null}
{
        "event": "rec.classification",
        "service": "rec",
        "event_time": 1759234802,
        "transaction_id": "4d39628e-7916-47d7-bc35-a00cb986942b",
        "data": {
             "status": "parsing_complete",
             "document_id": "ed66604d-9d62-4f71-a5fb-b78a490148a0",
             "document_classification": "lab_report"
        }
}
```

### Field Descriptions

* **`data`**: Contains additional details related to the event.
  * **`status`**: Current parsing state (parsing\_initiated, parsing\_complete, parsing\_error).
  * **`document_id`**: ID of the document that was parsed.
  * **`document_classification`**: Document classification category (enum)
    * Possible values:
      * `lab_report` - Laboratory test report
      * `prescription` - Medical prescription
      * `medical_insurance` - Medical insurance document
      * `scan_interpretation` - Radiology/scan interpretation report
      * `scan` - Medical scan/imaging
      * `discharge_summary` - Hospital discharge summary
      * `cowin_vaccine_certificate` - COVID-19 vaccination certificate
      * `other_medical_document` - Other medical-related document
      * `medical_invoice` - Medical bill/invoice
      * `id_card` - Identification card
      * `body_part` - Body part image
      * `other_insurance` - Other insurance document
      * `other_invoice` - Non-medical invoice
      * `other_graphical` - Other graphical content
      * `non_medical_document` - Non-medical document
        Note: The status field is an enum with following possible values:
* parsing\_complete
* parsing\_error
* parsing\_initiated


# Pii webhook
Source: https://developer.eka.care/docs/models/medical-document-parsing/pii-webhook



Webhook event is sent when processing of PII completes

### Request

**Headers:**

* `Eka-Webhook-Signature`: `<Eka Webhook Signature>`  [Refer: Webhook Signature](/docs/webhooks/webhook-signature)
* `Content-Type`: `application/json`

**Body:**

```json theme={null}
{
  "event": "rec.pii",
  "service": "rec",
  "event_time": 1759234802,
  "transaction_id": "4d39628e-7916-47d7-bc35-a00cb986942b",
  "data": {
    "status": "parsing_complete",
    "document_id": "ed66604d-9d62-4f71-a5fb-b78a490148a0",
    "data": {
      "pii": [
        {
          "file_index": 0,
          "page_num": 1,
          "document_date": 1562697000,
          "patient": {
            "age": {
              "years": 25,
              "months": 0,
              "days": 0
            },
            "gender": "male",
            "name": "THREE DUMMY"
          },
          "report_info": {
            "date_sample_collection": "10/07/2019 15:07:00",
            "date_sample_received": "10/07/2019 15:08:19",
            "date_report_generated": "10/07/2019 15:44:01",
            "doctor": "Dr. UNKNWON",
            "facility": "Dr Lal PathLabs"
          }
        }
      ]
    }
  }
}

```

### Field Descriptions

* **`data`**: Contains additional details related to the event.
  * **`status`**: Current parsing state (parsing\_complete, parsing\_error).
  * **`document_id`**: ID of the document that was parsed.
  * **`data`**: Additional Data.
    * **`pii`**: PII Data.
      * **`file_index`**: Zero-based index of the source file within the document.
      * **`page_num`**: One-based page number within that file.
      * **`document_date`**: Document timestamp (Unix epoch seconds).
      * **`patient`** : Patient metadata extracted from the page.
        * `age` Age at document\_date.
          * `years` Years.
          * `months` Months.
          * `days` Days.
        * `gender` gender (male, female, other)
        * `name` Patient display name as printed on the report.
      * **`report_info`** : Laboratory/report details.
        * `date_sample_collection` Sample collection datetime.
        * `date_sample_received` Sample received datetime.
        * `date_report_generated` Report generated datetime.
        * `doctor` Ordering/referring physician.
        * `facility` Lab or organization name.

Note: The status field is an enum with following possible values:

* parsing\_complete
* parsing\_error


# Smart report webhook
Source: https://developer.eka.care/docs/models/medical-document-parsing/smart-report-webhook



Webhook event is sent when Smart Report processing completes.

### Request

**Headers:**

* `Eka-Webhook-Signature`: `<Eka Webhook Signature>`  [Refer: Webhook Signature](/docs/webhooks/webhook-signature)
* `Content-Type`: `application/json`

**Body:**

```json theme={null}
{
        "event": "rec.srp",
        "service": "rec",
        "event_time": 1759234802,
        "transaction_id": "4d39628e-7916-47d7-bc35-a00cb986942b",
        "data": {
             "status": "parsing_complete",
             "document_id": "ed66604d-9d62-4f71-a5fb-b78a490148a0",
             "identifier": "ekacare-sr-82b9b563-6c83-48e6-a89e-c2621db5599a",
        }
}
```

### Field Descriptions

* **`data`**: Contains additional details related to the event.
  * **`status`**: Current parsing state (parsing\_initiated, parsing\_complete, parsing\_error).
  * **`document_id`**: ID of the document that was parsed.
  * **`identifier`**: Care-Context ID of document.
  * **`data`**: Additional Data.
    * **`fhir`**: Fhir Data in Base64 encoded Format.

Note: The status field is an enum with following possible values:

* parsing\_complete
* parsing\_error
* parsing\_initiated


# Medical Entity Codification
Source: https://developer.eka.care/docs/models/medical-entity-codification

Map free-text medical entities to standardised ontology codes for structured, interoperable health data

## Medical Entity Codification

The **Medical Entity Codification API** converts free-text medical entities —
symptoms, diagnoses, lab tests and drugs — into standardised clinical codes.
It turns unstructured clinical text into structured, interoperable data that
downstream systems, analytics and decision-support tools can rely on.

It links text to four ontologies:

* **SNOMED CT** — symptoms, findings, disorders and procedures
* **LOINC** — lab tests and observations
* **ICD-10-CM** — diagnoses, from natural-language clinical text
* **Medication** — branded and generic drugs from Eka's medication database

Read more: ([API Reference - Medical Entity Codification](/docs/models/medical-entity-codification/overview)) section.

***

## Use Cases

### Structured EMR Data

Code symptoms, diagnoses and prescriptions captured during a consultation so
records stay consistent and machine-readable across systems.

### Lab Report Standardisation

Link extracted lab test names to LOINC codes — with unit and specimen context —
for accurate longitudinal tracking of diagnostic results.

### Interoperability and FHIR

Generate ontology-coded entities required for FHIR resources and health
information exchange.

### Analytics and Population Health

Normalise clinical entities across cohorts to support reliable aggregation,
risk stratification and reporting.

### Claims and Coding Workflows

Map free-text diagnoses to ICD-10-CM codes to support medical coding and
insurance claim processing.

***

## How It Works

1. **Discover** available ontologies and versions via the registry endpoint.
2. **Send** a free-text entity with the target `ontology` and `version`.
3. **Receive** ranked candidate codes, each with a confidence signal and
   ontology-specific metadata.

For LOINC and medication, an optional `metadata` field carries hints (such as a
test's unit or a drug's form) that materially improve linking accuracy.

***

## Key Characteristics

* Four clinical ontologies from a single API
* Single and batch (up to 5 entities) linking
* Ontology-aware result metadata and confidence signals
* Designed for interoperability, analytics and decision support

***

## Scope & Limitations

* Provides candidate codes; clinical validation remains with the integrator
* Not a substitute for professional medical coding judgment
* Linking accuracy for LOINC and medication depends on the context supplied

Read more: ([API Reference - Medical Entity Codification](/docs/models/medical-entity-codification/overview)) section.


# Medical Entity Codification
Source: https://developer.eka.care/docs/models/medical-entity-codification/overview

Map free-text medical entities to standardised ontology codes — SNOMED CT, LOINC, ICD-10-CM and Eka's medication database.

## Overview

The **Medical Entity Codification API** (MedLink Named Entity Linking) takes a
free-text medical entity — a symptom, diagnosis, lab test or drug — and links it
to the matching code in a standardised clinical ontology.

It powers structured, interoperable medical data: turning `"chest pain"` into
SNOMED CT `29857009`, `"hemoglobin"` into LOINC `718-7`, or `"type 2 diabetes
mellitus"` into ICD-10-CM `E11`.

> [!NOTE]
>
> This API supersedes the legacy [`GET /eka-mcp/linking/v1/snomed`](/api-sdk/datasets/linking/snomed)
> endpoint. See that page for a migration guide; the legacy endpoint remains
> operational for existing integrations.

## Base URL

All endpoints are served under:

```
https://api.eka.care/med-link/
```

## Authentication

Every request requires a Bearer access token:

```
Authorization: Bearer <access_token>
```

Generate the token using the Eka authorization flow — see
[Authorization](/api-sdk/auth/getting-started).

## Supported ontologies

| Ontology | `ontology` | `version` | Use it for | `metadata` |
| - | - | - | - | - |
| SNOMED CT | `snomed` | `20250401_extended` | Symptoms, findings, disorders, procedures | Not used |
| LOINC | `loinc` | `v1.0` | Lab tests and observations | **Recommended** |
| Medication | `medication` | `v5.0` | Branded and generic drugs | Optional |
| ICD-10-CM (Comprehend) | `icd-10-cm` | `comprehend` | Diagnoses from natural-language clinical text | Not used |

> [!NOTE]
>
> Always call [List Registry](/api-sdk/models/medical-entity-codification/registry)
> to confirm the live `ontology` and `version` values before linking.

## Endpoints

> **[List Registry](/api-sdk/models/medical-entity-codification/registry)**
>
> Discover available ontologies, versions and indexes.

> **[Link Entity](/api-sdk/models/medical-entity-codification/link-entity)**
>
> Link a single medical entity to ontology codes.

> **[Link Entities (Batch)](/api-sdk/models/medical-entity-codification/link-entity-batch)**
>
> Link up to 5 entities in a single call.

## The `metadata` field

`metadata` carries ontology-specific hints that improve linking accuracy:

* **LOINC** — strongly recommended. A `unit` or `specimen` can change which code
  is linked (e.g. blood vs. urine hemoglobin).
* **Medication** — optional. `form`, `generic_name` and `dose_unit` help resolve
  ambiguous brand names.
* **SNOMED CT** and **ICD-10-CM Comprehend** — `metadata` is ignored.

See each endpoint page and the ontology guides in
**Spotlight → Technologies → [Medical Entity Codification](/docs/models/technologies/codification/overview)** for details.

## Reading a result

Each candidate in `results` carries:

* `term_id` — the ontology code
* `term_name` — the human-readable term
* `score` — relevance/confidence (`null` for medication)
* `is_linked` — `true` when the pipeline is confident this is the single correct match
* `metadata` — ontology-specific detail about the candidate


# Models
Source: https://developer.eka.care/docs/models/models



# Open Models for Indian Healthcare AI

Eka Care releases purpose-built models for speech, documents and text in Indian clinical settings. All models are in the [EkaCare Public Healthcare LLMs](https://huggingface.co/collections/ekacare/ekacare-public-healthcare-llms) collection on Hugging Face and on the [India AI AIKosh platform](https://aikosh.indiaai.gov.in). Try them live at [medai.eka.care](https://medai.eka.care/).

| Model | Task | Size | Links |
| - | - | - | - |
| Parrotlet-a 2.5 Pro | Medical ASR (5 Indian languages) | \~5B | [AIKosh](https://aikosh.indiaai.gov.in/home/models/details/parrotlet_a_2p5_pro.html) · [Hugging Face](https://huggingface.co/ekacare/parrotlet-a-2.5-pro) |
| Parrotlet-A-EN-5B | Medical ASR (English) | 5B | [AIKosh](https://aikosh.indiaai.gov.in/home/models/details/parrotlet_a_en_5b.html) · [Hugging Face](https://huggingface.co/ekacare/parrotlet-a-en-5b) |
| Parrotlet-v 2.5 Pro | Medical record extraction (vision) | \~2B | [AIKosh](https://aikosh.indiaai.gov.in/home/models/details/parrotlet_v_2p5_pro.html) · [Hugging Face](https://huggingface.co/ekacare/parrotlet-v-2.5-pro) |
| Parrotlet-V-Lite-4B | Medical record parsing (vision) | 4B | [AIKosh](https://aikosh.indiaai.gov.in/home/models/details/parrotlet_v_lite_4b.html) · [Hugging Face](https://huggingface.co/ekacare/parrotlet-v-lite-4b) |
| Med Doc Classifier | Medical document classification | \~96M | [AIKosh](https://aikosh.indiaai.gov.in/home/models/details/med_doc_classifier.html) · [Hugging Face](https://huggingface.co/ekacare/med-doc-classifier) |
| Document PII Redactor | PII detection & redaction | – | [AIKosh](https://aikosh.indiaai.gov.in/home/models/details/document_pii_redactor.html) · [Hugging Face](https://huggingface.co/ekacare/document-pii-redactor) |
| Parrotlet-E | Multilingual medical embeddings | – | [AIKosh](https://aikosh.indiaai.gov.in/home/models/details/parrotlet_e.html) · [Hugging Face](https://huggingface.co/ekacare/parrotlet-e) |

***

## Speech

### Parrotlet-a 2.5 Pro

* A purpose-built ASR model for medical speech in Indian healthcare settings, transcribing Indian English, Hindi, Marathi, Kannada and Telugu, including the heavily code-mixed speech typical of real consultations.
* Combines a Whisper large-v3 encoder with a MedGemma 4B decoder, further tuned with GRPO on medical conversation data. Best Semantic WER in every language against nine production ASR systems on medical conversation sets.
* [AIKosh](https://aikosh.indiaai.gov.in/home/models/details/parrotlet_a_2p5_pro.html) | [Hugging Face](https://huggingface.co/ekacare/parrotlet-a-2.5-pro) | [Live demo](https://medai.eka.care/asr) | [Launch blog](https://info.eka.care/services/benchmark-update-releasing-parrotlet-a-2-5-pro)

***

### Parrotlet-A-EN-5B

* A healthcare-optimized ASR model for transcribing English medical speech in Indian clinical settings, combining a Whisper V3 encoder with a MedGemma3 4B decoder.
* Designed for accurate short-form medical audio transcription, it enables high-fidelity speech-to-text conversion for scribe and voice-enabled healthcare applications.
* [AIKosh](https://aikosh.indiaai.gov.in/home/models/details/parrotlet_a_en_5b.html) | [Hugging Face](https://huggingface.co/ekacare/parrotlet-a-en-5b) | [Launch blog](https://info.eka.care/services/parrotlet-a-en-5b-releasing-our-purpose-built-llm-for-english-asr-in-indian-healthcare)

***

## Documents & Vision

### Parrotlet-v 2.5 Pro

* A fine-tune of Gemma 4 E2B (\~2B effective parameters) for structured, schema-driven extraction from Indian medical records: prescriptions, invoices, lab reports and discharge summaries, plus PII detection.
* Prompted with a document image and a single task tag; returns schema-conformant JSON. Released under Apache 2.0 in bf16.
* [AIKosh](https://aikosh.indiaai.gov.in/home/models/details/parrotlet_v_2p5_pro.html) | [Hugging Face](https://huggingface.co/ekacare/parrotlet-v-2.5-pro) | [Live demo](https://medai.eka.care/medical-records) | [Launch blog](https://info.eka.care/services/releasing-parrotlet-open-models-open-weights-for-medical-document-intelligence)

***

### Parrotlet-V-Lite-4B

* A purpose-built vision LLM optimized for parsing Indian medical records, including lab reports, digital prescriptions, document classification, and PII extraction.
* Deployable via Hugging Face, it enables structured data extraction from medical images and PDFs for healthcare AI and interoperability workflows.
* [AIKosh](https://aikosh.indiaai.gov.in/home/models/details/parrotlet_v_lite_4b.html) | [Hugging Face](https://huggingface.co/ekacare/parrotlet-v-lite-4b) | [Launch blog](https://info.eka.care/services/parrotlet-v-lite-4b-releasing-our-purpose-built-vision-llm-for-parsing-medical-records)

***

### Med Doc Classifier

* A lightweight (\~96M parameter) encoder-only model on a SigLIP2-base backbone that sorts a document image into one of 27 classes across two hierarchical levels, and also flags whether it is medical and whether it is handwritten.
* Built by training many specialised models, ensembling them, and distilling the ensemble into one compact student. Released under Apache 2.0.
* [AIKosh](https://aikosh.indiaai.gov.in/home/models/details/med_doc_classifier.html) | [Hugging Face](https://huggingface.co/ekacare/med-doc-classifier) | [Live demo](https://medai.eka.care/classifier) | [Launch blog](https://info.eka.care/services/releasing-parrotlet-open-models-open-weights-for-medical-document-intelligence)

***

### Document PII Redactor

* Model weights powering the open-source [document-pii-redactor](https://github.com/eka-care/document-pii-redactor), which detects and redacts PII in both text and document images and is light enough to run on CPU.
* Trained to understand Indian names, documents and contexts; the text model works across Indian languages. The core contribution is the PII token classifier, with OCR as a pluggable front-end.
* [AIKosh](https://aikosh.indiaai.gov.in/home/models/details/document_pii_redactor.html) | [Hugging Face](https://huggingface.co/ekacare/document-pii-redactor) | [GitHub](https://github.com/eka-care/document-pii-redactor) | [Live demo](https://medai.eka.care/pii-redactor) | [Launch blog](https://info.eka.care/services/releasing-parrotlet-open-models-open-weights-for-medical-document-intelligence)

***

## Embeddings

### Parrotlet-E

* A state-of-the-art multilingual embedding model optimized for entity-level medical concept representation across 12 Indic languages and English.
* Fine-tuned on 18M+ SNOMED CT and UMLS-aligned term pairs, it enables robust cross-lingual medical coding, semantic search, and retrieval with benchmark-leading performance on Eka-IndicMTEB.
* [AIKosh](https://aikosh.indiaai.gov.in/home/models/details/parrotlet_e.html) | [Hugging Face](https://huggingface.co/ekacare/parrotlet-e) | [Launch blog](https://info.eka.care/services/introducing-parrotlet-e-and-eka-indicmteb-bridging-indias-multilingual-healthcare-gap)

***

## Evaluation

Models are evaluated with [KARMA – OpenMedEvalKit](https://github.com/eka-care/karMA-OpenMedEvalKit), our open-source evaluation framework, on the [Eka evaluation datasets](/docs/models/datasets). Current results are on each model card and in the launch blogs linked above; the [Eka Medical ASR dataset card](https://huggingface.co/datasets/ekacare/eka-medical-asr-evaluation-dataset) carries a public leaderboard.

***

*Models are released under the license stated on their respective Hugging Face model cards. Some models require accepting the terms on Hugging Face before download.*


# Resources
Source: https://developer.eka.care/docs/models/resources

Open-source tools, knowledge bases and reference lists from Eka MedAI.

Everything from Eka MedAI that isn't a [model](/docs/models/models) or a [dataset](/docs/models/datasets): evaluation tooling, knowledge graphs, document tooling, knowledge bases served over API and MCP, and the reference lists behind our services. For SDKs and agent frameworks across all Eka products, see the [Open Source](/docs/get-started/open-source) page.

## Evaluation

* **KARMA – OpenMedEvalKit** – Open-source framework for evaluating medical AI models on Indian clinical tasks; runs every dataset on the [Datasets](/docs/models/datasets) page. [GitHub](https://github.com/eka-care/karMA-OpenMedEvalKit) · [Launch blog](https://info.eka.care/services/introducing-karma-openmedevalkit-an-open-source-framework-for-medical-ai-evaluation)

## Knowledge Graphs

* **BODHI – Bharat Ontology for Disease & Healthcare Informatics** – Clinician-validated clinical knowledge graphs (conditions ↔ symptoms ↔ specialities; concepts ↔ drugs ↔ lab investigations) in Neo4j, CSV, PyTorch Geometric and RDF. [GitHub](https://github.com/eka-care/BODHI) · [Hugging Face](https://huggingface.co/datasets/ekacare/BODHI-S) · [Launch blog](https://info.eka.care/services/bodhi-bharat-ontology-for-disease-healthcare-informatics)

## Document Tooling

* **document-pii-redactor** – Detects and redacts PII in text and document images; CPU-friendly, trained for Indian names, documents and languages. [GitHub](https://github.com/eka-care/document-pii-redactor) · [Model weights](https://huggingface.co/ekacare/document-pii-redactor) · [Live demo](https://medai.eka.care/pii-redactor)
* **Med Doc Classifier** – Lightweight medical document classifier. [Model card](https://huggingface.co/ekacare/med-doc-classifier) · [Live demo](https://medai.eka.care/classifier)

## Knowledge Bases (API & MCP)

Curated Indian medical knowledge, available as web APIs and through the [MedAI Tools MCP Server](/docs/datasets/build-with-ai/mcp-server/introduction) for Claude, ChatGPT, Cursor and other MCP clients. The same knowledge bases are also exposed inside the [Eka MCP Server](/docs/emr/build-with-ai/mcp-server/introduction).

| Knowledge base | What it covers | Access |
| - | - | - |
| Indian Branded Drugs | 500,000+ Indian branded drugs with generic composition, form, therapy class and manufacturer | [API](/api-sdk/datasets/medications/search) · [MCP](/docs/datasets/build-with-ai/mcp-server/tools) |
| Pharmacology (NFI) | National Formulary of India: indications, dosing, contraindications, pregnancy safety | [API](/api-sdk/datasets/medications/pharmacology) · [MCP](/docs/datasets/build-with-ai/mcp-server/tools) |
| Indian Treatment Protocols | 180+ protocols from ICMR, RSSDI, ADA, WHO, KDIGO, AHA and others, for RAG grounding | [API](/api-sdk/datasets/protocols/search) · [MCP](/docs/datasets/build-with-ai/mcp-server/tools) |
| Medical Calculators | 400+ clinical calculators across 26 categories | [MCP](/docs/datasets/build-with-ai/mcp-server/tools) |
| Medical Entity Codification | SNOMED CT, LOINC, ICD-10-CM and medication linking for free-text entities | [API](/docs/models/medical-entity-codification/overview) · [Guide](/docs/models/technologies/codification/overview) |

## Reference Lists

Live lists maintained alongside the services; always check the source rather than a copy.

* **LOINC-linkable lab tests** – the 1,400+ investigations our lab report parser links to LOINC. [Notion](https://ekacare.notion.site/726b13df13ea4409b0cd30c6f3a80315?v=dcd10c722d3149d880ae889b06f4820a)
* **PII categories** – the 53 categories detected by the redactor, in the [document-pii-redactor README](https://github.com/eka-care/document-pii-redactor#readme)

## Where to Find Us

* [Hugging Face](https://huggingface.co/ekacare) – models and datasets
* [AIKosh](https://aikosh.indiaai.gov.in) – India AI mission listings
* [GitHub](https://github.com/eka-care) – open-source code
* [medai.eka.care](https://medai.eka.care/) – live demos
* [Blog](https://info.eka.care/services) – launches and benchmark updates


# Spotlight
Source: https://developer.eka.care/docs/models/spotlight

Open models, datasets and research for AI in Indian healthcare — and who is building on them.

Open models, datasets and research for AI in Indian healthcare, built by Eka Care and used by teams around the world.

> **[Models](/docs/models/models)**
>
> Parrotlet ASR, vision and embedding models

> **[Datasets](/docs/models/datasets)**
>
> Evaluation sets, knowledge graphs, population data

> **[Resources](/docs/models/resources)**
>
> KARMA, BODHI, MCP knowledge bases, reference lists

> **[Live demo](https://medai.eka.care/)**
>
> Try the models in your browser

## Latest Releases

> **[Parrotlet Open Models](https://info.eka.care/services/releasing-parrotlet-open-models-open-weights-for-medical-document-intelligence)**
>
> Open weights for medical document intelligence: Parrotlet-v 2.5 Pro, Med Doc Classifier and Document PII Redactor.

> **[Parrotlet-a 2.5 Pro](https://info.eka.care/services/benchmark-update-releasing-parrotlet-a-2-5-pro)**
>
> Medical ASR for Indian English, Hindi, Marathi, Kannada and Telugu, benchmarked against nine production systems.

> **[BODHI](https://info.eka.care/services/bodhi-bharat-ontology-for-disease-healthcare-informatics)**
>
> Bharat Ontology for Disease & Healthcare Informatics: open, clinician-validated clinical knowledge graphs.

## Blogs

* [Releasing Parrotlet Open Models: Open Weights for Medical Document Intelligence](https://info.eka.care/services/releasing-parrotlet-open-models-open-weights-for-medical-document-intelligence) VisionLLMOpen Weights
* [Benchmark Update: Releasing Parrotlet-a 2.5 Pro](https://info.eka.care/services/benchmark-update-releasing-parrotlet-a-2-5-pro) ASRLLMEvaluation
* [Beyond Frontier Models: Grounding AI in Indian Clinical Reality](https://info.eka.care/services/beyond-frontier-models-grounding-ai-in-indian-clinical-reality) LLMMCPEvaluation
* [BODHI: Bharat Ontology for Disease & Healthcare Informatics](https://info.eka.care/services/bodhi-bharat-ontology-for-disease-healthcare-informatics) Knowledge GraphClinicalOpen Source
* [Parrotlet-a 2 Pro: The Most Performant Speech Recognition Model for Indian Healthcare](https://info.eka.care/services/releasing-parrotlet-a-v2-the-gold-standard-for-medical-speech-recognition-in-indian-healthcare) ASRLLMEvaluation
* [Introducing KARMA – OpenMedEvalKit](https://info.eka.care/services/introducing-karma-openmedevalkit-an-open-source-framework-for-medical-ai-evaluation) EvaluationOpen Source
* [Parrotlet-E & Eka IndicMTEB](https://info.eka.care/services/introducing-parrotlet-e-and-eka-indicmteb-bridging-indias-multilingual-healthcare-gap) EmbeddingsMultilingualBenchmark
* [Beyond Traditional WER: Semantic WER for ASR](https://info.eka.care/services/beyond-traditional-wer-the-critical-need-for-semantic-wer-in-asr-for-indian-healthcare) ASREvaluation
* [Parrotlet-V Lite (4B) – Vision LLM](https://info.eka.care/services/parrotlet-v-lite-4b-releasing-our-purpose-built-vision-llm-for-parsing-medical-records) VisionLLMOpen Weights
* [Parrotlet-A EN (5B) – Medical ASR LLM](https://info.eka.care/services/parrotlet-a-en-5b-releasing-our-purpose-built-llm-for-english-asr-in-indian-healthcare) ASRLLMOpen Weights
* [Advancing Healthcare AI Evaluation in India](https://info.eka.care/services/advancing-healthcare-ai-evaluation-in-india-ekacare-releases-four-evaluation-datasets) DatasetsEvaluation
* [Lab-Ready and Prescription-Perfect: Eka Care's Small LLMs vs. Industry Giants](https://info.eka.care/services/lab-ready-and-prescription-perfect-ekas-small-llms-vs-industry-giants) VisionLLMEvaluation
* [Extracting Structured Information from Lab Reports: Challenges and Learnings](https://info.eka.care/services/eka-smart-report) DocumentsLab Reports
* [Eka's heart rate monitor](https://www.eka.care/services/get-the-pulse) PPGSignal Processing
* [Leveraging semantic technologies in healthcare](https://info.eka.care/services/leveraging-ontologies-in-health-care) OntologyKnowledge Graph
* [The Quiet Threat: Understanding Latent Iron Deficiency](https://www.eka.care/services/the-quiet-threat-understanding-latent-iron-deficiency) Population HealthLab Data
* [Cholesterol Chronicles – The Indian Disadvantage](https://info.eka.care/services/cholesterol-chronicles-the-indian-disadvantage-2) Population HealthLab Data
* [Annual Health Report – India, 2022](https://c.eka.care/insights_2022.pdf) Population HealthReport

## Used by the Community

External teams building on or citing Eka's open datasets, models and research.

> **[Google Health](https://github.com/Google-Health/medasr/blob/main/notebooks/fine_tune_with_hugging_face.ipynb)**
>
> MedASR fine-tuning tutorial uses the Eka Medical ASR dataset

> **[ElevenLabs](https://elevenlabs.io/blog/scribe-v2-medical-generally-available)**
>
> Scribe v2 Medical benchmarked on the Eka Medical ASR dataset

> **[Microsoft Research India](https://arxiv.org/abs/2609.17355)**
>
> Two papers with Ashoka University analyse Eka's clinical conversation and ASR datasets

> **[Academic research](https://aclanthology.org/2026.eacl-industry.40.pdf)**
>
> EACL 2026, Univ. of Hamburg, NORDIS TECH and others fine-tune or benchmark on Eka assets

> **All citations**
>
> **Building on Eka open assets**
>
> * **Google Health** – [MedASR fine-tuning notebook](https://github.com/Google-Health/medasr/blob/main/notebooks/fine_tune_with_hugging_face.ipynb) · fine-tunes on the [Eka Medical ASR dataset](https://huggingface.co/datasets/ekacare/eka-medical-asr-evaluation-dataset)
> * **ElevenLabs** – [Scribe v2 Medical GA](https://elevenlabs.io/blog/scribe-v2-medical-generally-available) · benchmarks on the [Eka Medical ASR dataset](https://huggingface.co/datasets/ekacare/eka-medical-asr-evaluation-dataset)
> * **USTC / Univ. of Florida** – [Synthetic Doctor-Patient Dialogue Generation for Robust Medical ASR](https://aclanthology.org/2026.eacl-industry.40.pdf) (EACL 2026) · fine-tunes [Parrotlet-a-en-5b](https://huggingface.co/ekacare/parrotlet-a-en-5b)
> * **NORDIS TECH** – [MedWER](https://arxiv.org/abs/2609.05728) · baselines on the [Eka Medical ASR dataset](https://huggingface.co/datasets/ekacare/eka-medical-asr-evaluation-dataset)
> * **Univ. of Hamburg** – [MoDiCoL](https://arxiv.org/abs/2606.14459) · sources medical speech from the [Eka Medical ASR dataset](https://huggingface.co/datasets/ekacare/eka-medical-asr-evaluation-dataset)
>
> **Research citing Eka**
>
> * **Microsoft Research India / Ashoka** – Jaiswal et al. (2026), [Evaluating Ambient Clinical Scribes in India](https://arxiv.org/abs/2609.17355) · [Eka Clinical Note Generation](https://huggingface.co/datasets/ekacare/clinical_note_generation_dataset) and Medical ASR datasets
> * **Microsoft Research India / Ashoka / IIT Madras** – Shailya et al. (2026), [Building a Cultural Perspective on Doctor-Patient Conversations](https://arxiv.org/abs/2609.18390) · [Eka Clinical Note Generation dataset](https://huggingface.co/datasets/ekacare/clinical_note_generation_dataset)
> * **Kumar et al. (2025)** – [ASR Under the Stethoscope](https://arxiv.org/abs/2512.10967) · [Eka Medical ASR dataset](https://huggingface.co/datasets/ekacare/eka-medical-asr-evaluation-dataset)

## Publications

* **When De-noising Hurts: A Systematic Study of Speech Enhancement Effects on Modern Medical ASR Systems** · Chondhekar, Murukuri, Vasani, Goyal, Badami, Rana, SN, Pandia, Katiyar, Jagadeesh, Gulati (2025) · [arXiv](https://arxiv.org/abs/2512.17562)
* **Latent iron deficiency in Indian women and children: A descriptive analysis** · Badami, SN, Vasani, Tuniki, Kapoor, Gulati (2024) · *International Journal of Clinical Biochemistry and Research* · [Article](https://www.ijcbr.in/article-details/22074) · DOI 10.18231/j.ijcbr.2024.010
* **Smartphone-based health monitoring in India: Data collection and evaluation for pulse rate estimation** · Shetty, Narasimhamurthy, Nataraj, Prabhu, Jagadeesh, Katre et al. (2024) · *Journal of Family Medicine and Primary Care*
* **AI Horizons in Indian Healthcare: A Vision for Transformation and Equity** · Kapoor, SN, PS, Sethia, DB · *Indian Journal of Community Medicine* · in print
* **Demographic Profile and Antibiotic Prescription Practices in Outpatient Private Practice for Respiratory Tract Infections in Urban India** · Arunkumar, SN, Kapoor, Gupta, Jainkuniya, Gulati · *Cureus* · under review


# ICD-10-CM
Source: https://developer.eka.care/docs/models/technologies/codification/icd-10-cm



## Overview

**ICD-10-CM** (International Classification of Diseases, 10th Revision, Clinical
Modification) is the standard code set for diagnoses. Eka Care's codification
pipeline links free-text diagnoses to ICD-10-CM codes.

| Property | Value |
| - | - |
| `ontology` | `icd-10-cm` |
| `version` | `comprehend` |
| `metadata` | Not used |

## The Comprehend version

The `comprehend` version is built on **AWS Comprehend Medical**, a clinical NLP
service. Unlike a plain term lookup, it understands diagnoses expressed in
natural clinical language — handling modifiers, qualifiers and surrounding
context — which makes it well suited to coding from real clinical notes.

## When to use it

Use it to code diagnoses from free-text clinical content:

* Diagnoses recorded in consultation or discharge notes
* Problem lists and assessments
* Claims and medical-coding workflows

Send the diagnosis as the `query` — no `metadata` is needed.

## Reading the results

Each result is an ICD-10-CM code:

* `term_id` — the ICD-10-CM code (e.g. `E11`)
* `term_name` — the diagnosis description
* `score` — confidence of the candidate
* `is_linked` — `true` when the pipeline is confident of the match

The response also includes a `query_breakdown` derived from AWS Comprehend
Medical:

* `entity` — the clinical entity detected in the query
* `entity_score` — confidence of that detection
* `traits` — detected traits, e.g. `DIAGNOSIS`
* `attributes` — detected attributes, e.g. a `QUALITY` of `type 2`

## Example

A query of `type 2 diabetes mellitus` links to ICD-10-CM `E11`
("Type 2 diabetes mellitus"), with `query_breakdown` reporting the detected
entity `diabetes mellitus` and the attribute `type 2`.

## Try it out

See the [Link Entity API](/api-sdk/models/medical-entity-codification/link-entity)
and select the **ICD-10-CM Comprehend** example to try it.


# LOINC
Source: https://developer.eka.care/docs/models/technologies/codification/loinc



## Overview

**LOINC** (Logical Observation Identifiers Names and Codes) is the global
standard for identifying lab tests and clinical observations. Eka Care's
codification pipeline links free-text lab test names to LOINC codes.

| Property | Value |
| - | - |
| `ontology` | `loinc` |
| `version` | `v1.0` |
| `metadata` | **Strongly recommended** |

## Why context matters

A lab test name on its own is often ambiguous. `Hemoglobin` measured in blood is
a different LOINC code from hemoglobin measured in urine; the same test reported
as a mass concentration differs from one reported as a molar concentration.

LOINC codification therefore relies on the `metadata` field to disambiguate.
Supplying the unit and specimen is the difference between a confident, correct
link and an uncertain one.

## The `metadata` field

| Key | Description |
| - | - |
| `unit` | Test unit, e.g. `g/dl`, `mg/dl`, `%`. The single most important hint. |
| `value` | Numeric result value — improves value-type matching. |
| `range` | Reference range for the result. |
| `specimen` | Specimen type, e.g. `blood`, `urine`. |
| `specimen_text` | Free-text specimen description (auto-detected if omitted). |
| `panel_name` | Panel name for multi-test panels. |
| `extended_test_name` | Extended or alternate test name. |

## Context changes the result

Consider the query `hemoglobin`:

* **Without `metadata`** — the top candidate is `haemoglobin_urine` and
  `is_linked` is `false`. The pipeline cannot tell which hemoglobin you mean.
* **With** `metadata: { "unit": "g/dl", "value": "14.5", "specimen": "blood" }`
  — the pipeline links to LOINC `718-7` ("HEMOGLOBIN (HB) \[Mass/Vol]") with
  `is_linked: true`.

## Reading the results

* `term_id` — the LOINC code (e.g. `718-7`)
* `is_linked` — `true` only when test name, unit and specimen all match
* `metadata.matching_breakdown` — which dimensions matched (`component_match`,
  `unit_match`, `specimen_match`, …)
* `metadata.eka_id` — Eka's internal lab identifier for the test

The response also includes a `query_breakdown` showing how the test name, unit
and specimen were parsed from your request.

## Supported lab tests

Eka Care maintains a curated list of lab tests that link to LOINC. Browse the
full catalogue here:

> **[Eka's LOINC-linkable lab tests](https://ekacare.notion.site/726b13df13ea4409b0cd30c6f3a80315?v=dcd10c722d3149d880ae889b06f4820a)**
>
> Public list of every lab test Eka can link to a LOINC code, with their
> expected names, units and specimens.

If the test you need isn't in the list, [get in touch](mailto:ekaconnect@eka.care)
— the catalogue is expanded continuously.

## Try it out

See the [Link Entity API](/api-sdk/models/medical-entity-codification/link-entity)
and select the **LOINC** example to try it.


# Medication
Source: https://developer.eka.care/docs/models/technologies/codification/medication



## Overview

The **Medication** ontology links free-text drug mentions to Eka Care's
medication database — a curated catalogue of branded and generic drugs available
in India, with their compositions, forms and manufacturers.

| Property | Value |
| - | - |
| `ontology` | `medication` |
| `version` | `v5.0` |
| `metadata` | Optional |

## When to use it

Use the medication ontology to code drug mentions from prescriptions, discharge
summaries or clinical notes — for example `Dolo 650` or `Paracetamol 500mg
Tablet`.

## How it works

The query is segmented into brand name, salt, form and volume; candidates are
retrieved from the medication database; and a hybrid matcher compares the
parsed query against each candidate's form, volume and salt.

A drug links (`is_linked: true`) only when the brand matches and every required
attribute — volume, form and qualifiers — matches exactly.

## The optional `metadata` field

`metadata` is not required, but it helps resolve ambiguous mentions:

| Key | Description |
| - | - |
| `form` | Medication form, e.g. `tablet`, `capsule`, `injection`. |
| `generic_name` | Generic / salt name of the drug. |
| `dose_unit` | Dosage unit, e.g. `mg`, `mcg`, `ml`. |
| `dose_custom` | Custom dosage string. |

If the form and dose are already present in the query (e.g. `Dolo 650 Tablet`),
`metadata` adds little. It is most useful when the query is terse or the form is
implied.

## Reading the results

Medication results do not use a numeric `score` — read the `metadata` instead:

* `term_id` — the medication identifier (e.g. `b-4117370658`)
* `is_linked` — `true` when the drug is matched with all required attributes
* `metadata.generic_name`, `generic_composition`, `manufacturer_name`,
  `product_type`, `is_otc` — catalogue detail for the drug
* `metadata.matching_breakdown` — per-attribute match detail; when a drug does
  not link, `uncoded_reason` explains why (e.g. `volume_mismatch`)
* `metadata.linking_requirements` — attributes still needed to link confidently
  (e.g. `form_needed`)

The response also includes a `query_breakdown` showing the brand, form and
volume parsed from your request.

## Example

A query of `Dolo 650` with `metadata: { "form": "tablet", "generic_name":
"paracetamol", "dose_unit": "mg" }` links to `Dolo 650 Tablet`
(`b-4117370658`), composition Paracetamol (650mg), with `is_linked: true`.

## Try it out

See the [Link Entity API](/api-sdk/models/medical-entity-codification/link-entity)
and select the **Medication** example to try it.


# Medical Entity Codification
Source: https://developer.eka.care/docs/models/technologies/codification/overview



## Overview

**Medical Entity Codification** is Eka Care's named entity linking (NEL)
technology. It maps a free-text medical entity — a symptom, diagnosis, lab test
or drug — to the matching code in a standardised clinical ontology.

Free text is how clinicians naturally record information, but it is hard for
machines to aggregate, compare or exchange. Codification bridges that gap:
`"chest pain"` becomes SNOMED CT `29857009`, `"hemoglobin"` becomes LOINC
`718-7`, and `"type 2 diabetes mellitus"` becomes ICD-10-CM `E11`. The result is
structured, interoperable health data.

## Supported ontologies

| Ontology | Domain | Guide |
| - | - | - |
| SNOMED CT | Symptoms, findings, disorders, procedures | [SNOMED CT](/docs/models/technologies/codification/snomed) |
| LOINC | Lab tests and observations | [LOINC](/docs/models/technologies/codification/loinc) |
| Medication | Branded and generic drugs | [Medication](/docs/models/technologies/codification/medication) |
| ICD-10-CM | Diagnoses from clinical text | [ICD-10-CM](/docs/models/technologies/codification/icd-10-cm) |

## How the pipeline works

Each codification request runs through three stages:

1. **Query understanding** — the input text is parsed for the target ontology.
   For LOINC this extracts the test name, unit and specimen; for medication, the
   brand, salt, form and volume; for ICD-10-CM Comprehend, the clinical entity
   and its attributes.
2. **Retrieval** — candidate terms are fetched from the ontology index, using
   semantic vector search, a curated knowledge base, or AWS Comprehend Medical
   depending on the ontology.
3. **Linking** — candidates are scored and the best single match is flagged
   with `is_linked: true` when the pipeline is confident.

## The role of context

Some ontologies need more than a name to resolve correctly. A lab test like
`hemoglobin` is ambiguous until you know the unit and specimen — blood and urine
hemoglobin are different LOINC codes. The API accepts an optional `metadata`
field to carry this context, which materially improves accuracy for LOINC and
medication. The per-ontology guides explain exactly what to send.

## Use Cases

* **Structured EMRs** — code symptoms, diagnoses and prescriptions consistently.
* **Lab standardisation** — link extracted test names to LOINC for longitudinal tracking.
* **Interoperability** — produce the coded entities required for FHIR resources.
* **Analytics** — normalise clinical entities for reliable population-level insights.
* **Medical coding** — map free-text diagnoses to ICD-10-CM for claims workflows.

## Try it out

1. Explore the [API Reference](/docs/models/medical-entity-codification/overview)
   to get started.
2. Call [List Registry](/api-sdk/models/medical-entity-codification/registry) to
   see the live ontologies and versions.
3. Link your first entity with [Link Entity](/api-sdk/models/medical-entity-codification/link-entity).

Ready to structure your clinical data? [Get in Touch](mailto:ekaconnect@eka.care) today.


# SNOMED CT
Source: https://developer.eka.care/docs/models/technologies/codification/snomed



## Overview

**SNOMED CT** (Systematized Nomenclature of Medicine — Clinical Terms) is the
most comprehensive clinical terminology in the world. Eka Care's codification
pipeline links free-text clinical entities — symptoms, findings, disorders and
procedures — to SNOMED CT concept identifiers.

| Property | Value |
| - | - |
| `ontology` | `snomed` |
| `version` | `20250401_extended` |
| `metadata` | Not used |

## When to use it

Use SNOMED CT to code clinical entities recorded during consultations:

* Patient-reported symptoms (`chest pain`, `shortness of breath`)
* Clinical findings and disorders
* Procedures and interventions

SNOMED CT is the right choice when you need a precise, granular clinical concept
rather than a billing-oriented code.

## How it works

The query is normalised, candidate concepts are retrieved through semantic
vector search over the SNOMED CT index, and a language model selects the single
best match. No `metadata` is required — send the clinical entity as the `query`.

## Reading the results

Each result is a SNOMED CT concept:

* `term_id` — the SNOMED CT concept identifier (e.g. `29857009`)
* `term_name` — a human-readable term for the concept
* `score` — semantic relevance of the candidate
* `is_linked` — `true` when the pipeline is confident this is the correct match
* `metadata.semantic_tag` — the concept's category (`finding`, `disorder`,
  `procedure`, …)

The pipeline also matches localised and transliterated terms, so a single
concept can be returned under multiple `term_name` variants across languages.

## Example

A query of `chest pain` links to SNOMED CT concept `29857009` ("Chest pain"),
tagged as a `finding`.

## Try it out

See the [Link Entity API](/api-sdk/models/medical-entity-codification/link-entity)
and select the **SNOMED CT** example to try it.


# Medical Document Parsing
Source: https://developer.eka.care/docs/models/technologies/document-parsing

Structured data from Indian medical documents — lab reports, prescriptions, discharge summaries, insurance policies — with PII redaction and document classification.

Eka's document parsing stack turns scanned, photographed or digital medical documents into structured, coded, FHIR-ready data. It is built on our own vision models ([Parrotlet-v](/docs/models/models)), trained on Indian documents, handwriting and formats, and runs without a human in the loop.

## What it does

* **Classifies** an incoming document (lab report, prescription, discharge summary, insurance policy, invoice and more) and flags handwritten and non-medical inputs
* **Extracts** structured fields per document type: tests, results, units and reference ranges from lab reports; diagnoses, medications, dosages and advice from prescriptions; policy and claim details from insurance documents
* **Codes** the output to standard ontologies: [LOINC](https://loinc.org/) and [UCUM](https://ucum.org/) for lab tests, [SNOMED CT](https://www.snomed.org/) for clinical concepts, our drug database for medications
* **Redacts** personally identifiable information in text and in the document image itself
* **Returns** results as JSON and as an [HL7 FHIR](https://www.hl7.org/fhir/overview.html) document bundle

Capabilities, supported document classes and accuracy numbers change with each model release; the current state is always on the model cards and launch blogs below.

## Read more

* [Releasing Parrotlet Open Models: Open Weights for Medical Document Intelligence](https://info.eka.care/services/releasing-parrotlet-open-models-open-weights-for-medical-document-intelligence) – Parrotlet-v 2.5 Pro, Med Doc Classifier and Document PII Redactor
* [Parrotlet-V Lite (4B)](https://info.eka.care/services/parrotlet-v-lite-4b-releasing-our-purpose-built-vision-llm-for-parsing-medical-records) – our first open vision LLM for medical records
* [Lab-Ready and Prescription-Perfect: Eka Care's Small LLMs vs. Industry Giants](https://info.eka.care/services/lab-ready-and-prescription-perfect-ekas-small-llms-vs-industry-giants)
* [Extracting Structured Information from Lab Reports: Challenges and Learnings](https://info.eka.care/services/eka-smart-report)

## Models and tools

* [Parrotlet-v 2.5 Pro](https://huggingface.co/ekacare/parrotlet-v-2.5-pro) · [Parrotlet-V-Lite-4B](https://huggingface.co/ekacare/parrotlet-v-lite-4b) · [Med Doc Classifier](https://huggingface.co/ekacare/med-doc-classifier) · [Document PII Redactor](https://huggingface.co/ekacare/document-pii-redactor)
* Evaluation set: [Medical Records Parsing Validation Set](https://huggingface.co/datasets/ekacare/medical_records_parsing_validation_set)
* Reference: [LOINC-linkable lab tests](/docs/models/resources#reference-lists)

## Try it out

* Live demos: [Medical records](https://medai.eka.care/medical-records) · [Classifier](https://medai.eka.care/classifier) · [PII redactor](https://medai.eka.care/pii-redactor)
* API: [Medical Document Parsing](/api-sdk/models/medical-document-parsing/introduction)
* Entity linking: [Medical Entity Codification](/docs/models/technologies/codification/overview)


# Medical Scribe
Source: https://developer.eka.care/docs/models/technologies/medical-scribe

Medical speech recognition and ambient clinical documentation for Indian healthcare.

Eka's medical scribe stack listens to a consultation or dictation and produces structured clinical documentation. It is built on [Parrotlet-a](/docs/models/models), our medical ASR models for Indian English and Indian languages, trained on real clinical speech with its accents, code-mixing and drug vocabulary.

## What it does

* **Transcribes** medical speech in Indian English, Hindi, Marathi, Kannada, Telugu and more, including code-mixed doctor–patient conversation
* **Recognises medical entities** — drug names, doses, conditions, procedures, lab tests — that general-purpose ASR gets wrong
* **Structures** the transcript into clinical notes, prescriptions and EMR-ready records
* **Ships as a product** — [EkaScribe](/docs/scribe/overview), an ambient AI scribe with SDKs and APIs

Model versions, language coverage and benchmark numbers change with each release; the current numbers are on the model cards and launch blogs below.

## Read more

* [Benchmark Update: Releasing Parrotlet-a 2.5 Pro](https://info.eka.care/services/benchmark-update-releasing-parrotlet-a-2-5-pro)
* [Parrotlet-a 2 Pro: The Most Performant Speech Recognition Model for Indian Healthcare](https://info.eka.care/services/releasing-parrotlet-a-v2-the-gold-standard-for-medical-speech-recognition-in-indian-healthcare)
* [Parrotlet-A EN (5B) – Medical ASR LLM](https://info.eka.care/services/parrotlet-a-en-5b-releasing-our-purpose-built-llm-for-english-asr-in-indian-healthcare)
* [Beyond Traditional WER: Semantic WER for ASR](https://info.eka.care/services/beyond-traditional-wer-the-critical-need-for-semantic-wer-in-asr-for-indian-healthcare)
* [When De-noising Hurts: Speech Enhancement Effects on Medical ASR](https://arxiv.org/abs/2512.17562)

## Models and datasets

* [Parrotlet-a 2.5 Pro](https://huggingface.co/ekacare/parrotlet-a-2.5-pro) · [Parrotlet-A-EN-5B](https://huggingface.co/ekacare/parrotlet-a-en-5b)
* Evaluation sets: [Eka Medical ASR Evaluation Dataset](https://huggingface.co/datasets/ekacare/eka-medical-asr-evaluation-dataset) (with public leaderboard) · [Clinical Note Generation Dataset](https://huggingface.co/datasets/ekacare/clinical_note_generation_dataset)

## Try it out

* Live demo: [ASR](https://medai.eka.care/asr)
* Product and APIs: [EkaScribe](/docs/scribe/overview)


# Build with AI
Source: https://developer.eka.care/docs/nhcx/build-with-ai

Set up a coding agent to build with NHCX: the reference skill.

Use the reference skill to have a coding assistant build your NHCX integration. It hands the assistant the same facts as these docs.

> [!NOTE]
>
> Check what the assistant writes against these docs, and test it in the sandbox before it reaches a patient.

> **[Reference skill](#install-the-skill)**
>
> Every operation, its hosts, auth and headers, in one install.

## Before you start

Three things have to be in place before anything on this page works.

| What you need | Why |
| - | - |
| A coding assistant | Claude Code, Cursor, Codex or ChatGPT. Any one is enough. Pick one and stay on it. |
| A paid plan on it | Free tiers stop partway through a long task. |
| Your own project open in it | The assistant reads and writes the folder it is opened in. Open the repository you are building in first. |

Then work down this page in order: install the skill, connect the MCP server where there is one, and ask for one flow at a time in plain language. Read what the assistant writes before you run it.

## Install the skill

The `eka-nhcx` skill carries the hosts, auth and headers, and every NHCX operation, each with a link to its page here. It is built from these docs, so it changes when they do.

In Claude Code:

```bash theme={null}
/plugin marketplace add eka-care/eka-docs
/plugin install eka-nhcx@eka-docs
```

In Cursor, Codex or another agent, copy the [skill folder](https://github.com/eka-care/eka-docs/tree/main/plugins/eka-nhcx/skills/eka-nhcx) into the folder your agent loads skills from. Its map is [`SKILL.md`](https://raw.githubusercontent.com/eka-care/eka-docs/main/plugins/eka-nhcx/skills/eka-nhcx/SKILL.md).

## Read these docs as an agent

Every page here is also plain text an agent can read.

* [`llms.txt`](https://developer.eka.care/llms.txt) is a map of every page.
* [`llms-full.txt`](https://developer.eka.care/llms-full.txt) is every page's text in one file.
* The menu at the top of each page copies it as Markdown, or opens it in Claude or ChatGPT.


# Overview
Source: https://developer.eka.care/docs/nhcx/getting-started



NHCX (National Health Claims Exchange) carries cashless insurance claims between your hospital and the payer, including PMJAY. ABDM Connect builds the FHIR bundles, signs and encrypts them, talks to the exchange and parses the payer's answers. You send plain JSON and read the results back.

Every NHCX API is under `/abdm/nhcx/v1` and takes the [common authentication and headers](/api-sdk/hie-cm/overview#authentication). `X-Hip-Id` selects the facility the claim is raised from.

***

## The Claim Journey

A **claim** is the case every call after setup hangs off. Create one per hospitalisation and keep its `claim_id` against your admission.

**1. Find the payer and the policy**

[Search Payers](/api-sdk/nhcx/search-payers) gives the `participant_code` used as `payer_id`. Then [Search Policies](/api-sdk/nhcx/search-policies) by member ID, ABHA number or mobile number. Try the member ID first when the patient has a PMJAY card.

If no policy comes back, call [Discover Policy](/api-sdk/nhcx/discover-policy) and poll [Policy Discovery Status](/api-sdk/nhcx/discovery-status) until `status` is `found`.

**2. Check eligibility**

[Check Eligibility](/api-sdk/nhcx/check-eligibility) says whether the policy is in force and returns the wallet balance. The payer rejects pre-auths above the wallet balance, so show it.

**3. Pick procedures from the catalogue**

Browse the policy's catalogue with [List Specialities](/api-sdk/nhcx/list-specialities), [List Procedures](/api-sdk/nhcx/list-procedures) and [Get Procedure](/api-sdk/nhcx/get-procedure). If the catalogue is empty, call [Refresh Plan](/api-sdk/nhcx/refresh-plan).

**4. Create the claim**

[Create Claim](/api-sdk/nhcx/create-claim) with the `policy_id` and the chosen procedures. It returns the `claim_id` and asks the payer which documents and questionnaires each procedure needs. That answer arrives on the `coverage_eligibility` row of [Get Claim Requests](/api-sdk/nhcx/claim-requests) and drives the pre-auth form.

**5. Authenticate the beneficiary**

Send a consent questionnaire on the submit, or capture biometrics with [Init Biometric Auth](/api-sdk/nhcx/biometric-init) and [Verify Biometric Auth](/api-sdk/nhcx/biometric-verify), then pass the `user_token` with `auth_type: biometric`. Cyclic procedures such as dialysis and chemotherapy need a biometric capture on every treatment visit.

**6. Submit the pre-auth**

[Submit Pre-auth](/api-sdk/nhcx/submit-preauth) with the treating doctor, diagnosis, documents and answers. Use the same API with a different `request_type` to answer a payer query, resubmit after a rejection or ask for an enhancement. [Cancel Pre-auth](/api-sdk/nhcx/cancel-preauth) withdraws it.

**7. Submit the claim**

After discharge, [Submit Claim](/api-sdk/nhcx/submit-claim) with the discharge details, itemized billing and mandatory documents. Each billed line gets its own verdict.

**8. Track payment and disputes**

[Get Claim Payments](/api-sdk/nhcx/claim-payments) lists the payer's payment notices. A rejected claim, or one settled with more than 20% deducted, can be appealed once with [Reprocess Claim](/api-sdk/nhcx/reprocess-claim). [Get Claim](/api-sdk/nhcx/get-claim) tells you which in `review_path`.

> [!TIP]
>
> Users fill long forms over several sittings. [Save Draft](/api-sdk/nhcx/save-draft) stores a partial pre-auth or claim form without submitting it.

***

## Every Submit Is Asynchronous

A `2xx` on a submit means the request reached the payer, not that it was approved. Each submit returns a `request_id` with `status: "request.initiated"`:

```json theme={null}
{
  "request_id": "6f1c2b0e-...",
  "status": "request.initiated",
  "message": "Preauth request submitted successfully"
}
```

Poll [Get Claim Request](/api-sdk/nhcx/claim-request) with that `request_id`:

| `status` | What to do |
| - | - |
| `request.initiated`, `response.partial` | Keep polling. `response.partial` is an interim acknowledgement, not the verdict |
| `response.complete` | Read `outcome` and the per-item verdicts in `items` |
| `response.error` | Show `error_message` as it is |

Poll every 5 to 10 seconds for the first minute, then back off. Some procedures take the payer hours to decide.

[Get Claim Requests](/api-sdk/nhcx/claim-requests) lists every exchange on a claim. Build your screens from it rather than from the claim's `status` alone: it shows which request is pending, queried or failed.

***

## Errors

| Error | Meaning | What to do |
| - | - | - |
| `400` with `issues` | The backend checked the submit before sending it and found problems | Show every entry in `issues`, fix and resubmit |
| `5XX` | A server error | Retry |
| `response.error` on a request | The payer or the exchange refused it | Show `error_message`. Treat `error_code` as opaque and never branch on it |

```json theme={null}
{
  "error": "claim validation failed: <issue 1>; <issue 2>",
  "issues": ["<issue 1>", "<issue 2>"]
}
```

An errored request uses up nothing. A corrected submission is not penalised, and earlier approvals stand.

***

## Conventions

* **Enums are open.** Compare values case-insensitively and show unknown values as they are.
* **Flags before caps.** In [Get Procedure](/api-sdk/nhcx/get-procedure), read a cap such as a quantity or cycle limit only when its flag is set.
* **Dates** are `YYYY-MM-DD`. Date-times are RFC 3339 with the `+05:30` offset.
* **Documents** are sent inline as base64 `content`. Read them back with [Get Claim Request Document](/api-sdk/nhcx/claim-request-document).

***

## Records Adapter

The payer often wants the clinical records behind a claim. Register your HIS records API once with [Register Records Adapter](/api-sdk/nhcx/register-adapter), and ABDM Connect fetches an admission's visits and their FHIR bundles from it through [Get Admission Visits](/api-sdk/nhcx/admission-visits) and [Get Visit FHIR](/api-sdk/nhcx/visit-fhir).


# Glossary
Source: https://developer.eka.care/docs/nhcx/glossary

The terms used in the NHCX docs, what each one means, and the page where you meet it.

The terms you meet in the NHCX docs. Follow the link in the last column to see a term in context.

| Term | What it means | Where it is used |
| - | - | - |
| NHCX | National Health Claims Exchange. It carries cashless insurance claims, including PMJAY, between your hospital and the payer. ABDM Connect builds, signs and encrypts the FHIR bundles for you. | [NHCX overview](/docs/nhcx/getting-started) |
| Claim | The NHCX case that every call after setup hangs off. You create one per hospitalisation and keep its `claim_id` against your admission. | [NHCX overview](/docs/nhcx/getting-started) |
| Pre-auth | The NHCX request for approval you submit with the treating doctor, diagnosis, documents and answers. The payer rejects a pre-auth above the policy's wallet balance. | [NHCX overview](/docs/nhcx/getting-started) |

For terms from every Eka product, see the [Eka glossary](/docs/get-started/glossary).


# ABDM Connect
Source: https://developer.eka.care/docs/products/abdm

Connect your hospital system to India's health stack: ABHA, linked records, consent, claims and the UHI network.

Your hospital system joins the Ayushman Bharat Digital Mission (ABDM). Patients bring their ABHA (Ayushman Bharat Health Account), and records move between facilities with their consent. Claims go to insurers over one exchange. Eka handles the gateway, the encryption and the callbacks for you.

## What you build with

> **[HIE-CM](/docs/hie-cm/about)**
>
> ABHA, care contexts, consent and records.

> **[NHCX](/docs/nhcx/getting-started)**
>
> Eligibility, pre-auth and insurance claims.

> **[UHI](/docs/uhi/journeys/uhi-book-physical-consultation)**
>
> Blood bank search and consultations across the network.

## How they fit together

**1. Create or find the patient's ABHA**

Milestone 1 covers ABHA [creation and login](/docs/hie-cm/flows/m1). The [quickstart](/docs/hie-cm/quickstart) creates a sandbox ABHA in about ten minutes.

**2. Link the visit**

[Register a walk-in patient and link the visit](/docs/hie-cm/journeys/hip-register-patient-and-link-visit) as a care context, so the records belong to their ABHA.

**3. Share records with consent**

[Fetch a patient's records with consent](/docs/hie-cm/journeys/hiu-fetch-records-with-consent) from every facility that holds them.

**4. Submit the claim**

Check eligibility, get pre-authorisation and submit the claim through [NHCX](/docs/nhcx/getting-started).

**5. Reach the network**

[Book an in-person visit over UHI](/docs/uhi/journeys/uhi-book-physical-consultation), or search [blood banks](/docs/uhi/blood-bank/getting-started) near the patient.

## Start building

* [ABDM Connect quickstart](/docs/hie-cm/quickstart): a sandbox ABHA without writing code.
* [What is ABDM Connect](/docs/hie-cm/about): the roles, the milestones and what you can build.
* API reference: [HIE-CM](/api-sdk/hie-cm/overview), [NHCX](/api-sdk/nhcx/search-payers) and [UHI](/api-sdk/uhi/blood-bank/state-district).
* New to Eka? Get your keys first in [Build with Eka](/docs/get-started/overview).


# Solutions
Source: https://developer.eka.care/docs/products/clinical-intelligence

The Eka products you build your own clinical tools on: the medical scribe, document parsing and the clinical MCP server.

You build your own clinical tools on Eka's APIs, SDKs and MCP server. Three products cover the work, from the consultation to the patient's chart. Each one has its own documentation and API reference.

## What you build with

> **[Medical Scribe](/docs/scribe/overview)**
>
> Consultations become structured notes that complete the chart.

> **[Medical Document Parsing](/docs/models/medical-document-parsing)**
>
> Any medical record, in any format, becomes structured data.

> **[Clinical MCP](/docs/datasets/build-with-ai/mcp-server/introduction)**
>
> Ground your agent in Indian drugs, treatment protocols, pharmacology and clinical calculators.

## How they fit together

**1. Record the consultation**

Start a [Medical Scribe](/docs/scribe/overview) session and upload the audio. The [quickstart](/docs/scribe/quickstart) goes from audio to a structured note in five calls.

**2. Take the report in**

Upload a lab report to [document parsing](/docs/models/medical-document-parsing). A [webhook](/docs/models/medical-document-parsing/smart-report-webhook) tells you when the result is ready.

**3. Code the clinical terms**

Send diagnoses and findings to [entity codification](/docs/models/medical-entity-codification). You get codes such as ICD-10, SNOMED CT and LOINC.

**4. Ground your agent in clinical knowledge**

Connect your agent to the [clinical MCP server](/docs/datasets/build-with-ai/mcp-server/introduction). It can search Indian branded drugs, find treatment protocols, look up pharmacology and run clinical calculators.

## Start building

* [Spotlight](/docs/models/spotlight): the open models and datasets, and who is building on them.
* [Open assets](/docs/models/models): Eka's open models, on AIKosh and Hugging Face.
* API reference: [Medical Scribe](/api-sdk/scribe/sessions/overview) and [document parsing](/api-sdk/models/medical-document-parsing/introduction).
* New to Eka? Get your keys first in [Build with Eka](/docs/get-started/overview).


# Patient experiences
Source: https://developer.eka.care/docs/products/patient-experiences

A clinic's booking site, an agent that guides patients and books their visits, and the records they keep, built on Eka.

You build what the patient sees. A clinic's website books appointments into its Eka EMR. A patient-facing agent answers questions, guides the patient to the right care and books the visit. The patient's reports and records are stored and shared from one place. Five Eka products sit behind these.

## What you build with

> **[Agents](/docs/products/agents)**
>
> Build the patient's agent with the Echo Agent Kit, or embed MedAssist as it is.

> **[EMR](/docs/emr/appointments)**
>
> Finds open slots, books the appointment and sends reminders.

> **[Billing](/docs/billing/payments)**
>
> Records the payment for the consultation, with a receipt ID.

> **[Health Records](/docs/health-records/read-documents)**
>
> Lists and retrieves the patient's documents and records.

> **[Models](/docs/get-started/whats-possible/health-assessment)**
>
> Runs an AI health quiz in your app, built with four function calls.

## How they fit together

**1. Start the conversation**

Embed [MedAssist](/docs/agents/medassist) in your app, or build an agent with the [Echo Agent Kit quickstart](/docs/agents/agent-kit/quickstart).

**2. Book the visit**

The agent books a slot through [appointments](/docs/emr/appointments). The [appointments recipe](/docs/get-started/whats-possible/appointment-management) builds the booking screen end to end.

**3. Take the payment**

Record the [payment](/docs/billing/payments) for the consultation, in full or in parts.

**4. Remind and follow up**

Send the reminder with the [notify API](/api-sdk/emr/notify/notify) before the visit.

**5. Give the patient their records**

Build a personal health record app that pulls the patient's records from every hospital, with the [PHR app flows](/docs/hie-cm/phr/overview).

**6. Share reports and assessments**

Show the patient's [records](/docs/health-records/read-documents), and run a [health quiz](/docs/get-started/whats-possible/health-assessment) between visits.

## Start building

* [Echo Agent Kit quickstart](/docs/agents/agent-kit/quickstart): your first agent.
* [EMR MCP server](/docs/emr/build-with-ai/mcp-server/introduction): let an AI assistant book appointments and manage patients.
* API reference: [Agents](/api-sdk/agents/overview), [EMR](/api-sdk/emr/instructions/before-you-begin), [Billing](/api-sdk/billing/get-transaction-status) and [Health Records](/api-sdk/health-records/create-overview).
* New to Eka? Get your keys first in [Build with Eka](/docs/get-started/overview).


# EkaScribe
Source: https://developer.eka.care/docs/scribe/about

Clinical and enterprise use cases for medical-grade speech-to-documentation APIs

## EkaScribe Use Cases

**EkaScribe APIs** enable healthcare platforms, EMRs, and hospital systems to convert clinical audio into **accurate, structured medical documentation** using medical-grade speech recognition.

With support for **multiple languages**, **specialty-aware templates**, and **flexible integration models**, EkaScribe fits seamlessly into both **real-time** and **asynchronous** clinical workflows.

The following use cases highlight how EkaScribe can be leveraged across healthcare organizations and digital health platforms.

Read more : ([API Reference - Ekascribe](/docs/scribe/overview)) section.

***

## Clinical Documentation Automation

Automatically convert doctor–patient conversations into structured clinical notes, reducing manual documentation effort and improving clinician productivity across outpatient and inpatient settings.

***

## EMR and EHR Documentation

Generate EMR-ready medical notes in predefined templates and formats that integrate directly into electronic medical record systems used by hospitals and clinics.

***

## Hospital and Clinic Chain Enablement

Standardize documentation workflows across large hospital networks and clinic chains using consistent transcription models, templates, and output schemas.

***

## Specialty-Based Medical Notes

Produce structured notes aligned with specific medical specialties by providing contextual information during transcription, improving accuracy and relevance of outputs.

***

## Multilingual Consultation Transcription

Support consultations in multiple regional and international languages, enabling clinicians to document encounters naturally while maintaining standardized medical records.

***

## Teleconsultation and Virtual Care Support

Integrate real-time or recorded transcription into telemedicine platforms to capture complete consultation records during virtual visits.

***

## Audio Dictation for Clinicians

Enable voice-first documentation by allowing clinicians to dictate notes, observations, or summaries that are automatically converted into structured medical records.

***

## Post-Consultation Summaries and Reports

Generate consultation summaries that can be reviewed by clinicians, shared with patients, or stored for follow-up and continuity of care.

***

## Scalable Transcription Pipelines

Process large volumes of clinical audio using batch uploads, job tracking, and webhooks to support enterprise-scale documentation workflows.

***

## Healthcare Analytics and Compliance

Leverage structured transcription outputs for reporting, audit trails, quality reviews, and compliance workflows across healthcare organizations.

Read more : ([API Reference - Ekascribe](/docs/scribe/overview)) section.


# Authenticate & Try the APIs
Source: https://developer.eka.care/docs/scribe/authenticate-and-try

Paste your client credentials once and call every EkaScribe API live from these docs

Every API page in this section has a built-in playground — you can call the real API from your browser. Authenticate once and try the whole EkaScribe flow end-to-end, no code required.

## Step 1 — Get your access token

**1. Open the Client Login API**

Go to **[Client Login](/api-sdk/auth/client-login)** and click **Try it**.

**2. Paste your credentials**

Enter your `client_id` and `client_secret` in the request body and hit **Send**.

```json theme={null}
{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}
```

> [!NOTE]
>
> Don't have credentials? Create them in the [Eka Developer Console](https://console.eka.care) under **Manage API Credentials**.

**3. Copy the access\_token**

The response contains your token:

```json theme={null}
{ "access_token": "eyJhbGciOi...", "expires_in": 1800, "refresh_token": "..." }
```

## Step 2 — Set the token once

On any EkaScribe API page, paste the `access_token` into the **Authorization → Bearer** field of the playground. The docs remember it, so every other EkaScribe endpoint page is instantly authenticated too.

## Step 3 — Try the APIs, one by one

Walk the real flow directly from the docs:

| # | Try | What you'll see |
| - | - | - |
| 1 | [List Templates](/api-sdk/scribe/templates/list-templates) | The note templates available to your workspace |
| 2 | [Create Session](/api-sdk/scribe/sessions/create-session) | A new `session_id` — use it in the next calls |
| 3 | [Upload Audio](/api-sdk/scribe/sessions/upload-audio) | Send your audio — **use the cURL on that page** (raw binary uploads can’t be sent from the browser playground) |
| 4 | [End Session](/api-sdk/scribe/sessions/end-session) | Processing starts (`202`) |
| 5 | [Get Session](/api-sdk/scribe/sessions/get-session) | `202` while processing → `200` with the structured note |
| 6 | [List Session Documents](/api-sdk/scribe/documents/list-session-documents) | Every document generated on the session |
| 7 | [Get Document](/api-sdk/scribe/documents/get-document) | Note metadata + a download URL for the content |

> [!TIP]
>
> Want to try a custom format? [Create Template](/api-sdk/scribe/templates/create-template) with your own markdown instructions, then pass its `template_id` in Create Session — the notes come back in your format.

> [!NOTE]
>
> Access tokens expire (`expires_in` is in seconds — typically 30 minutes). If calls start returning `401`, run Step 1 again, or use the [Refresh Token API](/api-sdk/auth/refresh-token-v2). You can also create a **long-lived token** against your client in the Developer Console and use it directly as the Bearer token.


# Build with AI
Source: https://developer.eka.care/docs/scribe/build-with-ai

Set up a coding agent to build with EkaScribe: the reference skill and the CLAUDE.md file.

Use these to have a coding assistant build your EkaScribe integration. Each one hands it the same facts as these docs.

> [!NOTE]
>
> Check what the assistant writes against these docs, and test it in the sandbox before it reaches a patient.

> **[Reference skill](#install-the-skill)**
>
> Every operation, its hosts, auth and headers, in one install.

> **[CLAUDE.md file](/docs/scribe/build-with-ai/claude-md)**
>
> The four calls and their rules, in one file to drop into your project.

## Before you start

Three things have to be in place before anything on this page works.

| What you need | Why |
| - | - |
| A coding assistant | Claude Code, Cursor, Codex or ChatGPT. Any one is enough. Pick one and stay on it. |
| A paid plan on it | Free tiers stop partway through a long task. |
| Your own project open in it | The assistant reads and writes the folder it is opened in. Open the repository you are building in first. |

Then work down this page in order: install the skill, connect the MCP server where there is one, and ask for one flow at a time in plain language. Read what the assistant writes before you run it.

## Install the skill

The `eka-scribe` skill carries the hosts, auth and headers, and every Scribe operation, each with a link to its page here. It is built from these docs, so it changes when they do.

In Claude Code:

```bash theme={null}
/plugin marketplace add eka-care/eka-docs
/plugin install eka-scribe@eka-docs
```

In Cursor, Codex or another agent, copy the [skill folder](https://github.com/eka-care/eka-docs/tree/main/plugins/eka-scribe/skills/eka-scribe) into the folder your agent loads skills from. Its map is [`SKILL.md`](https://raw.githubusercontent.com/eka-care/eka-docs/main/plugins/eka-scribe/skills/eka-scribe/SKILL.md).

## Prompting an agent for Scribe

Tell the assistant these, and check its output against them.

| Tell it | Because |
| - | - |
| Keep the client secret on a server | The secret never goes in browser code. Exchange it on a small backend and hand the UI only the short-lived access token. |
| Upload raw audio bytes | The upload takes the bytes themselves: not multipart, not JSON, not base64. |
| Read the HTTP status when polling | 202 means still processing, 200 means done, 206 means some templates failed, and 410 means the session expired. |
| Use a chunked session for files over 10 MB | A single upload takes one file up to 10 MB. Longer recordings upload in numbered chunks before the session ends. |
| Sign in again on a 401 | The access token expires. A 401 means fetch a new one, not that the call is wrong. |

The [CLAUDE.md file](/docs/scribe/build-with-ai/claude-md) carries these rules and the four calls in one file you can drop into a project.

## Read these docs as an agent

Every page here is also plain text an agent can read.

* [`llms.txt`](https://developer.eka.care/llms.txt) is a map of every page.
* [`llms-full.txt`](https://developer.eka.care/llms-full.txt) is every page's text in one file.
* The menu at the top of each page copies it as Markdown, or opens it in Claude or ChatGPT.


# Build with AI (CLAUDE.md)
Source: https://developer.eka.care/docs/scribe/build-with-ai/claude-md

Drop this file into your project and ask Claude, Cursor or any coding agent to build the EkaScribe flow for you

Copy the file below into your project as `CLAUDE.md` (or paste it into any LLM) and prompt: *"Build me a page with record, stop and transcribe buttons that uses the EkaScribe API per CLAUDE.md."* It contains everything an agent needs — auth, the 4-call flow, request/response shapes and constraints.

```markdown CLAUDE.md theme={null}
# EkaScribe API Integration Guide

Goal: record or pick an audio file of a doctor–patient conversation and get back
a structured clinical note using the EkaScribe API.

Base URL: https://api.eka.care

## Authentication

POST /connect-auth/v1/account/login
Body: { "client_id": "<id>", "client_secret": "<secret>" }
→ 200 { "access_token": "...", "expires_in": 1800, "refresh_token": "..." }

Send `Authorization: Bearer <access_token>` on every other call.
SECURITY: never put client_secret in browser code — exchange it on a small
backend/proxy and hand only the short-lived access_token to the UI. If the
browser is blocked by CORS, route all calls through that proxy.

## The flow — 4 calls

### 1. Create session
POST /voice/v1/sessions
Body: {
  "upload_type": "single",                     // REQUIRED. single = one file ≤ 10 MB
  "model": "pro",                              // optional: pro | lite
  "language_hint": ["en"],                     // optional ISO 639-1 codes
  "templates": ["clinical_notes_template"]     // optional, max 2 template IDs
}
→ 201 { "session_id": "...", "upload_url": "...", "expires_at": "..." }

### 2. Upload audio
POST /voice/v1/sessions/{session_id}/audio/audio_0.webm
Body: RAW audio bytes (not multipart, not JSON, no base64).
Content-Type header optional — detected from the filename extension
(.webm .mp3 .wav .ogg .m4a .mp4).
→ 200 { "success": true }

### 3. End session (starts processing)
POST /voice/v1/sessions/{session_id}/end     — no body needed
→ 202

### 4. Poll for the result
GET /voice/v1/sessions/{session_id}          — every ~1 s
HTTP status is the signal:
  202 → still processing, keep polling
  200 → done:
    {
      "transcript": "…",
      "templates": [
        { "clinical_notes_template": {
            "status": "success",
            "document_id": "doc_…",
            "data": { …structured note… } } }
      ]
    }
  206 → done but some templates failed
  410 → session expired (create a new one)

## UI to build

- Input for the access token (or client_id/secret form hitting the proxy)
- "Start Recording" / "Stop" buttons using MediaRecorder (audio/webm),
  plus a file picker as fallback
- "Transcribe" button that runs: create → upload → end → poll,
  with a visible status (recording / uploading / processing / done)
- Render the transcript and the structured note (templates[i][id].data);
  show readable errors for 4xx/410/timeouts

## Rules & limits

- single upload: one file, max 10 MB. Longer recordings: create the session
  with "upload_type": "chunked" and upload audio_0.webm, audio_1.webm, …
  in order before calling end.
- Poll every ~1 s; give up after ~5 minutes.
- Sessions expire ~1 hour after creation if never ended.
- 401 → token expired; re-authenticate.
- List available templates: GET /voice/api/v1/template
  → { "items": [ { "id", "title", "desc" } ] }
- Create a custom note format: POST /voice/api/v1/template
  Body: { "title": "…", "desc": "<markdown describing the note structure>", "section_ids": [] }
  → use the returned template_id in step 1.

## Reference

- Docs: https://developer.eka.care/docs/scribe/overview
- Full docs for LLMs: https://developer.eka.care/llms-full.txt
```

> [!NOTE]
>
> Need credentials? Create them in the [Eka Developer Console](https://console.eka.care) under **Manage API Credentials**.


# Glossary
Source: https://developer.eka.care/docs/scribe/glossary

The terms used in the EkaScribe docs, what each one means, and the page where you meet it.

The terms you meet in the EkaScribe docs. Follow the link in the last column to see a term in context.

| Term | What it means | Where it is used |
| - | - | - |
| EkaScribe | Eka's AI medical scribe. You record or stream a consultation or dictation and get back a transcript and structured clinical notes in the format you define. | [EkaScribe overview](/docs/scribe/overview) |
| EkaScribe session | One unit of work in EkaScribe, identified by a `session_id`. It ties audio capture, processing and results together: you create it, send audio, end it, then read the notes. | [Sessions overview](/api-sdk/scribe/sessions/overview) |
| Template | A note format you describe in plain markdown, such as a SOAP note or a discharge summary. You name templates when you create a session, and EkaScribe returns one structured note per template. | [Create template](/api-sdk/scribe/templates/create-template) |
| `pro` and `lite` | The two EkaScribe models. `pro` adds speaker diarization, custom templates and 60-minute sessions; `lite` is fast and built for dictation. | [EkaScribe overview](/docs/scribe/overview) |

For terms from every Eka product, see the [Eka glossary](/docs/get-started/glossary).


# Overview
Source: https://developer.eka.care/docs/scribe/overview

EkaScribe turns clinical conversations into structured medical notes — via a simple session-based API

EkaScribe is Eka Care's AI medical scribe. Record or stream a consultation (or a dictation) and get back accurate, structured clinical notes — in the exact format you define — across 10+ Indian and international languages.

## How it works

One session, five calls:

```
Create Session  →  Upload Audio  →  End Session  →  Poll  →  Structured Notes
POST /sessions     POST .../audio    POST .../end     GET /sessions/{id}
```

1. **Create a session** with the note templates you want.
2. **Send audio** — HTTP chunks or a real-time WebSocket stream.
3. **End the session** to start processing.
4. **Get the results** — transcript plus structured notes per template (poll or webhook).

Start with the [Quickstart](/docs/scribe/quickstart) — the full flow is \~30 lines of code in any language.

## What you can build with it

> **[Sessions API](/api-sdk/scribe/sessions/overview)**
>
> Voice capture and transcription: create sessions, upload or stream audio, retrieve structured results.

> **[Templates API](/api-sdk/scribe/templates/create-template)**
>
> Define your own note formats in plain markdown — SOAP notes, specialty OPD notes, discharge summaries.

> **[Documents API](/api-sdk/scribe/documents/create-update-document)**
>
> Read, list, edit and manage every note generated on a session.

> **[Try the APIs live](/docs/scribe/authenticate-and-try)**
>
> Paste your client credentials and call every EkaScribe API from your browser.

To see the note land in the patient's record with a prescription and a parsed lab report, follow [Scribe with medical records](/docs/solutions/scribe-and-medical-records).

## Key capabilities

* **Built on an open protocol** — all APIs implement the [MedScribe Alliance scribe-emr protocol](/docs/scribe/protocol/overview); EkaScribe is the first scribe service to open-source it. No vendor lock-in.
* **Custom templates** — describe your note format in markdown; EkaScribe follows it. No rigid schemas.
* **Multilingual** — English, Hindi, Tamil, Telugu, Bengali, Marathi, Gujarati, Kannada, Malayalam, Punjabi. Auto-detection and output translation.
* **Real-time or batch** — WebSocket streaming for live scribing, chunked HTTP upload for recorded audio.
* **Two models** — `pro` (speaker diarization, custom templates, 60-min sessions) and `lite` (fast, dictation-focused).
* **FHIR output** — notes available as a [FHIR bundle](/docs/scribe/resources/fhir-structure) for interoperability.
* **Webhooks** — get notified when processing completes instead of polling.

## Integration options

| Option | Best for | Get started |
| - | - | - |
| **REST APIs** | Any language, full control | [Quickstart](/docs/scribe/quickstart) |
| **SDKs** (TypeScript, Python, Java, Android, iOS) | Fastest integration — VAD, chunking, retries handled for you | [SDKs](/api-sdk/scribe/sdks/ts-sdk) |
| **Chrome Extension** | No-code, works on any web page | [Install](https://chromewebstore.google.com/detail/ekascribe-ai-powered-clin/nncfcjgelepkhpjfkejgkncdfbcfmhom) |

## Integrating with an AI coding assistant?

These docs are LLM-ready. Point Claude, ChatGPT, Cursor or any coding agent at:

* **`https://developer.eka.care/llms.txt`** — index of all pages in plain text
* **`https://developer.eka.care/llms-full.txt`** — the full documentation in one file

Or grab the ready-made **[CLAUDE.md integration file](/docs/scribe/build-with-ai/claude-md)** — drop it in your project and your coding agent can build the record → transcribe → note flow in one shot.


# MedScribe Alliance Protocol
Source: https://developer.eka.care/docs/scribe/protocol/overview

The open protocol every EkaScribe API is built on

All EkaScribe APIs are built on the **[MedScribe Alliance scribe-emr protocol](https://github.com/MedScribeAlliance/scribe-emr-protocol)** — an open, session-based standard for connecting medical scribe services with EMRs. **EkaScribe is the first medical scribe service to open-source and implement it.**

Why it matters: integrate once against the protocol (no vendor lock-in), a standard session lifecycle everywhere, and self-describing services — [Discovery](/api-sdk/scribe/protocol/discovery) advertises models, formats and languages so clients configure themselves at runtime.

| Protocol concept | EkaScribe API |
| - | - |
| Service discovery | [Discovery](/api-sdk/scribe/protocol/discovery) — public, no auth |
| Session lifecycle | [Sessions](/api-sdk/scribe/sessions/overview) — create → audio → end → poll |
| Structured outputs | [Templates](/api-sdk/scribe/templates/create-template) · [Documents](/api-sdk/scribe/documents/create-update-document) |

Current implementation: **protocol v0.1** (negotiable via the Discovery response's `supported_versions`). Spec and schemas live in the [GitHub repo](https://github.com/MedScribeAlliance/scribe-emr-protocol).


# Quickstart
Source: https://developer.eka.care/docs/scribe/quickstart

From audio to a structured clinical note in five API calls

This guide takes a recorded consultation and returns a structured clinical note. The whole flow is five HTTP calls — no SDK required.

## Prerequisites

**1. Get API credentials**

[Sign up on Eka](https://login.eka.care/workspace/sign-in/?next=https://console.eka.care\&product_type=emr\&signup=user_only\&tab=sign-up), then in the [Developer Console](https://console.eka.care) go to **Manage API Credentials** and create a client. Save the `client_id` and `client_secret` — the secret is shown only once.

**2. Have an audio file ready**

Any consultation or dictation recording in `webm`, `wav`, `mp3`, `m4a`, `mp4` or `ogg`.

## The complete flow

```bash cURL theme={null}
BASE=https://api.eka.care

# 1. Authenticate — exchange credentials for an access token
TOKEN=$(curl -s -X POST $BASE/connect-auth/v1/account/login \
  -H "Content-Type: application/json" \
  -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}' \
  | jq -r .access_token)

# 2. Create a session
SESSION_ID=$(curl -s -X POST $BASE/voice/v1/sessions \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "language_hint": ["en"],
    "model": "pro",
    "templates": ["clinical_notes_template"],
    "upload_type": "single"
  }' | jq -r .session_id)

# 3. Upload the audio file (content type is detected from the extension)
curl -s -X POST "$BASE/voice/v1/sessions/$SESSION_ID/audio/audio_0.webm" \
  -H "Authorization: Bearer $TOKEN" \
  --data-binary @consultation.webm

# 4. End the session — processing starts
curl -s -X POST "$BASE/voice/v1/sessions/$SESSION_ID/end" \
  -H "Authorization: Bearer $TOKEN"

# 5. Poll until done (HTTP 202 = still processing, 200 = completed)
curl -s "$BASE/voice/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $TOKEN"
```

```python Python theme={null}
import requests, time

BASE = "https://api.eka.care"

# 1. Authenticate — exchange credentials for an access token
token = requests.post(f"{BASE}/connect-auth/v1/account/login", json={
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
}).json()["access_token"]
auth = {"Authorization": f"Bearer {token}"}

# 2. Create a session
session = requests.post(f"{BASE}/voice/v1/sessions", headers=auth, json={
    "language_hint": ["en"],
    "model": "pro",
    "templates": ["clinical_notes_template"],
    "upload_type": "single",
}).json()
sid = session["session_id"]

# 3. Upload the audio file (content type is detected from the extension)
with open("consultation.webm", "rb") as f:
    requests.post(
        f"{BASE}/voice/v1/sessions/{sid}/audio/audio_0.webm",
        headers=auth,
        data=f,
    )

# 4. End the session — processing starts
requests.post(f"{BASE}/voice/v1/sessions/{sid}/end", headers=auth)

# 5. Poll until done (HTTP 202 = still processing, 200 = completed)
while True:
    r = requests.get(f"{BASE}/voice/v1/sessions/{sid}", headers=auth)
    if r.status_code != 202:
        break
    time.sleep(1)

result = r.json()
print(result["transcript"])
print(result["templates"])   # structured note per requested template
```

```javascript JavaScript theme={null}
import { readFile } from "node:fs/promises";

const BASE = "https://api.eka.care";

// 1. Authenticate — exchange credentials for an access token
const { access_token } = await fetch(`${BASE}/connect-auth/v1/account/login`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: "YOUR_CLIENT_ID",
    client_secret: "YOUR_CLIENT_SECRET",
  }),
}).then((r) => r.json());
const auth = { Authorization: `Bearer ${access_token}` };

// 2. Create a session
const session = await fetch(`${BASE}/voice/v1/sessions`, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({
    language_hint: ["en"],
    model: "pro",
    templates: ["clinical_notes_template"],
    upload_type: "single",
  }),
}).then((r) => r.json());

// 3. Upload the audio file (content type is detected from the extension)
await fetch(
  `${BASE}/voice/v1/sessions/${session.session_id}/audio/audio_0.webm`,
  {
    method: "POST",
    headers: auth,
    body: await readFile("consultation.webm"),
  }
);

// 4. End the session — processing starts
await fetch(`${BASE}/voice/v1/sessions/${session.session_id}/end`, {
  method: "POST",
  headers: auth,
});

// 5. Poll until done (HTTP 202 = still processing, 200 = completed)
let result;
while (true) {
  const r = await fetch(`${BASE}/voice/v1/sessions/${session.session_id}`, {
    headers: auth,
  });
  if (r.status !== 202) { result = await r.json(); break; }
  await new Promise((s) => setTimeout(s, 1000));
}

console.log(result.transcript);
console.log(result.templates); // structured note per requested template
```

The completed response contains the transcript and one structured document per requested template:

```json theme={null}
{
  "session_id": "ses_abc123def456",
  "status": "completed",
  "transcript": "Patient presents with cough and fever...",
  "templates": [
    {
      "clinical_notes_template": {
        "status": "success",
        "document_id": "doc_abc123",
        "data": { "chief_complaint": "cough and fever", "assessment": "Acute bronchitis" }
      }
    }
  ]
}
```

> [!NOTE]
>
> `upload_type: "single"` sends one complete audio file — **max 10 MB** via the API. For larger recordings, create the session with `upload_type: "chunked"` and upload sequential chunks (`audio_0.webm`, `audio_1.webm`, ...), or use an [SDK](#prefer-an-sdk) which records, chunks and uploads automatically. For live scribing, use `upload_type: "stream"` with the [WebSocket API](/docs/scribe/sessions/stream-audio).

## Next steps

> **[Try it in the browser](/docs/scribe/authenticate-and-try)**
>
> Paste your credentials and call every API from the docs — no code needed.

> **[Create your own template](/api-sdk/scribe/templates/create-template)**
>
> Define your note format in markdown and pass its ID in `templates`.

> **[Explore the Sessions API](/api-sdk/scribe/sessions/overview)**
>
> Discovery, streaming, session updates, webhooks and status codes.

> **[Get notified via webhook](/api-sdk/webhooks/getting-started)**
>
> Skip polling — receive a callback when the note is ready.

## Prefer an SDK?

SDKs handle microphone capture, voice-activity detection, chunking, retries and polling for you:

```ts theme={null}
import { getEkaScribeInstance } from "@eka-care/ekascribe-ts-sdk";

const ekascribe = getEkaScribeInstance({
  access_token: "YOUR_ACCESS_TOKEN",
  env: "PROD",
  flavour: "CLIENT_IDENTIFIER",
  allianceConfig: { baseUrl: "https://api.eka.care/voice/v1" },
});

const start = await ekascribe.startRecordingV2({
  templates: ["clinical_notes_template"],
  sessionMode: "consultation",
  languageHint: ["en"],
});
// ... consultation happens ...
await ekascribe.endRecording();

const result = await ekascribe.getSessionStatus(start.txn_id, {
  poll: { maxAttempts: 60, intervalMs: 2000 },
});
```

Available for [TypeScript](/api-sdk/scribe/sdks/ekascribe-ts-sdk), [Python](/api-sdk/scribe/sdks/scribe-python-sdk), [Java](/api-sdk/scribe/sdks/java-sdk), [Android](/api-sdk/scribe/sdks/android-sdk) and [iOS](/api-sdk/scribe/sdks/ios-sdk).


# Complete FHIR Bundle Example
Source: https://developer.eka.care/docs/scribe/resources/fhir-bundle-example

Full JSON example of the Eka FHIR Bundle

```json theme={null}
{
  "entry": [
    {
      "request": {
        "method": "PUT",
        "url": "AllergyIntolerance/6a0841ca-46bf-5169-ba94-df396b21e999"
      },
      "resource": {
        "id": "6a0841ca-46bf-5169-ba94-df396b21e999",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "mh-53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "asserter": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          "food"
        ],
        "clinicalStatus": {
          "coding": [
            {
              "code": "active",
              "display": "Active",
              "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical"
            }
          ]
        },
        "code": {
          "coding": [
            {
              "code": "locale-45652c55c95428ea51e58155fee07af5",
              "display": "Banana intolerance",
              "system": "https://www.eka.care/local"
            }
          ]
        },
        "criticality": "high",
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-45652c55c95428ea51e58155fee07af5"
          }
        ],
        "note": [
          {
            "text": "Causes itching"
          }
        ],
        "patient": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "recordedDate": "2025-12-12T16:04:14.452266+00:00",
        "type": "allergy",
        "verificationStatus": {
          "coding": [
            {
              "code": "confirmed",
              "display": "Confirmed",
              "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-verification"
            }
          ]
        },
        "resourceType": "AllergyIntolerance"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Appointment/1a6610b4-a69e-57cc-9d0f-3f940c9449a8"
      },
      "resource": {
        "id": "1a6610b4-a69e-57cc-9d0f-3f940c9449a8",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "appointmentType": {
          "coding": [
            {
              "code": "FOLLOWUP",
              "display": "Follow-up",
              "system": "http://terminology.hl7.org/CodeSystem/v2-0276"
            }
          ]
        },
        "created": "2025-12-12T10:34:14.410092+00:00",
        "description": "Follow up advised in 3-5 days after test results are available",
        "end": "2025-12-15T00:00:00+00:00",
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#appointment"
          }
        ],
        "participant": [
          {
            "actor": {
              "display": "dummy_patient",
              "reference": "Patient/dummy_patient_oid"
            },
            "status": "accepted"
          }
        ],
        "start": "2025-12-15T00:00:00+00:00",
        "status": "proposed",
        "resourceType": "Appointment"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Condition/7d38dfba-9bdb-5834-9eee-f8aa545aa5cb"
      },
      "resource": {
        "id": "7d38dfba-9bdb-5834-9eee-f8aa545aa5cb",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "asserter": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "encounter-diagnosis",
                "display": "Encounter Diagnosis",
                "system": "http://terminology.hl7.org/CodeSystem/condition-category"
              }
            ]
          }
        ],
        "clinicalStatus": {
          "coding": [
            {
              "code": "inactive",
              "display": "inactive",
              "system": "http://terminology.hl7.org/CodeSystem/condition-clinical"
            }
          ]
        },
        "code": {
          "coding": [
            {
              "code": "locale-97f95df7ab182ac40f0e48c5d1dfbbbb",
              "display": "Acid reflux",
              "system": "https://www.eka.care"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "evidence": [
          {
            "code": [
              {
                "coding": [
                  {
                    "code": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2",
                    "system": "https://www.eka.care/prescriptions"
                  }
                ]
              }
            ]
          }
        ],
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-97f95df7ab182ac40f0e48c5d1dfbbbb"
          }
        ],
        "note": [
          {
            "text": "Working diagnosis based on symptoms and examination"
          }
        ],
        "recordedDate": "2025-12-12T10:34:14.410092+00:00",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "verificationStatus": {
          "coding": [
            {
              "code": "suspected",
              "display": "suspected",
              "system": "http://terminology.hl7.org/CodeSystem/condition-clinical"
            }
          ]
        },
        "resourceType": "Condition"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Condition/d51b2db3-6060-565b-a918-bd0a4e140c31"
      },
      "resource": {
        "id": "d51b2db3-6060-565b-a918-bd0a4e140c31",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "asserter": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "encounter-diagnosis",
                "display": "Encounter Diagnosis",
                "system": "http://terminology.hl7.org/CodeSystem/condition-category"
              }
            ]
          }
        ],
        "clinicalStatus": {
          "coding": [
            {
              "code": "inactive",
              "display": "inactive",
              "system": "http://terminology.hl7.org/CodeSystem/condition-clinical"
            }
          ]
        },
        "code": {
          "coding": [
            {
              "code": "locale-4ab621252040a372c8667a885de40f6f",
              "display": "Gastritis",
              "system": "https://www.eka.care"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "evidence": [
          {
            "code": [
              {
                "coding": [
                  {
                    "code": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2",
                    "system": "https://www.eka.care/prescriptions"
                  }
                ]
              }
            ]
          }
        ],
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-4ab621252040a372c8667a885de40f6f"
          }
        ],
        "note": [
          {
            "text": "Working diagnosis based on symptoms and examination"
          }
        ],
        "recordedDate": "2025-12-12T10:34:14.410092+00:00",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "verificationStatus": {
          "coding": [
            {
              "code": "suspected",
              "display": "suspected",
              "system": "http://terminology.hl7.org/CodeSystem/condition-clinical"
            }
          ]
        },
        "resourceType": "Condition"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Condition/baa81103-658c-58dc-9986-c4fc1ab220a2"
      },
      "resource": {
        "id": "baa81103-658c-58dc-9986-c4fc1ab220a2",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "asserter": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "encounter-diagnosis",
                "display": "Encounter Diagnosis",
                "system": "http://terminology.hl7.org/CodeSystem/condition-category"
              }
            ]
          }
        ],
        "clinicalStatus": {
          "coding": [
            {
              "code": "inactive",
              "display": "inactive",
              "system": "http://terminology.hl7.org/CodeSystem/condition-clinical"
            }
          ]
        },
        "code": {
          "coding": [
            {
              "code": "locale-308ec5a00860dfcb2af8a5f156506860",
              "display": "Dyspepsia",
              "system": "https://www.eka.care"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "evidence": [
          {
            "code": [
              {
                "coding": [
                  {
                    "code": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2",
                    "system": "https://www.eka.care/prescriptions"
                  }
                ]
              }
            ]
          }
        ],
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-308ec5a00860dfcb2af8a5f156506860"
          }
        ],
        "note": [
          {
            "text": "Working diagnosis based on symptoms and examination, related to intermittent abdominal pain"
          }
        ],
        "recordedDate": "2025-12-12T10:34:14.410092+00:00",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "verificationStatus": {
          "coding": [
            {
              "code": "suspected",
              "display": "suspected",
              "system": "http://terminology.hl7.org/CodeSystem/condition-clinical"
            }
          ]
        },
        "resourceType": "Condition"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Condition/a4dc0582-3010-57e2-b5fc-5530622ba8fa"
      },
      "resource": {
        "id": "a4dc0582-3010-57e2-b5fc-5530622ba8fa",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "asserter": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "problem-list-item",
                "display": "Problem List Item",
                "system": "http://terminology.hl7.org/CodeSystem/condition-category"
              }
            ]
          }
        ],
        "clinicalStatus": {
          "coding": [
            {
              "code": "active",
              "display": "active",
              "system": "http://terminology.hl7.org/CodeSystem/condition-clinical"
            }
          ]
        },
        "code": {
          "coding": [
            {
              "code": "locale-37f54c55ea395e99dae2a324bd47688c",
              "display": "Gastric issue",
              "system": "https://www.eka.care"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "evidence": [
          {
            "code": [
              {
                "coding": [
                  {
                    "code": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2",
                    "system": "https://www.eka.care/prescriptions"
                  }
                ]
              }
            ]
          }
        ],
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-37f54c55ea395e99dae2a324bd47688c"
          }
        ],
        "recordedDate": "2025-12-12T10:34:14.410092+00:00",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "verificationStatus": {
          "coding": [
            {
              "code": "confirmed",
              "display": "confirmed",
              "system": "http://terminology.hl7.org/CodeSystem/condition-clinical"
            }
          ]
        },
        "resourceType": "Condition"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Condition/84261bbe-790c-54bf-ac2a-bc4d9c7439bd"
      },
      "resource": {
        "id": "84261bbe-790c-54bf-ac2a-bc4d9c7439bd",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "asserter": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "problem-list-item",
                "display": "Problem List Item",
                "system": "http://terminology.hl7.org/CodeSystem/condition-category"
              }
            ]
          }
        ],
        "clinicalStatus": {
          "coding": [
            {
              "code": "active",
              "display": "active",
              "system": "http://terminology.hl7.org/CodeSystem/condition-clinical"
            }
          ]
        },
        "code": {
          "coding": [
            {
              "code": "locale-3c47e65837e019511242d1b65943954e",
              "display": "Allergic rhinitis",
              "system": "https://www.eka.care"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "evidence": [
          {
            "code": [
              {
                "coding": [
                  {
                    "code": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2",
                    "system": "https://www.eka.care/prescriptions"
                  }
                ]
              }
            ]
          }
        ],
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-3c47e65837e019511242d1b65943954e"
          }
        ],
        "recordedDate": "2025-12-12T10:34:14.410092+00:00",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "verificationStatus": {
          "coding": [
            {
              "code": "confirmed",
              "display": "confirmed",
              "system": "http://terminology.hl7.org/CodeSystem/condition-clinical"
            }
          ]
        },
        "resourceType": "Condition"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Condition/e49ff164-dc27-5486-b7d8-479e69cec534"
      },
      "resource": {
        "id": "e49ff164-dc27-5486-b7d8-479e69cec534",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "asserter": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "problem-list-item",
                "display": "Problem List Item",
                "system": "http://terminology.hl7.org/CodeSystem/condition-category"
              }
            ]
          }
        ],
        "clinicalStatus": {
          "coding": [
            {
              "code": "inactive",
              "display": "inactive",
              "system": "http://terminology.hl7.org/CodeSystem/condition-clinical"
            }
          ]
        },
        "code": {
          "coding": [
            {
              "code": "locale-4307395708f2c5e132701afcfea5f46f",
              "display": "Migraine",
              "system": "https://www.eka.care"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "evidence": [
          {
            "code": [
              {
                "coding": [
                  {
                    "code": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2",
                    "system": "https://www.eka.care/prescriptions"
                  }
                ]
              }
            ]
          }
        ],
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-4307395708f2c5e132701afcfea5f46f"
          }
        ],
        "note": [
          {
            "text": "Occasional episodes in the past, currently not active"
          }
        ],
        "recordedDate": "2025-12-12T10:34:14.410092+00:00",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "verificationStatus": {
          "coding": [
            {
              "code": "refuted",
              "display": "refuted",
              "system": "http://terminology.hl7.org/CodeSystem/condition-clinical"
            }
          ]
        },
        "resourceType": "Condition"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "CarePlan/3a230b5a-ef2b-5d76-9e18-90f321000e8a"
      },
      "resource": {
        "id": "3a230b5a-ef2b-5d76-9e18-90f321000e8a",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "author": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "386464006",
                "display": "Medical advice",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "created": "2025-12-12T16:04:14.472747+00:00",
        "description": "Follow the medication schedule strictly",
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-42d19e7fdb84acc68a988baaf186ca9f"
          }
        ],
        "intent": "plan",
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "CarePlan"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "CarePlan/54b505c4-52f2-5481-9fe7-60bc90ab40a9"
      },
      "resource": {
        "id": "54b505c4-52f2-5481-9fe7-60bc90ab40a9",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "author": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "386464006",
                "display": "Medical advice",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "created": "2025-12-12T16:04:14.473296+00:00",
        "description": "Complete the recommended tests",
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-4fe34c1270db070636da3398a0f30cb3"
          }
        ],
        "intent": "plan",
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "CarePlan"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "CarePlan/9ef7c35a-f898-5fc2-90b2-431a025ae8e2"
      },
      "resource": {
        "id": "9ef7c35a-f898-5fc2-90b2-431a025ae8e2",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "author": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "386464006",
                "display": "Medical advice",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "created": "2025-12-12T16:04:14.473802+00:00",
        "description": "Avoid known food triggers",
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-0b2381ce17f4ec7f8e58615651b1ffb4"
          }
        ],
        "intent": "plan",
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "CarePlan"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "CarePlan/c26f4429-1671-5920-90ff-23c185f15e54"
      },
      "resource": {
        "id": "c26f4429-1671-5920-90ff-23c185f15e54",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "author": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "386464006",
                "display": "Medical advice",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "created": "2025-12-12T16:04:14.474302+00:00",
        "description": "Monitor symptoms",
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-6b2a6f4cf15428f0a06d5c5ed61db097"
          }
        ],
        "intent": "plan",
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "CarePlan"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "CarePlan/1e84f116-3b97-50b3-9ef6-09a16295203b"
      },
      "resource": {
        "id": "1e84f116-3b97-50b3-9ef6-09a16295203b",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "author": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "386464006",
                "display": "Medical advice",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "created": "2025-12-12T16:04:14.474796+00:00",
        "description": "Avoid spicy and oily food",
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-dabbd37531374f42436a91b6b835cf6d"
          }
        ],
        "intent": "plan",
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "CarePlan"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "CarePlan/bd4b3fd2-7941-5ada-9256-a21ab6a9583f"
      },
      "resource": {
        "id": "bd4b3fd2-7941-5ada-9256-a21ab6a9583f",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "author": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "386464006",
                "display": "Medical advice",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "created": "2025-12-12T16:04:14.475298+00:00",
        "description": "Have early and light dinners",
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-6f9ecff5eaa8bf922b6f69433b298201"
          }
        ],
        "intent": "plan",
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "CarePlan"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "CarePlan/87753a7f-be1a-58ca-af6d-f31aff262a0a"
      },
      "resource": {
        "id": "87753a7f-be1a-58ca-af6d-f31aff262a0a",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "author": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "386464006",
                "display": "Medical advice",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "created": "2025-12-12T16:04:14.475791+00:00",
        "description": "Avoid tea or coffee on an empty stomach",
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-91ecff0e501c7f9f488654b5d16eb09b"
          }
        ],
        "intent": "plan",
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "CarePlan"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "CarePlan/62b3a87e-010a-5bb3-bdf8-8d5834e7620b"
      },
      "resource": {
        "id": "62b3a87e-010a-5bb3-bdf8-8d5834e7620b",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "author": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "386464006",
                "display": "Medical advice",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "created": "2025-12-12T16:04:14.476309+00:00",
        "description": "Drink adequate water",
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-db441d1f6e4785b2b1e16723ad2c3836"
          }
        ],
        "intent": "plan",
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "CarePlan"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "CarePlan/8963b4b5-ddc7-5e10-acb5-8fc75139bc24"
      },
      "resource": {
        "id": "8963b4b5-ddc7-5e10-acb5-8fc75139bc24",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "author": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "386464006",
                "display": "Medical advice",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "created": "2025-12-12T16:04:14.476850+00:00",
        "description": "Manage stress",
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-749454cfdd89100fa35c70d6dbb27956"
          }
        ],
        "intent": "plan",
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "CarePlan"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "CarePlan/43e405f2-cf6a-5e98-b8bf-56441494e3b6"
      },
      "resource": {
        "id": "43e405f2-cf6a-5e98-b8bf-56441494e3b6",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "author": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "386464006",
                "display": "Medical advice",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "created": "2025-12-12T16:04:14.477343+00:00",
        "description": "Get 7-8 hours of sleep",
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-cd08f4f60267c6792d6b8efbdd423bf2"
          }
        ],
        "intent": "plan",
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "CarePlan"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "CarePlan/2c61e7a0-61a1-569c-a0ab-e4d620aaaba1"
      },
      "resource": {
        "id": "2c61e7a0-61a1-569c-a0ab-e4d620aaaba1",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "author": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "386464006",
                "display": "Medical advice",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "created": "2025-12-12T16:04:14.477831+00:00",
        "description": "Avoid banana for now, reintroduce gradually if symptoms settle",
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-4544e3b00dc19d63c2eb90e57c67af33"
          }
        ],
        "intent": "plan",
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "CarePlan"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "CarePlan/1ae0ac1b-5a7a-5578-a50a-e7a71c81ef6e"
      },
      "resource": {
        "id": "1ae0ac1b-5a7a-5578-a50a-e7a71c81ef6e",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "author": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "category": [
          {
            "coding": [
              {
                "code": "371530004",
                "display": "Clinical note",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "created": "2025-12-12T16:04:14.478328+00:00",
        "description": "The patient is advised dietary and lifestyle modifications including avoiding spicy and oily food, having early and light dinners, avoiding tea or coffee on an empty stomach, drinking adequate water, managing stress, getting 7-8 hours of sleep, and working properly. The patient is also advised to avoid banana for now due to mild allergies and reintroduce gradually if symptoms settle. Fasting for 8 to 10 hours is required for imaging tests. No known red flag symptoms at present.",
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#b3e20a60-9a63-4db0-98bf-d2047f4d7643"
          }
        ],
        "intent": "proposal",
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "CarePlan"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "ServiceRequest/46a3c331-dc6e-5371-9a61-7747654b4379"
      },
      "resource": {
        "id": "46a3c331-dc6e-5371-9a61-7747654b4379",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "authoredOn": "2025-12-12T10:34:14.410092+00:00",
        "category": [
          {
            "coding": [
              {
                "code": "108252007",
                "display": "Laboratory procedure",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "code": "locale-e53edc51a4a40d10ae24cce03b46e3a0",
              "display": "Complete blood count",
              "system": "https://www.eka.care/local"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-e53edc51a4a40d10ae24cce03b46e3a0"
          }
        ],
        "intent": "order",
        "note": [
          {
            "text": "To rule out infection"
          }
        ],
        "requester": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "ServiceRequest"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "ServiceRequest/bed2f3a8-2a10-5fb8-baeb-611674d697a5"
      },
      "resource": {
        "id": "bed2f3a8-2a10-5fb8-baeb-611674d697a5",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "authoredOn": "2025-12-12T10:34:14.410092+00:00",
        "category": [
          {
            "coding": [
              {
                "code": "108252007",
                "display": "Laboratory procedure",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "code": "locale-b1594238c0f99d3191650dc0e14d3a32",
              "display": "Fasting blood sugar",
              "system": "https://www.eka.care/local"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-b1594238c0f99d3191650dc0e14d3a32"
          }
        ],
        "intent": "order",
        "note": [
          {
            "text": "To rule out sugar imbalance"
          }
        ],
        "requester": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "ServiceRequest"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "ServiceRequest/fbcc5bc7-b79c-567c-8598-21e927ba67ef"
      },
      "resource": {
        "id": "fbcc5bc7-b79c-567c-8598-21e927ba67ef",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "authoredOn": "2025-12-12T10:34:14.410092+00:00",
        "category": [
          {
            "coding": [
              {
                "code": "108252007",
                "display": "Laboratory procedure",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "code": "locale-adecb0c53f640a31ed2c1ea3e67ff02e",
              "display": "Liver function test",
              "system": "https://www.eka.care/local"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-adecb0c53f640a31ed2c1ea3e67ff02e"
          }
        ],
        "intent": "order",
        "note": [
          {
            "text": "To rule out liver related issues"
          }
        ],
        "requester": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "ServiceRequest"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "ServiceRequest/579b1c10-6c6c-5b55-963a-707bd53e9c5e"
      },
      "resource": {
        "id": "579b1c10-6c6c-5b55-963a-707bd53e9c5e",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "authoredOn": "2025-12-12T10:34:14.410092+00:00",
        "category": [
          {
            "coding": [
              {
                "code": "108252007",
                "display": "Laboratory procedure",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "code": "locale-487b7e9702affe76e2a3c1bdff7b06b4",
              "display": "Urine routine and microscopy",
              "system": "https://www.eka.care/local"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-487b7e9702affe76e2a3c1bdff7b06b4"
          }
        ],
        "intent": "order",
        "requester": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "ServiceRequest"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "ServiceRequest/bb9e687e-9f67-5088-b071-bf13bea65208"
      },
      "resource": {
        "id": "bb9e687e-9f67-5088-b071-bf13bea65208",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "authoredOn": "2025-12-12T10:34:14.410092+00:00",
        "category": [
          {
            "coding": [
              {
                "code": "363679005",
                "display": "Imaging",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "code": "locale-3fed2664e046e71b0a5619610a2d302b",
              "display": "Chest X-ray PA view",
              "system": "https://www.eka.care/local"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-3fed2664e046e71b0a5619610a2d302b"
          }
        ],
        "intent": "order",
        "requester": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "ServiceRequest"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "ServiceRequest/0ac5af5a-38d0-5bcb-b3da-7dd3cafcfccb"
      },
      "resource": {
        "id": "0ac5af5a-38d0-5bcb-b3da-7dd3cafcfccb",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "authoredOn": "2025-12-12T10:34:14.410092+00:00",
        "category": [
          {
            "coding": [
              {
                "code": "363679005",
                "display": "Imaging",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "code": "locale-66fd7fb2a1ae6c2e0d989200d0aa27fb",
              "display": "Ultrasound of abdomen and pelvis",
              "system": "https://www.eka.care/local"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-66fd7fb2a1ae6c2e0d989200d0aa27fb"
          }
        ],
        "intent": "order",
        "note": [
          {
            "text": "To assess the abdominal organs and evaluate the cause of discomfort"
          }
        ],
        "requester": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "ServiceRequest"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "ServiceRequest/08d590cc-cc16-5f79-959f-8c20e79b4046"
      },
      "resource": {
        "id": "08d590cc-cc16-5f79-959f-8c20e79b4046",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "authoredOn": "2025-12-12T10:34:14.410092+00:00",
        "category": [
          {
            "coding": [
              {
                "code": "387713003",
                "display": "Surgical procedure",
                "system": "http://snomed.info/sct"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "code": "locale-7adcac021efc5fe6525924f9213709e4",
              "display": "Diagnostic endoscopy",
              "system": "https://www.eka.care/local"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-7adcac021efc5fe6525924f9213709e4"
          }
        ],
        "intent": "order",
        "requester": {
          "display": "dummy doctor",
          "reference": "Practitioner/"
        },
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "ServiceRequest"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Observation/788869c9-bdc5-5b2a-9ff3-8dcf3e4206d1"
      },
      "resource": {
        "id": "788869c9-bdc5-5b2a-9ff3-8dcf3e4206d1",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "category": [
          {
            "coding": [
              {
                "code": "symptom",
                "display": "symptom",
                "system": "https://www.custom.code"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "code": "locale-f8a79ef309a886ba94602ec9429dd5b1",
              "display": "Abdominal pain",
              "system": "https://www.eka.care"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-f8a79ef309a886ba94602ec9429dd5b1"
          }
        ],
        "note": [
          {
            "text": "Intermittent"
          }
        ],
        "performer": [
          {
            "display": "dummy doctor",
            "reference": "Practitioner/"
          }
        ],
        "status": "preliminary",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "Observation"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Observation/f795b0e4-4de5-5e87-ba17-c1eb6070a19d"
      },
      "resource": {
        "id": "f795b0e4-4de5-5e87-ba17-c1eb6070a19d",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "category": [
          {
            "coding": [
              {
                "code": "symptom",
                "display": "symptom",
                "system": "https://www.custom.code"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "code": "locale-d8ac2007dfc6d117ded6a46e77603358",
              "display": "Burning sensation",
              "system": "https://www.eka.care"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-d8ac2007dfc6d117ded6a46e77603358"
          }
        ],
        "note": [
          {
            "text": "In the upper abdomen"
          }
        ],
        "performer": [
          {
            "display": "dummy doctor",
            "reference": "Practitioner/"
          }
        ],
        "status": "preliminary",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "Observation"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Observation/a846136a-f3a7-57e6-bb18-7e852ee4ab2e"
      },
      "resource": {
        "id": "a846136a-f3a7-57e6-bb18-7e852ee4ab2e",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "category": [
          {
            "coding": [
              {
                "code": "symptom",
                "display": "symptom",
                "system": "https://www.custom.code"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "code": "locale-c82b6bd3c496e89f5da5ccbe73fa11c1",
              "display": "Sour taste",
              "system": "https://www.eka.care"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-c82b6bd3c496e89f5da5ccbe73fa11c1"
          }
        ],
        "note": [
          {
            "text": "Early morning"
          }
        ],
        "performer": [
          {
            "display": "dummy doctor",
            "reference": "Practitioner/"
          }
        ],
        "status": "preliminary",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "Observation"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Observation/a9abe391-4555-529b-86ec-f6f5b266d30f"
      },
      "resource": {
        "id": "a9abe391-4555-529b-86ec-f6f5b266d30f",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "category": [
          {
            "coding": [
              {
                "code": "symptom",
                "display": "symptom",
                "system": "https://www.custom.code"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "code": "locale-380f43098d377b1705af989748de525f",
              "display": "Headache",
              "system": "https://www.eka.care"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-380f43098d377b1705af989748de525f"
          }
        ],
        "note": [
          {
            "text": "Occasional"
          }
        ],
        "performer": [
          {
            "display": "dummy doctor",
            "reference": "Practitioner/"
          }
        ],
        "status": "preliminary",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "Observation"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Observation/b2fe71a2-dfad-5169-ac59-413688daa446"
      },
      "resource": {
        "id": "b2fe71a2-dfad-5169-ac59-413688daa446",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "category": [
          {
            "coding": [
              {
                "code": "symptom",
                "display": "symptom",
                "system": "https://www.custom.code"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "code": "locale-83dbceb6d763ebb17cc387eccf42d052",
              "display": "Nasal congestion",
              "system": "https://www.eka.care"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-83dbceb6d763ebb17cc387eccf42d052"
          }
        ],
        "note": [
          {
            "text": "Slightly present"
          }
        ],
        "performer": [
          {
            "display": "dummy doctor",
            "reference": "Practitioner/"
          }
        ],
        "status": "preliminary",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "Observation"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Observation/c2154b8d-3304-5243-b72d-34e777e2c6d8"
      },
      "resource": {
        "id": "c2154b8d-3304-5243-b72d-34e777e2c6d8",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "category": [
          {
            "coding": [
              {
                "code": "symptom",
                "display": "symptom",
                "system": "https://www.custom.code"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "code": "locale-a9df378813d31194b7d07d81646dd4c2",
              "display": "Bloating",
              "system": "https://www.eka.care"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-a9df378813d31194b7d07d81646dd4c2"
          }
        ],
        "note": [
          {
            "text": "After meal"
          }
        ],
        "performer": [
          {
            "display": "dummy doctor",
            "reference": "Practitioner/"
          }
        ],
        "status": "preliminary",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "Observation"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Observation/c24a52f6-da61-5d81-a7c4-68ce793c3356"
      },
      "resource": {
        "id": "c24a52f6-da61-5d81-a7c4-68ce793c3356",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "category": [
          {
            "coding": [
              {
                "code": "vital-signs",
                "display": "Vital Signs",
                "system": "http://terminology.hl7.org/CodeSystem/observation-category"
              }
            ],
            "text": "Vital Signs"
          }
        ],
        "code": {
          "coding": [
            {
              "code": "v-1365277675",
              "display": "Blood pressure",
              "system": "https://www.custom.code/technical"
            }
          ]
        },
        "component": [
          {
            "code": {
              "coding": [
                {
                  "code": "lb-8296133834",
                  "display": "Diastolic Blood Pressure",
                  "system": "https://www.custom.code/technical"
                },
                {
                  "code": "75367002",
                  "display": "Diastolic Blood Pressure",
                  "system": "http://snomed.info/sct"
                }
              ]
            },
            "valueQuantity": {
              "code": "lu-736638821",
              "system": "https://www.eka.care/mdb/technical",
              "unit": "mmHg",
              "value": 128
            }
          },
          {
            "code": {
              "coding": [
                {
                  "code": "lb-9242267093",
                  "display": "Systolic Blood Pressure",
                  "system": "https://www.custom.code/technical"
                },
                {
                  "code": "75367002",
                  "display": "Systolic Blood Pressure",
                  "system": "http://snomed.info/sct"
                }
              ]
            },
            "valueQuantity": {
              "code": "lu-736638821",
              "system": "https://www.eka.care/mdb/technical",
              "unit": "mmHg",
              "value": 84
            }
          }
        ],
        "effectiveDateTime": "2025-12-12T10:34:14.410092+00:00",
        "encounter": {
          "reference": "Encounter/53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#v-1365277675"
          }
        ],
        "performer": [
          {
            "display": "dummy doctor",
            "reference": "Practitioner/"
          }
        ],
        "status": "final",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "Observation"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Observation/d92330a9-ff09-5542-a9e7-a41d70b26aa4"
      },
      "resource": {
        "id": "d92330a9-ff09-5542-a9e7-a41d70b26aa4",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "category": [
          {
            "coding": [
              {
                "code": "vital-signs",
                "display": "Vital Signs",
                "system": "http://terminology.hl7.org/CodeSystem/observation-category"
              }
            ],
            "text": "Vital Signs"
          }
        ],
        "code": {
          "coding": [
            {
              "code": "lb-1201285132",
              "display": "Pulse rate",
              "system": "https://www.custom.code/technical"
            },
            {
              "code": "78564009",
              "display": "Pulse rate",
              "system": "http://snomed.info/sct"
            }
          ]
        },
        "effectiveDateTime": "2025-12-12T10:34:14.410092+00:00",
        "encounter": {
          "reference": "Encounter/53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#lb-1201285132"
          }
        ],
        "performer": [
          {
            "display": "dummy doctor",
            "reference": "Practitioner/"
          }
        ],
        "status": "final",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "valueQuantity": {
          "system": "https://www.eka.care/mdb/technical",
          "unit": "bpm",
          "value": 82.0
        },
        "resourceType": "Observation"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Observation/c101b5ef-333d-538b-bd60-cdbd23b3f708"
      },
      "resource": {
        "id": "c101b5ef-333d-538b-bd60-cdbd23b3f708",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "category": [
          {
            "coding": [
              {
                "code": "vital-signs",
                "display": "Vital Signs",
                "system": "http://terminology.hl7.org/CodeSystem/observation-category"
              }
            ],
            "text": "Vital Signs"
          }
        ],
        "code": {
          "coding": [
            {
              "code": "lb-199711567",
              "display": "Temperature",
              "system": "https://www.custom.code/technical"
            },
            {
              "code": "386725007",
              "display": "Temperature",
              "system": "http://snomed.info/sct"
            }
          ]
        },
        "effectiveDateTime": "2025-12-12T10:34:14.410092+00:00",
        "encounter": {
          "reference": "Encounter/53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#lb-199711567"
          }
        ],
        "performer": [
          {
            "display": "dummy doctor",
            "reference": "Practitioner/"
          }
        ],
        "status": "final",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "valueQuantity": {
          "system": "https://www.eka.care/mdb/technical",
          "unit": "°F",
          "value": 98.4
        },
        "resourceType": "Observation"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Observation/6a73a85d-f99e-57e0-aae1-7cdd3a2e4864"
      },
      "resource": {
        "id": "6a73a85d-f99e-57e0-aae1-7cdd3a2e4864",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "category": [
          {
            "coding": [
              {
                "code": "vital-signs",
                "display": "Vital Signs",
                "system": "http://terminology.hl7.org/CodeSystem/observation-category"
              }
            ],
            "text": "Vital Signs"
          }
        ],
        "code": {
          "coding": [
            {
              "code": "lb-1771358750",
              "display": "Oxygen saturation",
              "system": "https://www.custom.code/technical"
            }
          ]
        },
        "effectiveDateTime": "2025-12-12T10:34:14.410092+00:00",
        "encounter": {
          "reference": "Encounter/53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#lb-1771358750"
          }
        ],
        "performer": [
          {
            "display": "dummy doctor",
            "reference": "Practitioner/"
          }
        ],
        "status": "final",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "valueQuantity": {
          "system": "https://www.eka.care/mdb/technical",
          "unit": "%",
          "value": 98.0
        },
        "resourceType": "Observation"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Observation/b2ac8bfa-f26c-516f-b8b1-3f1badac1362"
      },
      "resource": {
        "id": "b2ac8bfa-f26c-516f-b8b1-3f1badac1362",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "category": [
          {
            "coding": [
              {
                "code": "exam",
                "display": "exam",
                "system": "http://terminology.hl7.org/CodeSystem/observation-category"
              }
            ],
            "text": "exam"
          }
        ],
        "code": {
          "coding": [
            {
              "code": "locale-10cc52cdcf768e0de5c5cb8f2c7c392c",
              "display": "Abdominal examination",
              "system": "https://www.eka.care"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-10cc52cdcf768e0de5c5cb8f2c7c392c"
          }
        ],
        "performer": [
          {
            "display": "dummy doctor",
            "reference": "Practitioner/"
          }
        ],
        "status": "final",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "Observation"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Observation/a98e36a8-231c-5033-a77b-5c1b0601d84c"
      },
      "resource": {
        "id": "a98e36a8-231c-5033-a77b-5c1b0601d84c",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "category": [
          {
            "coding": [
              {
                "code": "exam",
                "display": "exam",
                "system": "http://terminology.hl7.org/CodeSystem/observation-category"
              }
            ],
            "text": "exam"
          }
        ],
        "code": {
          "coding": [
            {
              "code": "locale-a203eeec31398c30560cda36f182c1e9",
              "display": "Nasal examination",
              "system": "https://www.eka.care"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-a203eeec31398c30560cda36f182c1e9"
          }
        ],
        "performer": [
          {
            "display": "dummy doctor",
            "reference": "Practitioner/"
          }
        ],
        "status": "final",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "Observation"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "Observation/70fa9d39-88f8-55a0-a440-220f791c0a21"
      },
      "resource": {
        "id": "70fa9d39-88f8-55a0-a440-220f791c0a21",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "category": [
          {
            "coding": [
              {
                "code": "exam",
                "display": "exam",
                "system": "http://terminology.hl7.org/CodeSystem/observation-category"
              }
            ],
            "text": "exam"
          }
        ],
        "code": {
          "coding": [
            {
              "code": "locale-ff872e79afb817c097203685d3f3010e",
              "display": "Systematic examination",
              "system": "https://www.eka.care"
            }
          ]
        },
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-ff872e79afb817c097203685d3f3010e"
          }
        ],
        "performer": [
          {
            "display": "dummy doctor",
            "reference": "Practitioner/"
          }
        ],
        "status": "final",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "Observation"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "MedicationRequest/71747c56-19dc-58e5-ab73-bb45b37f0a44"
      },
      "resource": {
        "id": "71747c56-19dc-58e5-ab73-bb45b37f0a44",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "authoredOn": "2025-12-12T10:34:14.410000+00:00",
        "dispenseRequest": {
          "quantity": {
            "system": "https://www.eka.care/mdb",
            "unit": "tablet",
            "value": 10
          }
        },
        "dosageInstruction": [
          {
            "additionalInstruction": [
              {
                "coding": [
                  {
                    "display": "1-0-0",
                    "system": "https://www.eka.care/"
                  }
                ]
              }
            ],
            "doseAndRate": [
              {
                "doseQuantity": {
                  "system": "https://www.eka.care/mdb",
                  "unit": "tablet",
                  "value": 1
                },
                "type": {
                  "coding": [
                    {
                      "code": "ordered",
                      "display": "Ordered",
                      "system": "http://terminology.hl7.org/CodeSystem/dose-rate-type"
                    }
                  ]
                }
              }
            ],
            "text": "To reduce stomach acid",
            "timing": {
              "code": {
                "coding": [
                  {
                    "display": "on empty stomach",
                    "system": "https://www.eka.care/"
                  }
                ]
              },
              "repeat": {
                "duration": 10,
                "durationUnit": "d",
                "frequency": 1,
                "period": 1,
                "periodUnit": "d",
                "when": [
                  "MORN"
                ]
              }
            }
          }
        ],
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "use": "official",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-34e44334caaf5b59d3330526f322661b"
          }
        ],
        "intent": "order",
        "medicationCodeableConcept": {
          "coding": [
            {
              "code": "locale-34e44334caaf5b59d3330526f322661b",
              "display": "Pantoprazole 40 mg",
              "system": "https://www.eka.care/mdb"
            }
          ]
        },
        "requester": {
          "display": "dummy doctor",
          "reference": "Practitioner/None"
        },
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "MedicationRequest"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "MedicationRequest/1f8fcdc1-e658-5530-a120-b19965076740"
      },
      "resource": {
        "id": "1f8fcdc1-e658-5530-a120-b19965076740",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "authoredOn": "2025-12-12T10:34:14.410000+00:00",
        "dispenseRequest": {
          "quantity": {
            "system": "https://www.eka.care/mdb",
            "unit": "tablet",
            "value": 10
          }
        },
        "dosageInstruction": [
          {
            "additionalInstruction": [
              {
                "coding": [
                  {
                    "display": "0-1-1",
                    "system": "https://www.eka.care/"
                  }
                ]
              }
            ],
            "doseAndRate": [
              {
                "doseQuantity": {
                  "system": "https://www.eka.care/mdb",
                  "unit": "tablet",
                  "value": 1
                },
                "type": {
                  "coding": [
                    {
                      "code": "ordered",
                      "display": "Ordered",
                      "system": "http://terminology.hl7.org/CodeSystem/dose-rate-type"
                    }
                  ]
                }
              }
            ],
            "text": "For abdominal cramps",
            "timing": {
              "code": {
                "coding": [
                  {
                    "code": "tpr1$ta5",
                    "display": "after meal",
                    "system": "https://www.eka.care/"
                  }
                ]
              },
              "repeat": {
                "duration": 5,
                "durationUnit": "d",
                "frequency": 2,
                "period": 1,
                "periodUnit": "d",
                "when": [
                  "AFT",
                  "NIGHT"
                ]
              }
            }
          }
        ],
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "use": "official",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-36c66e1c0745cce3d9d00b24e90a3cef"
          }
        ],
        "intent": "order",
        "medicationCodeableConcept": {
          "coding": [
            {
              "code": "locale-36c66e1c0745cce3d9d00b24e90a3cef",
              "display": "Dicyclomine 10 mg",
              "system": "https://www.eka.care/mdb"
            }
          ]
        },
        "requester": {
          "display": "dummy doctor",
          "reference": "Practitioner/None"
        },
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "MedicationRequest"
      }
    },
    {
      "request": {
        "method": "PUT",
        "url": "MedicationRequest/fa49c610-f4d3-519e-89e2-1814ee6f1f72"
      },
      "resource": {
        "id": "fa49c610-f4d3-519e-89e2-1814ee6f1f72",
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "authoredOn": "2025-12-12T10:34:14.410000+00:00",
        "dispenseRequest": {
          "quantity": {
            "system": "https://www.eka.care/mdb",
            "unit": "ml",
            "value": 140
          }
        },
        "dosageInstruction": [
          {
            "additionalInstruction": [
              {
                "coding": [
                  {
                    "display": "0-1-1",
                    "system": "https://www.eka.care/"
                  }
                ]
              }
            ],
            "doseAndRate": [
              {
                "doseQuantity": {
                  "system": "https://www.eka.care/mdb",
                  "unit": "ml",
                  "value": 10
                },
                "type": {
                  "coding": [
                    {
                      "code": "ordered",
                      "display": "Ordered",
                      "system": "http://terminology.hl7.org/CodeSystem/dose-rate-type"
                    }
                  ]
                }
              }
            ],
            "text": "For quick relief from burning and acidity",
            "timing": {
              "code": {
                "coding": [
                  {
                    "code": "tpr1$ta5",
                    "display": "after meal",
                    "system": "https://www.eka.care/"
                  }
                ]
              },
              "repeat": {
                "duration": 7,
                "durationUnit": "d",
                "frequency": 2,
                "period": 1,
                "periodUnit": "d",
                "when": [
                  "AFT",
                  "NIGHT"
                ]
              }
            }
          }
        ],
        "encounter": {
          "reference": "Encounter/edfad957-7379-5416-a97c-45982d9cb531"
        },
        "identifier": [
          {
            "system": "https://www.eka.care",
            "use": "official",
            "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2#locale-7547a072463fc3e549f4a6f85f5acfbb"
          }
        ],
        "intent": "order",
        "medicationCodeableConcept": {
          "coding": [
            {
              "code": "locale-7547a072463fc3e549f4a6f85f5acfbb",
              "display": "Antacid syrup",
              "system": "https://www.eka.care/mdb"
            }
          ]
        },
        "requester": {
          "display": "dummy doctor",
          "reference": "Practitioner/None"
        },
        "status": "active",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "resourceType": "MedicationRequest"
      }
    },
    {
      "request": {
        "method": "POST",
        "url": "Composition"
      },
      "resource": {
        "extension": [
          {
            "url": "https://www.eka.care/care_context_id",
            "valueString": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
          }
        ],
        "author": [
          {
            "display": "dummy doctor",
            "reference": "Practitioner/"
          }
        ],
        "date": "2025-12-12T10:34:14.410092+00:00",
        "identifier": {
          "system": "https://www.eka.care",
          "value": "53c5592a-9e86-4dfs53aabcdda--vicky-12-dec-test-2"
        },
        "section": [
          {
            "entry": [
              {
                "reference": "AllergyIntolerance/6a0841ca-46bf-5169-ba94-df396b21e999"
              }
            ],
            "title": "AllergyIntolerance"
          },
          {
            "entry": [
              {
                "reference": "Appointment/1a6610b4-a69e-57cc-9d0f-3f940c9449a8"
              }
            ],
            "title": "Appointment"
          },
          {
            "entry": [
              {
                "reference": "Condition/7d38dfba-9bdb-5834-9eee-f8aa545aa5cb"
              },
              {
                "reference": "Condition/d51b2db3-6060-565b-a918-bd0a4e140c31"
              },
              {
                "reference": "Condition/baa81103-658c-58dc-9986-c4fc1ab220a2"
              },
              {
                "reference": "Condition/a4dc0582-3010-57e2-b5fc-5530622ba8fa"
              },
              {
                "reference": "Condition/84261bbe-790c-54bf-ac2a-bc4d9c7439bd"
              },
              {
                "reference": "Condition/e49ff164-dc27-5486-b7d8-479e69cec534"
              }
            ],
            "title": "Condition"
          },
          {
            "entry": [
              {
                "reference": "CarePlan/3a230b5a-ef2b-5d76-9e18-90f321000e8a"
              },
              {
                "reference": "CarePlan/54b505c4-52f2-5481-9fe7-60bc90ab40a9"
              },
              {
                "reference": "CarePlan/9ef7c35a-f898-5fc2-90b2-431a025ae8e2"
              },
              {
                "reference": "CarePlan/c26f4429-1671-5920-90ff-23c185f15e54"
              },
              {
                "reference": "CarePlan/1e84f116-3b97-50b3-9ef6-09a16295203b"
              },
              {
                "reference": "CarePlan/bd4b3fd2-7941-5ada-9256-a21ab6a9583f"
              },
              {
                "reference": "CarePlan/87753a7f-be1a-58ca-af6d-f31aff262a0a"
              },
              {
                "reference": "CarePlan/62b3a87e-010a-5bb3-bdf8-8d5834e7620b"
              },
              {
                "reference": "CarePlan/8963b4b5-ddc7-5e10-acb5-8fc75139bc24"
              },
              {
                "reference": "CarePlan/43e405f2-cf6a-5e98-b8bf-56441494e3b6"
              },
              {
                "reference": "CarePlan/2c61e7a0-61a1-569c-a0ab-e4d620aaaba1"
              },
              {
                "reference": "CarePlan/1ae0ac1b-5a7a-5578-a50a-e7a71c81ef6e"
              }
            ],
            "title": "CarePlan"
          },
          {
            "entry": [
              {
                "reference": "ServiceRequest/46a3c331-dc6e-5371-9a61-7747654b4379"
              },
              {
                "reference": "ServiceRequest/bed2f3a8-2a10-5fb8-baeb-611674d697a5"
              },
              {
                "reference": "ServiceRequest/fbcc5bc7-b79c-567c-8598-21e927ba67ef"
              },
              {
                "reference": "ServiceRequest/579b1c10-6c6c-5b55-963a-707bd53e9c5e"
              },
              {
                "reference": "ServiceRequest/bb9e687e-9f67-5088-b071-bf13bea65208"
              },
              {
                "reference": "ServiceRequest/0ac5af5a-38d0-5bcb-b3da-7dd3cafcfccb"
              },
              {
                "reference": "ServiceRequest/08d590cc-cc16-5f79-959f-8c20e79b4046"
              }
            ],
            "title": "ServiceRequest"
          },
          {
            "entry": [
              {
                "reference": "Observation/788869c9-bdc5-5b2a-9ff3-8dcf3e4206d1"
              },
              {
                "reference": "Observation/f795b0e4-4de5-5e87-ba17-c1eb6070a19d"
              },
              {
                "reference": "Observation/a846136a-f3a7-57e6-bb18-7e852ee4ab2e"
              },
              {
                "reference": "Observation/a9abe391-4555-529b-86ec-f6f5b266d30f"
              },
              {
                "reference": "Observation/b2fe71a2-dfad-5169-ac59-413688daa446"
              },
              {
                "reference": "Observation/c2154b8d-3304-5243-b72d-34e777e2c6d8"
              },
              {
                "reference": "Observation/c24a52f6-da61-5d81-a7c4-68ce793c3356"
              },
              {
                "reference": "Observation/d92330a9-ff09-5542-a9e7-a41d70b26aa4"
              },
              {
                "reference": "Observation/c101b5ef-333d-538b-bd60-cdbd23b3f708"
              },
              {
                "reference": "Observation/6a73a85d-f99e-57e0-aae1-7cdd3a2e4864"
              },
              {
                "reference": "Observation/b2ac8bfa-f26c-516f-b8b1-3f1badac1362"
              },
              {
                "reference": "Observation/a98e36a8-231c-5033-a77b-5c1b0601d84c"
              },
              {
                "reference": "Observation/70fa9d39-88f8-55a0-a440-220f791c0a21"
              }
            ],
            "title": "Observation"
          },
          {
            "entry": [
              {
                "reference": "MedicationRequest/71747c56-19dc-58e5-ab73-bb45b37f0a44"
              },
              {
                "reference": "MedicationRequest/1f8fcdc1-e658-5530-a120-b19965076740"
              },
              {
                "reference": "MedicationRequest/fa49c610-f4d3-519e-89e2-1814ee6f1f72"
              }
            ],
            "title": "MedicationRequest"
          }
        ],
        "status": "preliminary",
        "subject": {
          "display": "dummy_patient",
          "reference": "Patient/dummy_patient_oid"
        },
        "title": "Prescription",
        "type": {
          "coding": [
            {
              "code": "440545006",
              "display": "Prescription record",
              "system": "http://snomed.info/sct"
            }
          ]
        },
        "resourceType": "Composition"
      }
    }
  ],
  "type": "batch",
  "resourceType": "Bundle"
}
```


# Eka FHIR Structure
Source: https://developer.eka.care/docs/scribe/resources/fhir-structure

FHIR resource mappings for Eka Care medical data

# Eka FHIR Resource Mappings

This document provides the FHIR (Fast Healthcare Interoperability Resources) mappings used by Eka Care for structured medical data. Each section details how Eka properties map to standard FHIR resources.

***

## Symptoms

**FHIR Resource:** `Observation`

Symptoms observed during patient consultations are stored using the FHIR Observation resource.

| Eka Property | FHIR Resource | FHIR Link | Decision to Use |
| - | - | - | - |
| symptoms.name, code | Observation.code | [Manifestation or Symptom](https://www.hl7.org/fhir/valueset-manifestation-or-symptom.html) | SNOMED, Eka codes |
| symptoms.category | Observation.category | [Observation Category](https://terminology.hl7.org/5.1.0/CodeSystem-observation-category.html) | SNOMED: 418799008, MDB: s-8068301606 |
| symptoms.status | Observation.status | [Observation Status](https://www.hl7.org/fhir/valueset-observation-status.html) | Voice2RX: `preliminary`, Rx: `final` |
| symptoms.since | Observation.effective | - | effectiveDateTime \| effectivePeriod |
| symptom.notes | Observation.note | [Annotation](https://www.hl7.org/fhir/datatypes.html#Annotation) | String text |
| symptom.is-recorded-for | Observation.subject | - | Patient Reference |
| symptoms.severity | Observation.value | [CodeableConcept](https://www.hl7.org/fhir/datatypes.html#CodeableConcept) | ValueCodeableConcept |
| symptoms.laterality | Observation.bodySite | [Body Site](https://www.hl7.org/fhir/valueset-body-site.html#expansion) | CodeableConcept.coding.code |

***

## Conditions / Diagnoses

**FHIR Resource:** `Condition`

Medical conditions and diagnoses are stored using the FHIR Condition resource.

| Eka Property | FHIR Resource | FHIR Link | Decision to Use |
| - | - | - | - |
| condition.name, code | Condition.code | - | SNOMED |
| condition.current\_status | Condition.clinicalStatus | [Condition Clinical](https://build.fhir.org/valueset-condition-clinical.html) | Ruled-out: `inactive`, Confirmed: `active`, Suspected: `unknown` |
| condition.verification | Condition.verificationStatus | [Verification Status](https://build.fhir.org/valueset-condition-ver-status.html) | Ruled-out: `refuted`, Confirmed: `confirmed`, Suspected: `unconfirmed` |
| condition.severity | Condition.severity | [Condition Severity](https://build.fhir.org/valueset-condition-severity.html) | SNOMED: 24484000 (severe), 6736007 (moderate), 255604002 (mild) |
| condition.category | Condition.category | [Condition Category](https://build.fhir.org/valueset-condition-category.html) | FHIR: `encounter-diagnosis` |
| condition.since | Condition.onset | - | datetime \| period \| age \| string |
| condition.is-recorded-for | Condition.subject | - | Patient |
| condition.first-time-on | Condition.recordedDate | - | - |
| condition.evidence | Condition.evidence | - | Evidence pointing to condition |
| condition.where | Condition.bodyStructure | - | Has bodysite + other details |
| condition.stage | Condition.stage | - | e.g., cancer stages |
| condition.notes | Condition.note | - | Strings |
| condition.laterality | Condition.bodySite | [Body Site](https://www.hl7.org/fhir/valueset-body-site.html#expansion) | CodeableConcept.coding.code |

***

## Medical History

**FHIR Resource:** `Condition`

Past medical history is also stored using the FHIR Condition resource with different category.

| Eka Property | FHIR Resource | FHIR Link | Decision to Use |
| - | - | - | - |
| condition.name, code | Condition.code | - | SNOMED |
| condition.current\_status | Condition.clinicalStatus | [Condition Clinical](https://build.fhir.org/valueset-condition-clinical.html) | Ruled-out: `inactive`, Confirmed: `active`, Suspected: `unknown` |
| condition.verification | Condition.verificationStatus | [Verification Status](https://build.fhir.org/valueset-condition-ver-status.html) | Ruled-out: `refuted`, Confirmed: `confirmed`, Suspected: `unconfirmed` |
| condition.severity | Condition.severity | [Condition Severity](https://build.fhir.org/valueset-condition-severity.html) | SNOMED codes for severity |
| condition.category | Condition.category | [Condition Category](https://build.fhir.org/valueset-condition-category.html) | `problem-list-item` |
| condition.since | Condition.onset | - | datetime \| period \| age \| string |
| condition.is-recorded-for | Condition.subject | - | Patient |
| condition.first-time-on | Condition.recordedDate | - | - |
| condition.stage | Condition.stage | - | e.g., cancer stages |
| condition.notes | Condition.note | - | Strings |

***

## Advices

**FHIR Resource:** `CarePlan`

Doctor's advice to patients is stored using the FHIR CarePlan resource.

| Eka Property | FHIR Resource | FHIR Link | Decision to Use |
| - | - | - | - |
| advice.status | CarePlan.status | - | `active` |
| advice.intent | CarePlan.intent | [Care Plan Intent](https://build.fhir.org/valueset-care-plan-intent.html) | `plan` |
| advice.category | CarePlan.category | - | Custom: SNOMED for advice |
| advice.for | CarePlan.subject | - | Patient |
| advice.details | CarePlan.activity.performedActivity | [CodeableReference](https://build.fhir.org/references.html#CodeableReference) | CodeableReference.concept.text |
| advice.details | CarePlan.description | [CarePlan Description](https://build.fhir.org/careplan-definitions.html#CarePlan.description) | - |

***

## Notes

**FHIR Resource:** `CarePlan`

Clinical notes are stored using the FHIR CarePlan resource with different intent.

| Eka Property | FHIR Resource | FHIR Link | Decision to Use |
| - | - | - | - |
| notes.status | CarePlan.status | - | `active` |
| notes.intent | CarePlan.intent | [Care Plan Intent](https://build.fhir.org/valueset-care-plan-intent.html) | `proposal` |
| notes.category | CarePlan.category | - | Custom: for notes |
| notes.for | CarePlan.subject | - | Patient |
| notes.details | CarePlan.description | [CodeableReference](https://build.fhir.org/references.html#CodeableReference) | CodeableReference.concept.text |

***

## Examinations

**FHIR Resource:** `Observation`

Physical examination findings are stored using the FHIR Observation resource.

| Eka Property | FHIR Resource | FHIR Link | Decision to Use |
| - | - | - | - |
| exam.name, code | Observation.code | [Manifestation or Symptom](https://www.hl7.org/fhir/valueset-manifestation-or-symptom.html) | SNOMED, Eka codes |
| exam.category | Observation.category | [Observation Category](https://terminology.hl7.org/5.1.0/CodeSystem-observation-category.html) | `exam` |
| exam.status | Observation.status | [Observation Status](https://www.hl7.org/fhir/valueset-observation-status.html) | `preliminary` \| `final` \| `unknown` |
| exam.since | Observation.effective | - | effectiveDateTime \| effectivePeriod |
| exam.notes | Observation.note | [Annotation](https://www.hl7.org/fhir/datatypes.html#Annotation) | String |
| exam.is-recorded-for | Observation.subject | - | Patient |
| exam.location | Observation.bodySite | [Body Site](https://www.hl7.org/fhir/valueset-body-site.html#expansion) | - |

***

## Follow-Up

**FHIR Resource:** `Appointment`

Follow-up appointments suggested by doctors are stored using the FHIR Appointment resource.

| Eka Property | FHIR Resource | FHIR Link | Decision to Use |
| - | - | - | - |
| followup.status | Appointment.status | [Appointment Status](https://build.fhir.org/valueset-appointmentstatus.html) | `proposed` |
| followup.type | Appointment.appointmentType | [Appointment Type](https://terminology.hl7.org/6.0.2/ValueSet-v2-0276.html) | `FOLLOWUP` |
| followup.created | Appointment.created | - | - |
| followup.start | Appointment.start | - | Instant |

***

## Family History

**FHIR Resource:** `FamilyMemberHistory`

Family medical history is stored using the FHIR FamilyMemberHistory resource.

| Eka Property | FHIR Resource | FHIR Link | Decision to Use |
| - | - | - | - |
| dataentry.status | FamilyMemberHistory.status | [History Status](https://build.fhir.org/valueset-history-status.html) | `completed` |
| relation | FamilyMemberHistory.relationship | [Family Member](https://terminology.hl7.org/6.0.2/ValueSet-v3-FamilyMember.html) | - |
| relative.name | FamilyMemberHistory.name | - | String |
| remarks | FamilyMemberHistory.note | - | - |
| clinical.status | FamilyMemberHistory.condition.outcome | - | CodeableConcept.coding.code |

***

## Vitals ( Trackers )

**FHIR Resource:** `Observation`

Patient vitals and health trackers are stored using the FHIR Observation resource.

| Eka Property | FHIR Resource | FHIR Link | Decision to Use |
| - | - | - | - |
| vitals.name, code | Observation.code | [Manifestation or Symptom](https://www.hl7.org/fhir/valueset-manifestation-or-symptom.html) | SNOMED, Eka codes |
| vitals.category | Observation.category | [Observation Category](https://terminology.hl7.org/5.1.0/CodeSystem-observation-category.html) | SNOMED: s-8068301606, FHIR: `vital-signs` |
| vitals.status | Observation.status | [Observation Status](https://www.hl7.org/fhir/valueset-observation-status.html) | Voice2RX: `preliminary`, Rx: `final` |
| vitals.since | Observation.effective | - | effectiveDateTime \| effectivePeriod |
| vitals.notes | Observation.note | [Annotation](https://www.hl7.org/fhir/datatypes.html#Annotation) | String text |
| vitals.value | Observation.value | [CodeableConcept](https://www.hl7.org/fhir/datatypes.html#CodeableConcept) | ValueCodeableConcept |
| vitals.components | Observation.component | - | For vitals like BP with multiple values |

***

## Medications

**FHIR Resource:** `MedicationRequest`

Medication prescriptions are stored using the FHIR MedicationRequest resource.

| Eka Property | FHIR Resource | FHIR Link | Decision to Use |
| - | - | - | - |
| medication.name, medication.id | MedicationRequest.medicationCodeableConcept | [Medication Codes](https://www.hl7.org/fhir/valueset-medication-codes.html) | Name : Ibuprofen 200mg; code: MDB/SNOMED |
| medication.status | MedicationRequest.status | [MedicationRequest Status](https://www.hl7.org/fhir/valueset-medicationrequest-status.html) | `active` |
| medication.intent | MedicationRequest.intent | [MedicationRequest Intent](https://www.hl7.org/fhir/valueset-medicationrequest-intent.html) | `order` |
| patient.id, patient.profile.personal.name | MedicationRequest.subject | [Reference](https://www.hl7.org/fhir/references.html) | Patient reference |
| doctor.id, doctor.profile.personal.name | MedicationRequest.requester | [Reference](https://www.hl7.org/fhir/references.html) | Practitioner reference |
| date | MedicationRequest.authoredOn | [dateTime](https://www.hl7.org/fhir/datatypes.html#dateTime) | ISO 8601 format |
| medication.instruction | MedicationRequest.dosageInstruction.text | [Dosage](https://www.hl7.org/fhir/dosage.html) | String |
| medication.dose.value, dose.unit, dose.id, dose.custom | MedicationRequest.dosageInstruction.doseAndRate.doseQuantity | [Quantity](https://www.hl7.org/fhir/datatypes.html#Quantity) | value, unit, code |
| medication.dose-rate-type | MedicationRequest.dosageInstruction.doseAndRate.type | [Dose Rate Type](https://www.hl7.org/fhir/valueset-dose-rate-type.html) | `ordered` |
| medication.frequency.id, frequency.value, frequency.custom | MedicationRequest.dosageInstruction.additionalInstruction | [Additional Instruction](https://www.hl7.org/fhir/valueset-additional-instruction-codes.html) | CodeableConcept |
| medication.frequency.frequency, frequency.period, frequency.period\_unit, duration, duration-unit, when | MedicationRequest.dosageInstruction.timing.repeat | [Timing](https://www.hl7.org/fhir/datatypes.html#Timing) | frequency, period, periodUnit |
| calculated | MedicationRequest.dispenseRequest.quantity | [Quantity](https://www.hl7.org/fhir/datatypes.html#Quantity) | frequency × duration × dose |

***

## Lab Tests / Imaging / Surgical Procedures

**FHIR Resource:** `ServiceRequest`

Lab tests, imaging requests ( radiology) and surgical procedure are stored using the FHIR ServiceRequest resource.

| Eka Property | FHIR Resource | FHIR Link | Decision to Use |
| - | - | - | - |
| status | ServiceRequest.status | [Request Status](https://www.hl7.org/fhir/valueset-request-status.html) | `active` |
| intent | ServiceRequest.intent | [Request Intent](https://www.hl7.org/fhir/valueset-request-intent.html) | `order` |
| category | ServiceRequest.category | [Service Request Category](https://www.hl7.org/fhir/valueset-servicerequest-category.html) | Supported categories are imaging, lab\_test, surgical\_procedure |
| labTests.id, labTests.name | ServiceRequest.code | [Procedure Codes](https://www.hl7.org/fhir/valueset-procedure-code.html) | CodeableConcept from `http://eka.care/mdb`, `http://loinc.org`, `https://parchi.eka.care/local` |
| patient\_oid, patient\_name | ServiceRequest.subject | [Reference](https://www.hl7.org/fhir/references.html) | Reference to Patient resource |
| visitid | ServiceRequest.encounter | [Reference](https://www.hl7.org/fhir/references.html) | Reference to Encounter resource |
| doctor\_oid, doctor\_name | ServiceRequest.requester | [Reference](https://www.hl7.org/fhir/references.html) | Reference to Practitioner resource |
| date | ServiceRequest.authoredOn | [dateTime](https://www.hl7.org/fhir/datatypes.html#dateTime) | ISO 8601 format |
| remark/notes | ServiceRequest.note | [Annotation](https://www.hl7.org/fhir/datatypes.html#Annotation) | Text note |

***

## DrugAllergy / FoodAllergy Intolerance

**FHIR Resource:** `AllergyIntolerance`

Food and medication allergies are stored using the FHIR AllergyIntolerance resource.

| Eka Property | FHIR Resource | FHIR Link | Decision to Use |
| - | - | - | - |
| doctor\_oid, doctor\_name | AllergyIntolerance.asserter | [Reference](https://www.hl7.org/fhir/references.html) | Reference to Practitioner resource |
| category | AllergyIntolerance.category | [Allergy Category](https://www.hl7.org/fhir/valueset-allergy-intolerance-category.html) | `food` or `medication` |
| clinicalStatus | AllergyIntolerance.clinicalStatus | [Clinical Status](https://www.hl7.org/fhir/valueset-allergyintolerance-clinical.html) | code: `active`, display: `Active` |
| drugAllergy.id, foodOtherAllergy.id | AllergyIntolerance.code | [Allergy Codes](https://www.hl7.org/fhir/valueset-allergyintolerance-code.html) | CodeableConcept from `http://snomed.info/sct`, `http://eka.care/mdb`, `https://parchi.eka.care/local` |
| criticality | AllergyIntolerance.criticality | [Allergy Criticality](https://www.hl7.org/fhir/valueset-allergy-intolerance-criticality.html) | `high` |
| notes | AllergyIntolerance.note | [Annotation](https://www.hl7.org/fhir/datatypes.html#Annotation) | Text note |
| patient\_oid, patient\_name | AllergyIntolerance.patient | [Reference](https://www.hl7.org/fhir/references.html) | Reference to Patient resource |
| type | AllergyIntolerance.type | [Allergy Type](https://www.hl7.org/fhir/valueset-allergy-intolerance-type.html) | `allergy` |
| recordedDate | AllergyIntolerance.recordedDate | [dateTime](https://www.hl7.org/fhir/datatypes.html#dateTime) | ISO 8601 format (current time) |
| verificationStatus | AllergyIntolerance.verificationStatus | [Verification Status](https://www.hl7.org/fhir/valueset-allergyintolerance-verification.html) | code: `confirmed`, display: `Confirmed` |

***

# Summary Table

| Data Type | FHIR Resource | Category/Type |
| - | - | - |
| Symptoms | Observation | signs-and-symptoms |
| Conditions/Diagnoses | Condition | encounter-diagnosis |
| Medical History | Condition | problem-list-item |
| Advices | CarePlan | intent: plan |
| Notes | CarePlan | intent: proposal |
| Examinations | Observation | exam |
| Follow-Up | Appointment | FOLLOWUP |
| Family History | FamilyMemberHistory | - |
| Vitals | Observation | vital-signs |
| Medications | MedicationRequest | intent: order |
| Lab Tests/Imaging/Surgical Procedures | ServiceRequest | imaging/lab\_test/surgical\_procedure |
| Food and drug Allergies | AllergyIntolerance | food/medication |

***

## Complete FHIR Bundle Example

> **View Complete FHIR Bundle JSON**
>
> Click here to view the full 3000+ line JSON example of a comprehensive FHIR Bundle including all mapped resources. (Opens in new tab)

[Open](/docs/scribe/resources/fhir-bundle-example)


# IP Allowlisting for Clients
Source: https://developer.eka.care/docs/scribe/resources/ip-allowlisting

Allowlisting and endpoint information for Eka Scribe APIs & Audio transcription

Ensure your network/firewall is configured to allow inbound connections from the below URLs for seamless integration with Eka Scribe & audio transcription APIs.

## Production

* **Allowed URLs:**
  * `*.eka.care`

## Staging

* **Allowed URLs:**
  * `*.dev.eka.care`

## S3 Bucket URLs

### Production

```
https://m-prod-voice-record.s3.ap-south-1.amazonaws.com
https://m-prod-voice2rx-batch.s3.ap-south-1.amazonaws.com
https://m-prod-ekascribe-batch.s3.amazonaws.com
```

### Staging

```
https://m-dev-voice-record.s3.ap-south-1.amazonaws.com
https://m-dev-voice2rx-batch.s3.ap-south-1.amazonaws.com
```

***

> eka.care is hosted on AWS Cloudfront, Make sure you have allowlisted [AWS CloudFront IP Addresses.](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/LocationsOfEdgeServers.html)


# Local Development with HTTPS (ngrok)
Source: https://developer.eka.care/docs/scribe/resources/local-development-ngrok

Give your local server a public HTTPS URL for testing with production APIs.

Production APIs require a secure (HTTPS) origin — requests from `http://localhost` will fail CORS preflight checks. ngrok solves this by tunneling your local server through a public HTTPS URL in seconds.

***

## Step 1 — Install ngrok

**macOS**

```bash theme={null}
brew install ngrok/ngrok/ngrok
```

**Windows (Chocolatey)**

```powershell theme={null}
choco install ngrok
```

**Windows (Scoop)**

```powershell theme={null}
scoop install ngrok
```

**Windows (manual)**

Download the `.zip` from [ngrok.com/download](https://ngrok.com/download), extract `ngrok.exe`, and add its folder to your PATH.

***

## Step 2 — Get your Auth Token

1. Go to [ngrok.com](https://ngrok.com) and sign up (free)
2. After login, go to **Dashboard → Your Authtoken**
3. Copy the token — it looks like `2abc123XYZ_abcdefghijklmnop`

***

## Step 3 — Add the token (one-time only)

```bash theme={null}
ngrok config add-authtoken YOUR_TOKEN_HERE
```

You only need to do this once per machine.

***

## Step 4 — Start your app, then run ngrok

Start your local server first, then in a **second terminal**:

```bash theme={null}
ngrok http <YOUR_APP_PORT>
```

Replace `<YOUR_APP_PORT>` with the port your app runs on (e.g. `3000`, `8000`, `8080`).

ngrok will show output like:

```
Forwarding   https://xxxx-xx-xx-xx.ngrok-free.app -> http://localhost:<YOUR_APP_PORT>
```

Open that `https://` URL in any browser, on any device — it works and satisfies CORS requirements for production APIs.

***

## Stop ngrok

Press `Ctrl+C` in the ngrok terminal.


# System Requirements for Extension
Source: https://developer.eka.care/docs/scribe/resources/system-requirements



Before integrating EkaScribe, ensure your system meets the following requirements:

#### Platform Requirements

* **Google Chrome (Web)**: Version 100+
* **Android App**: Android OS version 10+
* **iOS App**: iOS version 14+

#### Network Requirements

* **Internet Speed**: Minimum 1 Mbps (recommended: 5+ Mbps)

#### Hardware Requirements

* **Microphone/Audio Capture Device**: Required

> **Note**: EkaScribe uses audio from doctor-patient interactions. Using a quality external microphone improves audio quality and transcription accuracy.

***


# Stream Audio (WebSocket)
Source: https://developer.eka.care/docs/scribe/sessions/stream-audio

Real-time audio streaming for upload_type: stream

Sessions created with `upload_type: stream` return a **`wss://` URL** as `upload_url`. Connect and stream — the server auto-detects the wire format from your first frame.

**Option A — raw binary:** send 16-bit LE, mono, 16 kHz PCM as binary frames.

```js theme={null}
const ws = new WebSocket(uploadUrl);
ws.binaryType = "arraybuffer";
ws.onopen = () => ws.send(pcmChunk);
```

**Option B — JSON envelope** (Twilio/Vobiz Media Streams compatible), base64 PCM payloads:

```json theme={null}
{ "event": "start", "start": { "mediaFormat": { "encoding": "audio/x-l16", "sampleRate": 16000 } } }
{ "event": "media", "media": { "payload": "<base64 PCM>" } }
{ "event": "stop" }
```

**To finish:** close the socket (flushes audio), then call [End Session](/api-sdk/scribe/sessions/end-session) — closing alone does **not** start processing. Then poll [Get Session](/api-sdk/scribe/sessions/get-session).


# Overview
Source: https://developer.eka.care/docs/uhi/blood-bank/getting-started



Users can search for **available blood banks** using multiple criteria such as **State**, **District**, **Blood Group**, and **Blood Component**.
Alternatively, users can search **nearby blood banks** by providing their **GPS location** and desired **search radius**.

This feature enables individuals, hospitals, or organizations to quickly locate and contact the nearest blood bank with the required blood component, reducing search time in critical situations.

### Search by Location & Blood Details

The user can search by selecting their **State** and **District**, and specifying the **Blood Group** and **Blood Component**.
The system will return a list of matching blood banks along with availability details.

### Search by GPS & Radius

The user can search by **current location** or manually entered GPS coordinates, along with a search radius (e.g., 5 km, 10 km).
The system will return the nearest blood banks within the given radius.

**1. Search by State & District**

Use the [Get State/District Wise Blood Banks](/api-reference/user-app/bloodbank/state-district-search) API
to retrieve a list of blood banks by providing State, District, Blood Group, and Blood Component.

**2. Search by GPS & Radius**

Use the [Get GPS Wise Blood Banks](/api-reference/user-app/bloodbank/gps-search) API
to retrieve a list of nearby blood banks by providing GPS coordinates, search radius, Blood Group, and Blood Component.

### API Response

The API response includes:

* **Blood Bank Name**
* **Address & Contact Information**
* **Blood Group & Component Availability**
* **Distance (if GPS search)**
* **Last Updated Timestamp**

> &#x20;Availability data is updated periodically. Users should verify with the blood bank before making a visit.


# Build with AI
Source: https://developer.eka.care/docs/uhi/build-with-ai

Set up a coding agent to build with UHI: the reference skill.

Use the reference skill to have a coding assistant build your UHI integration. It hands the assistant the same facts as these docs.

> [!NOTE]
>
> Check what the assistant writes against these docs, and test it in the sandbox before it reaches a patient.

> **[Reference skill](#install-the-skill)**
>
> Every operation, its hosts, auth and headers, in one install.

## Before you start

Three things have to be in place before anything on this page works.

| What you need | Why |
| - | - |
| A coding assistant | Claude Code, Cursor, Codex or ChatGPT. Any one is enough. Pick one and stay on it. |
| A paid plan on it | Free tiers stop partway through a long task. |
| Your own project open in it | The assistant reads and writes the folder it is opened in. Open the repository you are building in first. |

Then work down this page in order: install the skill, connect the MCP server where there is one, and ask for one flow at a time in plain language. Read what the assistant writes before you run it.

## Install the skill

The `eka-uhi` skill carries the hosts, auth and headers, and every UHI operation, each with a link to its page here. It is built from these docs, so it changes when they do.

In Claude Code:

```bash theme={null}
/plugin marketplace add eka-care/eka-docs
/plugin install eka-uhi@eka-docs
```

In Cursor, Codex or another agent, copy the [skill folder](https://github.com/eka-care/eka-docs/tree/main/plugins/eka-uhi/skills/eka-uhi) into the folder your agent loads skills from. Its map is [`SKILL.md`](https://raw.githubusercontent.com/eka-care/eka-docs/main/plugins/eka-uhi/skills/eka-uhi/SKILL.md).

## Read these docs as an agent

Every page here is also plain text an agent can read.

* [`llms.txt`](https://developer.eka.care/llms.txt) is a map of every page.
* [`llms-full.txt`](https://developer.eka.care/llms-full.txt) is every page's text in one file.
* The menu at the top of each page copies it as Markdown, or opens it in Claude or ChatGPT.


# Book an in-person doctor visit over UHI
Source: https://developer.eka.care/docs/uhi/journeys/uhi-book-physical-consultation

A consumer health app finds a doctor on the Unified Health Interface, books a physical consultation slot for its user, and tracks the booking to the visit.

## In short

* The app searches UHI for doctors, fetches a doctor's open slots and books one for the patient.
* The patient accepts the quote and the provider's terms before the app confirms.
* The provider returns a PIN that the patient shows at the clinic.
* The app keeps the booking's reference to check status, reschedule or cancel later.

## Who and when

A consumer health app, such as a Personal Health Record (PHR) app, used by a patient who wants to see a doctor in person. The patient opens the app and asks for a doctor by speciality, name, facility or location. The app searches doctors across the Unified Health Interface (UHI), not only one hospital's own list, and books the visit on the patient's behalf.

**Already in place:** your app acts as a UHI consumer app on Eka. The patient has an ABHA and is logged in on your app. That means you hold Eka's id for the patient ([Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha)). Your server can receive Eka webhooks.

## What they want

"Find a doctor near me who can see me this week, book a slot, and tell me what to show at the clinic."

## The steps

1. The patient describes who they want to see. That can be a speciality, a doctor's name, a hospital, a district or pincode, or their current location with a radius. They choose the days they are free.
2. The app searches UHI for doctors who match and shows the list: name, qualifications, languages, years of experience, facility and address. → workflow: [Book a physical consultation over UHI](/docs/uhi/workflows/uhi-book-consultation)
3. The patient picks a doctor. The app fetches that doctor's open slots for the chosen window, with the price of each. → same workflow
4. The patient picks a slot and gives billing details. The app starts the booking and shows the quote, the price breakup and the provider's terms. → same workflow
5. The patient accepts the terms. The app confirms the booking. The provider returns a PIN that the patient shows to the doctor before the consultation. → same workflow
6. Before the visit, the app checks the booking's status and shows it to the patient. → same workflow
7. The patient goes to the clinic, shows the PIN, and sees the doctor. This is a human step.

## What they have at the end

The patient has a confirmed in-person appointment with a named doctor at a named facility, at a known start and end time. They hold the PIN to show at the clinic. Your app holds the booking's reference, the provider's identifier and the transaction's identifier, so it can check status, reschedule or cancel later.

## Branches

* **No doctor matches the search.** The patient widens the search: a larger radius, another speciality, or a wider time window. → same workflow, search step
* **The doctor has no open slot in the window.** The patient picks another window or another doctor. → same workflow, slot search step
* **The patient wants another time.** The app moves the booking to a new slot. → same workflow, update step
* **The patient cannot go.** The app cancels the booking and confirms the cancellation. → same workflow, cancel step
* **The patient changes their mind before confirming.** They leave after seeing the quote and terms.&#x20;
* **The patient also needs blood.** Separately from booking, the same app can offer a related UHI search. It finds blood banks that hold a blood group and component. This is not a step of the booking. → workflow: [Search blood banks over UHI](/docs/uhi/workflows/blood-bank-search)


# Pay an open bill by scanning the counter QR
Source: https://developer.eka.care/docs/uhi/journeys/uhi-scan-and-pay

A patient at a facility's billing counter scans its QR code with a PHR app, picks an open bill and pays it from their phone.

## In short

* The patient scans the counter QR, and your app shares their ABHA profile with the facility.
* The facility returns the patient's open orders, and the patient picks what to pay.
* Your app receives a payment link, and the patient pays on it.
* Your app then fetches the transaction details and shows a receipt link.

## Who and when

A patient standing at the billing or registration counter of a hospital, clinic or lab. They have a bill to settle: a consultation, a test, a procedure. The counter shows a QR code for the facility. Rather than queue to pay, the patient scans the QR with a Personal Health Record (PHR) app built on Eka, and pays from their phone.

**Already in place:** your app is a PHR app. The patient has an ABHA and is logged in on your app. That means you hold Eka's id for the patient ([Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha)). The facility is a Health Information Provider (HIP) on ABDM and displays a Scan and Pay QR at the counter.

## What they want

"Let me pay this bill from my phone without waiting in line, and give me a receipt."

## The steps

1. The patient scans the QR code at the counter with your app. The QR carries the facility's HIP ID and the counter ID.
2. Your app shares the patient's ABHA profile with the facility and asks for the patient's open orders. → workflow: [Pay an open order with Scan and Pay](/docs/uhi/workflows/scan-and-pay)
3. The facility returns the unpaid orders for this patient, grouped by category with each service and its amount. Your app shows them. → same workflow
4. The patient selects what they want to pay for. Your app sends the selection and receives a payment link with the amount due. → same workflow
5. The patient pays on the payment link. This is a human step on the payment page.
6. Your app fetches the transaction details and shows the payment status and a receipt link. → same workflow

## What they have at the end

The selected bill is paid. The patient holds a receipt link and a transaction id for the payment. The transaction details tie the payment to the patient's ABHA address and the facility's order number.

## Branches

* **The patient has no open order at this facility.** The open order list comes back empty, and the patient pays at the counter as usual. → same workflow, open order step
* **The facility does not answer, or answers with an error.** The request ends in an error, with an error code and message. → same workflow, "When it fails"
* **The payment fails or the patient abandons the payment page.** The transaction details show a status other than paid.  → same workflow, transaction details step
* **The patient is not logged in on your app.** Log them in first. → workflow: [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha)


# Overview
Source: https://developer.eka.care/docs/uhi/scan-and-pay/getting-started



This guide explains how developers can implement the **Scan & Pay** feature using the available APIs. The workflow enables a patient to scan a facility QR code, share their details, select an open order, view payment details, and complete the payment.

> **Note:** Each API response will include a unique `request_id` — you must supply that same `request_id` in your subsequent GET calls to retrieve the corresponding order or payment information.

### Scan & Pay API Workflow

**1. Share Patient Details**

Use the relevant API to share the patient's ABHA profile or identifier with the health facility after scanning the QR code. This step registers or identifies the patient in the facility's system.

**2. Select Open Order**

Retrieve the list of open orders or pending bills for the patient using the facility's API. Allow the patient to select the order they wish to pay for.

**3. Get Payment Details**

Fetch the payment details for the selected order, including the total amount due and a breakdown of charges, using the appropriate API endpoint.

**4. Make Payment**

Initiate the payment process by calling the payment API with the order and patient details. Handle the payment response and display confirmation to the user upon success.


# Search blood banks over UHI
Source: https://developer.eka.care/docs/uhi/workflows/blood-bank-search

Find blood banks that hold a blood group and component, by state and district or by location and radius.

## In short

* Search blood banks over UHI by state and district, or by a location and radius.
* Keep `request_id` from Search Blood Banks and pass it to Get Blood Banks.
* Tell the user to check with the blood bank before they visit.

## When to use this

Your user needs a blood group and component, and wants to know which blood banks hold it. You search across blood banks on the Unified Health Interface (UHI) by state and district, or by a location and a radius around it. Availability is updated periodically, so tell the user to check with the blood bank before they visit.

## Before you start

* A Bearer token. Both operations use the `authApiKey` scheme. See [Authorization](/api-sdk/auth/getting-started).
* The blood group and blood component the user needs.
* Either the state and district, or the user's latitude, longitude and a search radius.
* The patient headers, if your integration sends them.&#x20;

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  App->>Eka: POST /abdm/uhi/v1/blood-bank/search
  App->>Eka: GET /abdm/uhi/v1/blood-bank/search/{request_id}
```

## Steps

**1. Start the search**

Send `search_type`, `blood_group` and `blood_component` to [Search Blood Banks](/api-sdk/uhi/blood-bank/state-district). All three are required. For a district search, also send `state` and `district`. For a location search, send `search_type` `location`, `location` with `lat` and `long`, and `radius` with `value` and `unit`, for example `km`.

Keep `request_id` from the response. `status` is `SUCCESS` or `FAILURE`; on `FAILURE`, check the request.

**2. Read the results**

Call [Get Blood Banks](/api-sdk/uhi/blood-bank/get-blood-banks) with `request_id`. The response carries `status` and `data`, which holds `context`, `message.catalog` with the matching blood banks, and `error_code` if the search failed. Show each blood bank's name, contact details and availability.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `request_id` | Search Blood Banks | Until the results are read | Get Blood Banks |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Both operations return `GenericError` with `code`, `error` and `source_error` on a 4XX or 5XX. A failure in the search itself comes back in `data.error_code` with `code` and `message`. See [Errors](/docs/hie-cm/errors).

| Situation | Code | Do |
| - | - | - |
| Missing `search_type`, `blood_group` or `blood_component` | 4XX | Fix the request |
| District search without `state` or `district`, or location search without `location` or `radius` | 4XX | Send the fields for that search type |
| Search not accepted | `status` `FAILURE` | |
| Unknown `request_id` | | Start a new search |
| No blood bank matches | | Widen the radius or try a neighbouring district |
| Upstream unavailable | 5XX | Retry later |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

* [ ] District search with a test state, district, blood group and component; receive `request_id` and `SUCCESS`
* [ ] Get Blood Banks with that `request_id`; results list at least one blood bank
* [ ] Location search with a test latitude, longitude and a 10 km radius
* [ ] Failure: a search without `blood_group` returns a 4XX


# Pay an open order with Scan and Pay
Source: https://developer.eka.care/docs/uhi/workflows/scan-and-pay

Share the patient's profile from a facility QR code, fetch their open orders, get a payment link for the selected ones, and read the transaction result.

## In short

* Share the profile, list open orders, get a payment link, then read the payment result.
* Each `POST` returns a `request_id`; poll the matching `GET` with it, since no webhook is documented.
* The patient pays on `payment_url`; no Scan and Pay operation takes the payment.

## When to use this

The patient has scanned a facility's Scan and Pay QR code in your Personal Health Record (PHR) app and wants to pay an open bill. This workflow:

* shares the patient's profile with the facility
* lists their open orders
* gets a payment link for the ones they select
* reads the payment result.

Each `POST` returns a `request_id` and a `status` at once. You pass that `request_id` to the matching `GET` to read the result. No webhook is documented for Scan and Pay, so you poll.

## Before you start

* A Bearer token. Every Scan and Pay operation uses the `authApiKey` scheme. See [Authorization](/api-sdk/auth/getting-started).
* The patient logged in on your app, with their Eka user id (`oid`) to send as `X-Pt-Id`. See [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha).&#x20;
* The `hip_id` and `counter_id` read from the facility's QR code.&#x20;

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant Patient as Patient on payment page
  App->>Eka: POST /abdm/v1/profile/scan-and-pay/open-order
  App->>Eka: GET /abdm/v1/profile/scan-and-pay/open-order/{request_id}
  App->>Eka: POST /abdm/v1/profile/scan-and-pay/patient-select
  App->>Eka: GET /abdm/v1/profile/scan-and-pay/patient-select/{request_id}
  App-->>Patient: open payment_url
  App->>Eka: GET /abdm/v1/profile/scan-and-pay/transaction-details/{request_id}
```

## Steps

All five operations return a `status` from the same list: `REQUESTED_OPEN_ORDER`, `PROCESSING_OPEN_ORDER`, `REQUESTED_PATIENT_SELECT`, `PROCESSING_PATIENT_SELECT`, `PROCESSING_PATIENT_NOTIFY`, `REQUESTING_PATIENT_NOTIFY` and `ERROR`.

**1. Share the profile and request open orders**

Send `hip_id` and `counter_id` from the QR code to [Open Orders](/api-sdk/uhi/scan-and-pay/open-orders). This shares the patient's profile with the facility. Keep `request_id` from the response. `status` is `REQUESTED_OPEN_ORDER`.

**2. Read the open orders**

Call [Get Open Orders](/api-sdk/uhi/scan-and-pay/get-open-orders) with `request_id`. When the facility has answered, `data` carries `abha_address`, `intent` and `procedures`. Each procedure has a `category` and `services`, each with `serviceId`, `name`, `description` and `amount`.

If `status` is `ERROR`, read `data.error.code` and `data.error.message`. If `procedures` is empty, the patient has nothing to pay here. The patient selects what to pay.

**3. Select the orders to pay**

Send `request_id` from step 1, `intent` set to `PAYMENT_ORDER`, and the selected `procedures` to [Patient Select](/api-sdk/uhi/scan-and-pay/patient-select). All three are required. The spec describes this call as returning the payment link for the selected order. Keep `request_id` from the response.

**4. Read the payment link**

Call [Get Patient Select Details](/api-sdk/uhi/scan-and-pay/get-patient-select) with `request_id`. `data.payment_bundle` carries `payment_url`, `amount`, `order_number`, `merchant_id`, `payment_mode` and `description`. Show `amount` and open `payment_url` for the patient. The patient pays on that page; no Scan and Pay operation takes the payment.

**5. Read the transaction details**

Call [Get Transaction Details](/api-sdk/uhi/scan-and-pay/get-transaction-details) with `request_id`. `data` carries `status`, `transactionId`, `orderNumber`, `paymentDate`, `paymentReceiptLink`, `abhaAddress` and `openOrderRequestId`. Show the status and the receipt link to the patient.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `oid` | ABHA login | On the patient record | `X-Pt-Id` header on every call |
| `hip_id`, `counter_id` | Facility QR code | Until the payment completes | Open Orders |
| `request_id` | Open Orders | Until the transaction details are final | Get Open Orders, Patient Select, and possibly Get Transaction Details |
| `request_id` | Patient Select | Until the transaction details are final | Get Patient Select Details |
| `order_number`, `amount` | Get Patient Select Details | With the payment record | Matching the payment to the facility's order |
| `transactionId`, `paymentReceiptLink` | Get Transaction Details | With the payment record | Showing the receipt later |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Every operation returns `GenericError` with `code`, `error` and `source_error` on a 4XX or 5XX. A failure inside the facility's answer comes back as `status` `ERROR` with `data.error`. See [Errors](/docs/hie-cm/errors).

| Situation | Code | Do |
| - | - | - |
| Missing `hip_id` or `counter_id`, or an unreadable QR | 4XX | Ask the patient to scan again |
| Unknown or invalid `request_id` | `ABDM-1030` (expected, not confirmed) | Restart from Open Orders |
| Facility does not answer | `ABDM-1028` or `ABDM-1401` (expected, not confirmed) | Tell the patient to pay at the counter |
| Facility answers with an error | `status` `ERROR`, `data.error.code` | Show `data.error.message`; pay at the counter |
| Payment fails or is abandoned | Transaction details `data.status` | |
| Rate limit | `ABDM-1022` (expected, not confirmed) | |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

* [ ] Open Orders with a test `hip_id` and `counter_id`; receive a `request_id` and `REQUESTED_OPEN_ORDER`
* [ ] Get Open Orders until `procedures` is returned
* [ ] Patient Select with one procedure and `PAYMENT_ORDER`; Get Patient Select Details returns `payment_url`
* [ ] Complete the payment on `payment_url` with sandbox payment details&#x20;
* [ ] Get Transaction Details returns a `transactionId` and `paymentReceiptLink`
* [ ] Failure: Get Open Orders with an unknown `request_id`
* [ ] Failure: a `counter_id` with no open orders returns empty `procedures`


# Book a physical consultation over UHI
Source: https://developer.eka.care/docs/uhi/workflows/uhi-book-consultation

Search doctors on the Unified Health Interface, pick a slot, initiate and confirm the booking, then track, reschedule or cancel it.

## In short

* Book an in-person visit in four calls: search doctors, search slots, Init, Confirm.
* Each `POST` returns at once; its result arrives on a webhook or the matching `GET`.
* Show the patient the `pin` from Confirm; they present it to the doctor.
* Check, reschedule or cancel the booking later with its `order_id`.

## When to use this

Your user wants to see a doctor in person and you book the visit for them over the Unified Health Interface (UHI). The workflow covers the whole booking: doctor search, slot search, initiate, confirm, then status, reschedule and cancel.

Every step is asynchronous. A `POST` starts the request and returns identifiers at once. The result arrives on a webhook, and you can also read it with the matching `GET`.

## Before you start

* A Bearer token. Every UHI operation uses the `authApiKey` scheme. See [Authorization](/api-sdk/auth/getting-started).
* The patient logged in on your app, with their Eka user id (`oid`) in hand to send as `X-Pt-Id`. See [Log in to an existing ABHA](/docs/hie-cm/workflows/login-abha).&#x20;
* A webhook endpoint registered with Eka that verifies `Eka-Webhook-Signature`. See [Webhook signature](/docs/webhooks/webhook-signature).
* The patient's search criteria and the time window they are free, and their billing name, phone and address for the booking.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  App->>Eka: POST /abdm/uhi/v1/physical-consultation/search/doctors
  Eka-->>App: webhook doctor.search.results
  App->>Eka: GET /abdm/uhi/v1/physical-consultation/search/doctors
  App->>Eka: POST /abdm/uhi/v1/physical-consultation/search/doctors/slots
  Eka-->>App: webhook doctor.slot.search.results
  App->>Eka: GET /abdm/uhi/v1/physical-consultation/search/doctors/slots
  App->>Eka: POST /abdm/uhi/v1/physical-consultation/booking/init
  Eka-->>App: webhook booking.init
  App->>Eka: GET /abdm/uhi/v1/physical-consultation/booking/init
  App->>Eka: POST /abdm/uhi/v1/physical-consultation/booking/confirm
  Eka-->>App: webhook booking.confirm
  App->>Eka: GET /abdm/uhi/v1/physical-consultation/booking/confirm
  App->>Eka: POST /abdm/uhi/v1/physical-consultation/booking/order-status
  Eka-->>App: webhook booking.status
  App->>Eka: GET /abdm/uhi/v1/physical-consultation/booking/order-status
  App->>Eka: POST /abdm/uhi/v1/physical-consultation/booking/update
  App->>Eka: POST /abdm/uhi/v1/physical-consultation/booking/cancel
  Eka-->>App: webhook booking.cancel
  App->>Eka: GET /abdm/uhi/v1/physical-consultation/booking/cancel
```

## Steps

Every `POST` in this workflow returns `txn_id`, `provider_id` and `order_id`. The spec describes `txn_id` and `provider_id` as the values for the next call. Every `GET` except Get Doctors takes the same three as query parameters; the spec gives Get Doctors none.

**1. Search for doctors**

Send the patient's criteria to [Search Doctors](/api-sdk/uhi/phys-cons/search-doctors). `start_time` and `end_time` set the availability window. The reference page lists the optional filters, such as speciality, doctor, facility and location. Keep `txn_id` and `provider_id` from the response.

**2. Read the doctor results**

The `doctor.search.results` webhook carries the list. You can also read it from [Get Doctors](/api-sdk/uhi/phys-cons/get-doctors). If `data` is empty, widen the search and repeat step 1. The patient picks one doctor; keep that result's `hpr_id`, `facility_id` and `transaction_id`.

**3. Search the doctor's slots**

Send `hpr_id`, `facility_id`, `transaction_id`, `provider_id`, `start_time` and `end_time` to [Search Slots](/api-sdk/uhi/phys-cons/search-slots). All six are required. Keep `txn_id`, `provider_id` and `order_id` from the response.

**4. Read the slots**

The `doctor.slot.search.results` webhook carries `doctor`, `provider_info` and `slots`. You can also read them from [Get Slots](/api-sdk/uhi/phys-cons/get-slots). Each slot has `id`, `date`, `start_time`, `end_time`, `price` and `currency`. If `slots` is empty, pick another window or doctor. The patient picks one slot.

**5. Initiate the booking**

Send [Init](/api-sdk/uhi/phys-cons/init) these fields:

* From the chosen slot: its `id` as `slot_id`, its `start_time` and `end_time`, and its price as `price.value` and `price.currency`.
* The doctor's `doctor.id` as `doctor_id`.
* From the chosen doctor: `facility_id`.
* `provider_id`, `transaction_id`, and the patient's `billing`.

The spec describes `transaction_id` only as received in the previous API response. Keep `txn_id`, `provider_id` and `order_id` from the response.

**6. Show the quote and terms**

The `booking.init` webhook carries `quote` with `total` and `breakup`, `terms`, `payment` with `status` and `type`, and the `order_id`. You can also read them from [Get Init](/api-sdk/uhi/phys-cons/get-init). Show the total and the terms. The patient must accept the terms before you confirm.

**7. Confirm the booking**

Send `provider_id` and `transaction_id` from Init to [Confirm](/api-sdk/uhi/phys-cons/confirm). Keep `txn_id`, `provider_id` and `order_id` from the response.

**8. Read the confirmation and PIN**

The `booking.confirm` webhook carries `order_id`, `pin`, `slot`, `doctor_info` and `state`. You can also read them from [Get Confirm](/api-sdk/uhi/phys-cons/get-confirm). Show `pin` to the patient; they present it to the doctor before the consultation. Store `order_id` on the booking.

**9. Check the booking status**

Send `order_id`, `provider_id` and `transaction_id` to [Order Status](/api-sdk/uhi/phys-cons/order-status). The `booking.status` webhook carries the booking. You can also read it from [Get Order Status](/api-sdk/uhi/phys-cons/get-order-status).

**10. Reschedule, if the patient asks**

Send `order_id`, `provider_id`, `transaction_id`, `facility_id` and the new `slot_id`, `start_time` and `end_time` to [Update](/api-sdk/uhi/phys-cons/update). Get a new slot, for example by repeating steps 3 and 4.

**11. Cancel, if the patient asks**

Send `order_id`, `provider_id` and `transaction_id` to [Cancel](/api-sdk/uhi/phys-cons/cancel). The `booking.cancel` webhook carries `status`. You can also read it from [Get Cancel](/api-sdk/uhi/phys-cons/get-cancel). The spec gives `SUCCESS`, `FAILED` and `PENDING` as examples. Mark the booking cancelled only on `SUCCESS`.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `oid` | ABHA login | On the patient record | `X-Pt-Id` header on every call |
| `txn_id` | Each `POST` response | Until the next step's `POST` returns | The `GET` poll and the next `POST` as `transaction_id` |
| `provider_id` | Each `POST` response | With the booking, until the visit or cancellation | Every later call for this booking |
| `hpr_id`, `transaction_id` | Chosen doctor result | Until slot search returns | Search Slots |
| `facility_id` | Chosen doctor result | With the booking, until the visit or cancellation | Search Slots, Init, Update |
| `slot_id`, `start_time`, `end_time`, price | Chosen slot | Until Init returns | Init |
| `order_id` | Init, then Confirm | With the booking, until the visit or cancellation | Order Status, Update, Cancel |
| `pin` | Confirm | Until the visit | The patient shows it to the doctor |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](/docs/hie-cm/errors), matched by meaning. Log the code you actually receive.

Every UHI operation returns `GenericError` with `code`, `error` and `source_error` on a 4XX or 5XX. The spec lists no UHI-specific codes. See [Errors](/docs/hie-cm/errors).

| Situation | Code | Do |
| - | - | - |
| Missing or malformed field | 4XX | Fix the request; check the required fields on the reference page |
| Search returns no doctors or no slots | Empty `data` or `slots` | Widen the criteria or the time window |
| Expired or unknown transaction | | Restart from the step that issued it |
| Webhook never arrives | None | Poll the matching `GET` |
| Provider or network unavailable | 5XX | |
| Rate limit | | |
| Cancel returns `FAILED` or `PENDING` | `status` | Keep the booking active; check again with Get Cancel |

## Test it

The [testing page](/docs/hie-cm/testing) has the sandbox base URL, credentials and the happy path for every journey.

* [ ] Search doctors with a speciality and a seven-day window; receive `doctor.search.results`
* [ ] Search slots for one result; receive `doctor.slot.search.results` with at least one slot
* [ ] Init with that slot; receive `booking.init` with a quote and terms
* [ ] Confirm; receive `booking.confirm` with a `pin` and `order_id`
* [ ] Order Status; receive `booking.status` with the same `order_id`
* [ ] Update to another slot, then check Order Status shows the new slot
* [ ] Cancel; receive `booking.cancel` with `SUCCESS`
* [ ] Failure: a search that matches nothing returns empty `data`
* [ ] Failure: Search Slots without `hpr_id` returns a 4XX