# Fetch the service ids registered against a bridge

`GET /api/hiecm/gateway/v3/bridge-services`

Retrieve the unique identifiers, known as service IDs, that are associated with a specific bridge. In this context, a bridge acts as an intermediary component that connects various services or networks, enabling them to communicate with each other. When you call this API, it queries the bridge to gather a list of all the service IDs that have been registered with it.

```bash
curl --request GET \
  --url https://dev.abdm.gov.in/api/hiecm/gateway/v3/bridge-services \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Responses

- `200`: OK
  - `bridge` (object)
  - `bridge.id` (string)
  - `bridge.name` (string)
  - `bridge.url` (string)
  - `bridge.active` (boolean)
  - `bridge.blocklisted` (boolean)
  - `services` (object[])
  - `services.id` (string)
  - `services.name` (string)
  - `services.types` (string[])
  - `services.endpoints` (object)
  - `services.endpoints.hipEndpoints` (object[])
  - `services.endpoints.hipEndpoints.use` (string)
  - `services.endpoints.hipEndpoints.connectionType` (string)
  - `services.endpoints.hipEndpoints.address` (string)
  - `services.endpoints.hiuEndpoints` (object[])
  - `services.endpoints.hiuEndpoints.use` (string)
  - `services.endpoints.hiuEndpoints.connectionType` (string)
  - `services.endpoints.hiuEndpoints.address` (string)
  - `services.endpoints.healthLockerEndpoints` (object[])
  - `services.endpoints.healthLockerEndpoints.use` (string)
  - `services.endpoints.healthLockerEndpoints.connectionType` (string)
  - `services.endpoints.healthLockerEndpoints.address` (string)
  - `services.active` (boolean)
- `204`: No Content
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `400`: Bad Request
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1015 - Invalid Response. May be returned either bare (`ABDM-1015`) or with a trailing ": " separator (`ABDM-1015: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
- `500`: Internal Server Error
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "bridge": {
    "id": "Bridge_ABC",
    "name": "ABC Bridge",
    "url": "https://abc.def.in",
    "active": true,
    "blocklisted": false
  },
  "services": [
    {
      "id": "ABC_Service",
      "name": "Service ABC",
      "types": [
        "HIP"
      ],
      "endpoints": {
        "hipEndpoints": [
          {
            "use": "registration",
            "connectionType": "HTTPS",
            "address": "https://abc.com/register"
          }
        ],
        "hiuEndpoints": [
          {
            "use": "registration",
            "connectionType": "HTTPS",
            "address": "https://abc.com/register"
          }
        ],
        "healthLockerEndpoints": [
          {
            "use": "registration",
            "connectionType": "HTTPS",
            "address": "https://abc.com/register"
          }
        ]
      },
      "active": true
    }
  ]
}
```


---

# Fetch the details of a service ID

`GET /api/hiecm/gateway/v3/bridge-service/serviceId/{service-id}`

Retrieve the details associated with a specific service ID. When invoked, it queries the system to fetch comprehensive information about the service identified by the provided service ID.

```bash
curl --request GET \
  --url https://dev.abdm.gov.in/api/hiecm/gateway/v3/bridge-service/serviceId/{service-id} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Path parameters

- `service-id` (string, required): The service id

## Responses

- `200`: OK
  - `id` (number)
  - `bridgeId` (string)
  - `serviceId` (string)
  - `name` (string)
  - `isHip` (boolean)
  - `isHiu` (boolean)
  - `isHealthLocker` (boolean)
  - `isPhr` (boolean)
  - `active` (boolean)
  - `registerTime` (string)
  - `dateCreated` (string)
  - `dateModified` (string)
- `204`: No Content
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `400`: Bad Request
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1015 - Invalid Response. May be returned either bare (`ABDM-1015`) or with a trailing ": " separator (`ABDM-1015: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
- `500`: Internal Server Error
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "id": 4,
  "bridgeId": "ABC_Bridge",
  "serviceId": "ABC_Service",
  "name": "Service ABC",
  "isHip": true,
  "isHiu": true,
  "isHealthLocker": true,
  "isPhr": true,
  "active": true,
  "registerTime": "2022-10-06T10:10:00.587Z",
  "dateCreated": "2022-10-06T10:10:00.587Z",
  "dateModified": "2022-10-06T10:10:00.587Z"
}
```


---

# Update the bridge URL

`PATCH /api/hiecm/gateway/v3/bridge/url`

Update the URL of a bridge. When invoked, it allows users to modify the existing URL associated with a specific bridge. This functionality is crucial for maintaining accurate and up-to-date connection information within the network. By using this API, administrators can ensure that the bridge URL reflects the current configuration and routing requirements, facilitating seamless communication and integration between different services in the form of webhook site.

```bash
curl --request PATCH \
  --url https://dev.abdm.gov.in/api/hiecm/gateway/v3/bridge/url \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "<YOUR_CALLBACK_URL>"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `url` (string, required): The bridge URL to be updated

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `204`: No Content
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `400`: Bad Request
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1015 - Invalid Response. May be returned either bare (`ABDM-1015`) or with a trailing ": " separator (`ABDM-1015: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
- `500`: Internal Server Error
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 204 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "error": {
    "code": "ABDM-1001",
    "message": "No data found"
  }
}
```


---

# Generate access token

`POST /api/hiecm/gateway/v3/sessions`

Generate an access token. When invoked, it facilitates the authentication process by providing a secure token that can be used to access various services and resources within the system. This functionality is essential for ensuring secure and authorised access, enabling users to interact with protected endpoints and perform operations that require authentication. By using this API, users can obtain the necessary tokens to maintain secure sessions and access the system’s features effectively.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/gateway/v3/sessions \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "clientId": "SBX_0000",
  "clientSecret": "0******-***-***-***-a****",
  "grantType": "client_credentials"
}'
```

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `clientId` (string, required): The client ID issued to the integrator by ABDM at registration.
- `clientSecret` (string, required): The client secret issued to the integrator by ABDM along with the client ID.
- `grantType` (string, required): The method used by the client to obtain an access token, e.g. client_credentials. One of: client_credentials.

## Responses

- `202`: Accepted
  - `accessToken` (string)
  - `expiresIn` (integer)
  - `refreshExpiresIn` (integer)
  - `refreshToken` (string)
  - `tokenType` (string)
- `204`: No Content
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `400`: Bad Request
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1015 - Invalid Response. May be returned either bare (`ABDM-1015`) or with a trailing ": " separator (`ABDM-1015: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
- `500`: Internal Server Error
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 202 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "accessToken": "<TOKEN>",
  "expiresIn": 1200,
  "refreshExpiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "tokenType": "bearer"
}
```


---

# Gateway session

Session and token calls, certificate endpoints for verifying tokens, and bridge registration calls that tell ABDM which URL your callbacks arrive on.

The full operation list is in the [Gateway session API reference](/reference/hiecm-gateway).

New to this? Start with [Milestones](/docs/hiecm/v3/milestones).


---

# API references

Every endpoint below is generated from the specification that declares it. Each one has its own page with the headers, the body and a request you can send.

This page lists every module, including any that the role you have chosen does not use. The sidebar shows only yours.

In M2 and M3 a call is acknowledged now and answered later. The answer arrives as a callback, a POST from ABDM to the URL you registered, declared in the specification as a webhook. Each callback is shown on the call it belongs to, and has a page of its own under that module.

## Gateway session

4 endpoints across 2 use cases: Bridge, Session. Each endpoint has its own page in the sidebar.

[Read the whole specification](/reference/hiecm-gateway)

## M1 Identity

122 endpoints across 10 use cases: Create ABHA, Child ABHA, Login, Profile, ABHA Card & Profile, Find ABHA, Forgot ABHA, Benefit, Access Tokens & Encryption, ABHA Address Login. Each endpoint has its own page in the sidebar.

[Read the whole specification](/reference/hiecm-m1)

## M2 Health Information Provider

20 endpoints across 5 use cases: Link token, HIP initiated linking, User initiated linking, Consent and data flow, Callbacks. Each endpoint has its own page in the sidebar.

[Read the whole specification](/reference/hiecm-m2)

## M3 Health Information User

12 endpoints across 2 use cases: Consent and data flow, Callbacks. Each endpoint has its own page in the sidebar.

[Read the whole specification](/reference/hiecm-m3)

## M4 Registry Integration

100 endpoints across 4 use cases: HPID, HFR, HRP bridge services, HPR. Each endpoint has its own page in the sidebar.

[Read the whole specification](/reference/hiecm-m4)

## P1 Registration and login

42 endpoints across 4 use cases: PHR certificate and session token, Create ABHA number, Aadhaar OTP, Create ABHA address, PHR login. Each endpoint has its own page in the sidebar.

[Read the whole specification](/reference/hiecm-p1)

## P2 Consents Management

46 endpoints across 5 use cases: PHR profile, Link ABHA number, Quick OPD Registration, User initiated linking, Consent manager. Each endpoint has its own page in the sidebar.

[Read the whole specification](/reference/hiecm-p2)

## P3 Subscription

14 endpoints across 2 use cases: Subscription request and notifications, HIU side, Subscription approval and management, PHR side. Each endpoint has its own page in the sidebar.

[Read the whole specification](/reference/hiecm-p3)

## P4 Locker

5 endpoints across 1 use case: Locker. Each endpoint has its own page in the sidebar.

[Read the whole specification](/reference/hiecm-p4)

## Scan and Register

2 endpoints across 1 use case: Scan and register. Each endpoint has its own page in the sidebar.

[Read the whole specification](/reference/hiecm-scan-and-register)

## Patient scan and record share

11 endpoints across 1 use case: Record share. Each endpoint has its own page in the sidebar.

[Read the whole specification](/reference/hiecm-record-share)

## Scan and Pay

18 endpoints across 2 use cases: Scan and pay, Scan and pay details and version update. Each endpoint has its own page in the sidebar.

[Read the whole specification](/reference/hiecm-scan-and-pay)


---

# Search ABHA address (auth methods)

`POST /abha/api/v3/phr/web/login/abha/search`

**Endpoint:** `POST /abha/api/v3/phr/web/login/abha/search`

**Flow:** **ABHA Address Login - Aadhaar OTP** - step 1 of 6
- Previous: none (first call of this flow)
- Next: *ABHA address login via Aadhaar OTP - send OTP*

---

This API endpoint is used to search for ABHA (Ayushman Bharat Health Account) profiles. It allows users to retrieve information about their ABHA profiles using identifier ABHA address. This is essential for verifying the user’s identity and ensuring secure access to their ABHA profile

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/abha/search \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "abhaAddress": "<ABHA_ADDRESS>"
}'
```

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `abhaAddress` (string, required): The ABHA address chosen for the account, without the @ suffix.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it refers to the successful retrieve of user details based on the ABHA address
  - `healthIdNumber` (string)
  - `abhaAddress` (string)
  - `authMethods` (string[])
  - `blockedAuthMethods` (string[])
  - `status` (string)
  - `message` (string)
  - `fullName` (string)
  - `mobile` (string)
- `400`: The 400 response code signifies a bad request. In this context, it means that no user was found for the provided ABHA address.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
- `401`: A 401 Unauthorized error occurs when a server receives a request without valid authentication credentials or with incorrect credentials. This error indicates that the server cannot authenticate the user,
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: A 404 Not Found error occurs when a server cannot find the requested resource. This error indicates that the server is reachable, but the specific page or resource is not available
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "healthIdNumber": "<ABHA_NUMBER>",
  "abhaAddress": "<ABHA_ADDRESS>",
  "authMethods": [
    "MOBILE_OTP",
    "AADHAAR_OTP"
  ],
  "blockedAuthMethods": [],
  "status": "ACTIVE",
  "message": null,
  "fullName": "<NAME>",
  "mobile": "9340******"
}
```


---

# ABHA address login via Aadhaar OTP - send OTP

`POST /abha/api/v3/phr/web/login/abha/request/otp`

Starts login with an ABHA address. UIDAI sends an OTP to the Aadhaar-linked mobile. `loginId` is the RSA-encrypted ABHA address. Use *Search ABHA address (auth methods)* first to check that `Aadhaar_OTP` is allowed.

**Endpoint:** `POST /abha/api/v3/phr/web/login/abha/request/otp`

**Flow:** **ABHA Address Login - Aadhaar OTP** - step 2 of 6
- Previous: *Search ABHA address (auth methods)*
- Next: *ABHA address login via Aadhaar OTP - verify*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-address-login", "Aadhaar-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"ABHA-address"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"Aadhaar"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/abha/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-address-login",
    "aadhaar-verify"
  ],
  "loginHint": "abha-address",
  "loginId": "{{encryptedAbhaAddress}}",
  "otpSystem": "aadhaar"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: abha-address.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: aadhaar.

## Responses

- `200`: Success: OTP send-Success - Aadhaar
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): ABHA Address Verification via Aadhaar OTP-User Not found; ABHA Address Verification via Aadhaar OTP-Invaild abha address; ABHA Address Verification via Aadhaar OTP-Invaild Otp System
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Missing Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "message": "OTP sent to Aadhaar registered mobile number ending with ******0933"
}
```


---

# ABHA address login via Aadhaar OTP - verify

`POST /abha/api/v3/phr/web/login/abha/verify`

Verifies the Aadhaar OTP for ABHA-address login. Returns the linked ABHA address(es) in `users` and `tokens.token`. Send that token as the `X-token` header to the ABHA-address profile, PHR card and QR code APIs.

**Endpoint:** `POST /abha/api/v3/phr/web/login/abha/verify`

**Flow:** **ABHA Address Login - Aadhaar OTP** - step 3 of 6
- Previous: *ABHA address login via Aadhaar OTP - send OTP*
- Next: *Get ABHA-address profile*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-address-login", "Aadhaar-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/abha/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-address-login",
    "aadhaar-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "41e59beb-6ee7-421e-a844-3652b2482038",
      "otpValue": "{{encryptedOtpValue}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: OTP Verification -Success Aadhaaar Otp
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.profilePhoto` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
- `400`: Bad Request (request validation failed): ABHA Address Verification via Aadhaar OTP-Invalid Scope; ABHA Address Verification via Aadhaar OTP-Invalid Auth Methods; ABHA Address Verification via Aadhaar OTP-Invalid Transaction Id
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Missing Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "message": "OTP verified successfully",
  "authResult": "success",
  "users": [
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "<NAME>",
      "profilePhoto": "<BASE64_PHOTO>",
      "abhaNumber": "<ABHA_NUMBER>",
      "status": "ACTIVE",
      "kycStatus": "VERIFIED"
    }
  ],
  "tokens": {
    "token": "<TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<TOKEN>",
    "refreshExpiresIn": 1296000
  }
}
```


---

# Get ABHA-address profile

`GET /abha/api/v3/phr/web/login/profile/abha-profile`

**Endpoint:** `GET /abha/api/v3/phr/web/login/profile/abha-profile`

**Flow:** **ABHA Address Login - Aadhaar OTP** - step 4 of 6
- Previous: *ABHA address login via Aadhaar OTP - verify*
- Next: *Get PHR card*

---

This API endpoint retrieves the user’s ABHA (Ayushman Bharat Health Account) profile. Access to this profile is granted after the successful verification of the OTP, ensuring the user’s profile information is secure.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/profile/abha-profile \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{jwtToken}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it signifies that the user was successfully verified with the OTP in the previous API call. A valid JWT token was provided, which authenticated the user and allowed access to their profile. As a result, the user profile was successfully retrieved, including all ABHA profile details.
  - `abhaAddress` (string)
  - `fullName` (string)
  - `profilePhoto` (string)
  - `firstName` (string)
  - `middleName` (string)
  - `lastName` (string)
  - `dayOfBirth` (string)
  - `monthOfBirth` (string)
  - `yearOfBirth` (string)
  - `dateOfBirth` (string)
  - `gender` (string)
  - `email` (string)
  - `mobile` (string)
  - `abhaNumber` (string)
  - `address` (string)
  - `stateName` (string)
  - `pinCode` (string)
  - `stateCode` (string)
  - `districtCode` (string)
  - `authMethods` (string[])
  - `status` (string)
  - `subDistrictCode` (string)
  - `subDistrictName` (string)
  - `emailVerified` (string)
  - `mobileVerified` (string)
  - `kycStatus` (string)
- `400`: A  Bad Request error with the description “invalid X-token”  indicates that the server received a request with an invalid or missing authentication token.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: The 401 response code indicates that the request was not authorized due to invalid credentials. Ensure that your API invocation includes the appropriate authorization header.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "abhaAddress": "<ABHA_ADDRESS>",
  "fullName": "<NAME>",
  "profilePhoto": "<BASE64_PHOTO>",
  "firstName": "<NAME>",
  "middleName": "<NAME>",
  "lastName": "<NAME>",
  "dayOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "yearOfBirth": "<DOB>",
  "dateOfBirth": "<DOB>",
  "gender": "M",
  "email": "<EMAIL>",
  "mobile": "<MOBILE_NUMBER>",
  "abhaNumber": "<ABHA_NUMBER>",
  "address": "<ADDRESS>",
  "stateName": "MAHARASHTRA",
  "pinCode": "<PINCODE>",
  "stateCode": "27",
  "districtCode": "487",
  "authMethods": [
    "AADHAAR_OTP",
    "MOBILE_OTP"
  ],
  "status": "ACTIVE",
  "subDistrictCode": "",
  "subDistrictName": "",
  "emailVerified": "false",
  "mobileVerified": "true",
  "kycStatus": "VERIFIED"
}
```


---

# Get PHR card

`GET /abha/api/v3/phr/web/login/profile/abha/phr-card`

**Endpoint:** `GET /abha/api/v3/phr/web/login/profile/abha/phr-card`

**Flow:** **ABHA Address Login - Aadhaar OTP** - step 5 of 6
- Previous: *Get ABHA-address profile*
- Next: *Get ABHA-address QR code*

---

This API endpoint is used to generate a PHR Card profile. It requires valid credentials and headers for authentication.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/profile/abha/phr-card \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{jwtToken}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `202`: Indicates a successful generation of PHR card
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: A 400 Bad Request error with the description “invalid X-token”  indicates that the server received a request with an invalid or missing authentication token.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Invalid Credentials error occurs when a server receives a request but cannot authorize it due to incorrect or missing authentication
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors


---

# Get ABHA-address QR code

`GET /abha/api/v3/phr/web/login/profile/abha/qr-code`

**Endpoint:** `GET /abha/api/v3/phr/web/login/profile/abha/qr-code`

**Flow:** **ABHA Address Login - Aadhaar OTP** - step 6 of 6
- Previous: *Get PHR card*
- Next: none (last call of this flow)

---

This API endpoint is used to generate a QR code for a complete ABHA address profile. The QR code can be used to quickly access and share the user’s ABHA address profile information. This is particularly useful for healthcare providers to retrieve patient information efficiently and securely.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/profile/abha/qr-code \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: Receives a QR code as a response which can be used to quickly access and share the user’s ABHA profile information.
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors


---

# ABHA address login via Fingerprint - send authentication request

`POST /abha/api/v3/phr/web/login/abha/request/otp`

Starts fingerprint login with an ABHA address. `loginId` is the RSA-encrypted ABHA address. Use the returned `txnId` in *ABHA address login via Fingerprint - verify*.

**Endpoint:** `POST /abha/api/v3/phr/web/login/abha/request/otp`

**Flow:** **ABHA Address Login - Fingerprint** - step 1 of 5
- Previous: none (first call of this flow)
- Next: *ABHA address login via Fingerprint - verify*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-bio-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"ABHA-address"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"Aadhaar"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

> **Note:** Biometric ABHA-address login uses scope `ABHA-login`, not `ABHA-address-login` (the same in Swagger and Postman).

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/abha/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-bio-verify"
  ],
  "loginHint": "abha-address",
  "loginId": "{{encryptedAbhaAddress}}",
  "otpSystem": "aadhaar"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: abha-address.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: aadhaar.

## Responses

- `200`: Success: Send Authentication Request via Biometric (Fingerprint Authentication)
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Missing Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "4faf0ca4-ce24-4804-8dfa-1dd1c9f0edfb",
  "message": "FingerPrint authentication request successfully sent"
}
```


---

# ABHA address login via Fingerprint - verify

`POST /abha/api/v3/phr/web/login/abha/verify`

Completes fingerprint login with an ABHA address. Send the `txnId` and the fingerprint PID. Returns `users` and `tokens.token` (send it as `X-token` to the profile, PHR card and QR code APIs).

**Endpoint:** `POST /abha/api/v3/phr/web/login/abha/verify`

**Flow:** **ABHA Address Login - Fingerprint** - step 2 of 5
- Previous: *ABHA address login via Fingerprint - send authentication request*
- Next: *Get ABHA-address profile*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-bio-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["bio"]` | yes | Authentication method used in this step. |
| `authData.bio` | object | yes | Fingerprint authentication block. |
| `authData.bio.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.bio.fingerPrintAuthPid` | string | yes | Base64 PID block captured from a registered fingerprint RD device. |

> **Note:** Biometric ABHA-address login uses scope `ABHA-login`, not `ABHA-address-login` (the same in Swagger and Postman).

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/abha/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-bio-verify"
  ],
  "authData": {
    "authMethods": [
      "bio"
    ],
    "bio": {
      "txnId": "41e59beb-6ee7-421e-a844-3652b2482038",
      "fingerPrintAuthPid": "{{fingerPrintAuthPid}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.bio` (object, required): Fingerprint authentication block.
- `authData.bio.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.bio.fingerPrintAuthPid` (string, required): Base64 PID block captured from a registered fingerprint RD device.

## Responses

- `200`: Success: Verify via Biometric - Fingerprint Authentication
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.profilePhoto` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
- `400`: Bad Request (request validation failed): Biometric is locked; Biometric data did not match
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Missing Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "4faf0ca4-ce24-4804-8dfa-1dd1c9f0edfb",
  "message": "BIO verified successfully",
  "authResult": "success",
  "users": [
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "<NAME>",
      "profilePhoto": "<BASE64_PHOTO>",
      "abhaNumber": "<ABHA_NUMBER>",
      "status": "ACTIVE",
      "kycStatus": "VERIFIED"
    }
  ],
  "tokens": {
    "token": "<TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<TOKEN>",
    "refreshExpiresIn": 1296000,
    "switchProfileEnabled": false
  }
}
```


---

# Get ABHA-address profile

`GET /abha/api/v3/phr/web/login/profile/abha-profile`

**Endpoint:** `GET /abha/api/v3/phr/web/login/profile/abha-profile`

**Flow:** **ABHA Address Login - Fingerprint** - step 3 of 5
- Previous: *ABHA address login via Fingerprint - verify*
- Next: *Get PHR card*

---

This API endpoint retrieves the user’s ABHA (Ayushman Bharat Health Account) profile. Access to this profile is granted after the successful verification of the OTP, ensuring the user’s profile information is secure.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/profile/abha-profile \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{jwtToken}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it signifies that the user was successfully verified with the OTP in the previous API call. A valid JWT token was provided, which authenticated the user and allowed access to their profile. As a result, the user profile was successfully retrieved, including all ABHA profile details.
  - `abhaAddress` (string)
  - `fullName` (string)
  - `profilePhoto` (string)
  - `firstName` (string)
  - `middleName` (string)
  - `lastName` (string)
  - `dayOfBirth` (string)
  - `monthOfBirth` (string)
  - `yearOfBirth` (string)
  - `dateOfBirth` (string)
  - `gender` (string)
  - `email` (string)
  - `mobile` (string)
  - `abhaNumber` (string)
  - `address` (string)
  - `stateName` (string)
  - `pinCode` (string)
  - `stateCode` (string)
  - `districtCode` (string)
  - `authMethods` (string[])
  - `status` (string)
  - `subDistrictCode` (string)
  - `subDistrictName` (string)
  - `emailVerified` (string)
  - `mobileVerified` (string)
  - `kycStatus` (string)
- `400`: A  Bad Request error with the description “invalid X-token”  indicates that the server received a request with an invalid or missing authentication token.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: The 401 response code indicates that the request was not authorized due to invalid credentials. Ensure that your API invocation includes the appropriate authorization header.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "abhaAddress": "<ABHA_ADDRESS>",
  "fullName": "<NAME>",
  "profilePhoto": "<BASE64_PHOTO>",
  "firstName": "<NAME>",
  "middleName": "<NAME>",
  "lastName": "<NAME>",
  "dayOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "yearOfBirth": "<DOB>",
  "dateOfBirth": "<DOB>",
  "gender": "M",
  "email": "<EMAIL>",
  "mobile": "<MOBILE_NUMBER>",
  "abhaNumber": "<ABHA_NUMBER>",
  "address": "<ADDRESS>",
  "stateName": "MAHARASHTRA",
  "pinCode": "<PINCODE>",
  "stateCode": "27",
  "districtCode": "487",
  "authMethods": [
    "AADHAAR_OTP",
    "MOBILE_OTP"
  ],
  "status": "ACTIVE",
  "subDistrictCode": "",
  "subDistrictName": "",
  "emailVerified": "false",
  "mobileVerified": "true",
  "kycStatus": "VERIFIED"
}
```


---

# Get PHR card

`GET /abha/api/v3/phr/web/login/profile/abha/phr-card`

**Endpoint:** `GET /abha/api/v3/phr/web/login/profile/abha/phr-card`

**Flow:** **ABHA Address Login - Fingerprint** - step 4 of 5
- Previous: *Get ABHA-address profile*
- Next: *Get ABHA-address QR code*

---

This API endpoint is used to generate a PHR Card profile. It requires valid credentials and headers for authentication.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/profile/abha/phr-card \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{jwtToken}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `202`: Indicates a successful generation of PHR card
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: A 400 Bad Request error with the description “invalid X-token”  indicates that the server received a request with an invalid or missing authentication token.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Invalid Credentials error occurs when a server receives a request but cannot authorize it due to incorrect or missing authentication
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors


---

# Get ABHA-address QR code

`GET /abha/api/v3/phr/web/login/profile/abha/qr-code`

**Endpoint:** `GET /abha/api/v3/phr/web/login/profile/abha/qr-code`

**Flow:** **ABHA Address Login - Fingerprint** - step 5 of 5
- Previous: *Get PHR card*
- Next: none (last call of this flow)

---

This API endpoint is used to generate a QR code for a complete ABHA address profile. The QR code can be used to quickly access and share the user’s ABHA address profile information. This is particularly useful for healthcare providers to retrieve patient information efficiently and securely.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/profile/abha/qr-code \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: Receives a QR code as a response which can be used to quickly access and share the user’s ABHA profile information.
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors


---

# ABHA address login via IRIS - send authentication request

`POST /abha/api/v3/phr/web/login/abha/request/otp`

Starts IRIS login with an ABHA address. `loginId` is the RSA-encrypted ABHA address. Use the returned `txnId` in *ABHA address login via IRIS - verify*.

**Endpoint:** `POST /abha/api/v3/phr/web/login/abha/request/otp`

**Flow:** **ABHA Address Login - IRIS** - step 1 of 5
- Previous: none (first call of this flow)
- Next: *ABHA address login via IRIS - verify*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-iris-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"ABHA-address"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"Aadhaar"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

> **Note:** Biometric ABHA-address login uses scope `ABHA-login`, not `ABHA-address-login` (the same in Swagger and Postman).

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/abha/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-iris-verify"
  ],
  "loginHint": "abha-address",
  "loginId": "{{encryptedAbhaAddress}}",
  "otpSystem": "aadhaar"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: abha-address.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: aadhaar.

## Responses

- `200`: Success: Send Authentication Request via Biometric (IRIS Authentication)
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Missing Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "4faf0ca4-ce24-4804-8dfa-1dd1c9f0edfb",
  "message": "Iris authentication request successfully sent"
}
```


---

# ABHA address login via IRIS - verify

`POST /abha/api/v3/phr/web/login/abha/verify`

Completes IRIS login with an ABHA address. Send the `txnId` and the IRIS PID. Returns `users` and `tokens.token` (send it as `X-token` to the profile, PHR card and QR code APIs).

**Endpoint:** `POST /abha/api/v3/phr/web/login/abha/verify`

**Flow:** **ABHA Address Login - IRIS** - step 2 of 5
- Previous: *ABHA address login via IRIS - send authentication request*
- Next: *Get ABHA-address profile*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-iris-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["iris"]` | yes | Authentication method used in this step. |
| `authData.iris` | object | yes | IRIS authentication block. |
| `authData.iris.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.iris.irisAuthPid` | string | yes | Base64 PID block captured from a registered IRIS RD device. |

> **Note:** Biometric ABHA-address login uses scope `ABHA-login`, not `ABHA-address-login` (the same in Swagger and Postman).

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/abha/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-iris-verify"
  ],
  "authData": {
    "authMethods": [
      "iris"
    ],
    "iris": {
      "txnId": "41e59beb-6ee7-421e-a844-3652b2482038",
      "irisAuthPid": "{{irisAuthPid}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.iris` (object, required): IRIS authentication block.
- `authData.iris.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.iris.irisAuthPid` (string, required): Base64 PID block captured from a registered IRIS RD device.

## Responses

- `200`: Success: Verify via Biometric - Iris Authentication
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.profilePhoto` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
- `400`: Bad Request (request validation failed): Biometric is locked; Biometric data did not match
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Missing Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "4faf0ca4-ce24-4804-8dfa-1dd1c9f0edfb",
  "message": "Iris verified successfully",
  "authResult": "success",
  "users": [
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "<NAME>",
      "profilePhoto": "<BASE64_PHOTO>",
      "abhaNumber": "<ABHA_NUMBER>",
      "status": "ACTIVE",
      "kycStatus": "VERIFIED"
    }
  ],
  "tokens": {
    "token": "<TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<TOKEN>",
    "refreshExpiresIn": 1296000,
    "switchProfileEnabled": false
  }
}
```


---

# Get ABHA-address profile

`GET /abha/api/v3/phr/web/login/profile/abha-profile`

**Endpoint:** `GET /abha/api/v3/phr/web/login/profile/abha-profile`

**Flow:** **ABHA Address Login - IRIS** - step 3 of 5
- Previous: *ABHA address login via IRIS - verify*
- Next: *Get PHR card*

---

This API endpoint retrieves the user’s ABHA (Ayushman Bharat Health Account) profile. Access to this profile is granted after the successful verification of the OTP, ensuring the user’s profile information is secure.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/profile/abha-profile \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{jwtToken}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it signifies that the user was successfully verified with the OTP in the previous API call. A valid JWT token was provided, which authenticated the user and allowed access to their profile. As a result, the user profile was successfully retrieved, including all ABHA profile details.
  - `abhaAddress` (string)
  - `fullName` (string)
  - `profilePhoto` (string)
  - `firstName` (string)
  - `middleName` (string)
  - `lastName` (string)
  - `dayOfBirth` (string)
  - `monthOfBirth` (string)
  - `yearOfBirth` (string)
  - `dateOfBirth` (string)
  - `gender` (string)
  - `email` (string)
  - `mobile` (string)
  - `abhaNumber` (string)
  - `address` (string)
  - `stateName` (string)
  - `pinCode` (string)
  - `stateCode` (string)
  - `districtCode` (string)
  - `authMethods` (string[])
  - `status` (string)
  - `subDistrictCode` (string)
  - `subDistrictName` (string)
  - `emailVerified` (string)
  - `mobileVerified` (string)
  - `kycStatus` (string)
- `400`: A  Bad Request error with the description “invalid X-token”  indicates that the server received a request with an invalid or missing authentication token.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: The 401 response code indicates that the request was not authorized due to invalid credentials. Ensure that your API invocation includes the appropriate authorization header.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "abhaAddress": "<ABHA_ADDRESS>",
  "fullName": "<NAME>",
  "profilePhoto": "<BASE64_PHOTO>",
  "firstName": "<NAME>",
  "middleName": "<NAME>",
  "lastName": "<NAME>",
  "dayOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "yearOfBirth": "<DOB>",
  "dateOfBirth": "<DOB>",
  "gender": "M",
  "email": "<EMAIL>",
  "mobile": "<MOBILE_NUMBER>",
  "abhaNumber": "<ABHA_NUMBER>",
  "address": "<ADDRESS>",
  "stateName": "MAHARASHTRA",
  "pinCode": "<PINCODE>",
  "stateCode": "27",
  "districtCode": "487",
  "authMethods": [
    "AADHAAR_OTP",
    "MOBILE_OTP"
  ],
  "status": "ACTIVE",
  "subDistrictCode": "",
  "subDistrictName": "",
  "emailVerified": "false",
  "mobileVerified": "true",
  "kycStatus": "VERIFIED"
}
```


---

# Get PHR card

`GET /abha/api/v3/phr/web/login/profile/abha/phr-card`

**Endpoint:** `GET /abha/api/v3/phr/web/login/profile/abha/phr-card`

**Flow:** **ABHA Address Login - IRIS** - step 4 of 5
- Previous: *Get ABHA-address profile*
- Next: *Get ABHA-address QR code*

---

This API endpoint is used to generate a PHR Card profile. It requires valid credentials and headers for authentication.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/profile/abha/phr-card \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{jwtToken}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `202`: Indicates a successful generation of PHR card
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: A 400 Bad Request error with the description “invalid X-token”  indicates that the server received a request with an invalid or missing authentication token.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Invalid Credentials error occurs when a server receives a request but cannot authorize it due to incorrect or missing authentication
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors


---

# Get ABHA-address QR code

`GET /abha/api/v3/phr/web/login/profile/abha/qr-code`

**Endpoint:** `GET /abha/api/v3/phr/web/login/profile/abha/qr-code`

**Flow:** **ABHA Address Login - IRIS** - step 5 of 5
- Previous: *Get PHR card*
- Next: none (last call of this flow)

---

This API endpoint is used to generate a QR code for a complete ABHA address profile. The QR code can be used to quickly access and share the user’s ABHA address profile information. This is particularly useful for healthcare providers to retrieve patient information efficiently and securely.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/profile/abha/qr-code \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: Receives a QR code as a response which can be used to quickly access and share the user’s ABHA profile information.
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors


---

# Search ABHA address (auth methods)

`POST /abha/api/v3/phr/web/login/abha/search`

**Endpoint:** `POST /abha/api/v3/phr/web/login/abha/search`

**Flow:** **ABHA Address Login - Mobile OTP** - step 1 of 6
- Previous: none (first call of this flow)
- Next: *ABHA address login via Mobile OTP - send OTP*

---

This API endpoint is used to search for ABHA (Ayushman Bharat Health Account) profiles. It allows users to retrieve information about their ABHA profiles using identifier ABHA address. This is essential for verifying the user’s identity and ensuring secure access to their ABHA profile

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/abha/search \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "abhaAddress": "<ABHA_ADDRESS>"
}'
```

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `abhaAddress` (string, required): The ABHA address chosen for the account, without the @ suffix.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it refers to the successful retrieve of user details based on the ABHA address
  - `healthIdNumber` (string)
  - `abhaAddress` (string)
  - `authMethods` (string[])
  - `blockedAuthMethods` (string[])
  - `status` (string)
  - `message` (string)
  - `fullName` (string)
  - `mobile` (string)
- `400`: The 400 response code signifies a bad request. In this context, it means that no user was found for the provided ABHA address.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
- `401`: A 401 Unauthorized error occurs when a server receives a request without valid authentication credentials or with incorrect credentials. This error indicates that the server cannot authenticate the user,
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: A 404 Not Found error occurs when a server cannot find the requested resource. This error indicates that the server is reachable, but the specific page or resource is not available
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "healthIdNumber": "<ABHA_NUMBER>",
  "abhaAddress": "<ABHA_ADDRESS>",
  "authMethods": [
    "MOBILE_OTP",
    "AADHAAR_OTP"
  ],
  "blockedAuthMethods": [],
  "status": "ACTIVE",
  "message": null,
  "fullName": "<NAME>",
  "mobile": "9340******"
}
```


---

# ABHA address login via Mobile OTP - send OTP

`POST /abha/api/v3/phr/web/login/abha/request/otp`

Starts login with an ABHA address. ABDM sends an OTP to the mobile linked with the ABHA address. `loginId` is the RSA-encrypted ABHA address. Use *Search ABHA address (auth methods)* first to check that `MOBILE_OTP` is allowed.

**Endpoint:** `POST /abha/api/v3/phr/web/login/abha/request/otp`

**Flow:** **ABHA Address Login - Mobile OTP** - step 2 of 6
- Previous: *Search ABHA address (auth methods)*
- Next: *ABHA address login via Mobile OTP - verify*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-address-login", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"ABHA-address"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/abha/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-address-login",
    "mobile-verify"
  ],
  "loginHint": "abha-address",
  "loginId": "{{encryptedAbhaAddress}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: abha-address.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.

## Responses

- `200`: Success: OTP send-Success- Mobile Number
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Missing Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "message": "OTP is sent to Mobile number ending with ******9127"
}
```


---

# ABHA address login via Mobile OTP - verify

`POST /abha/api/v3/phr/web/login/abha/verify`

Verifies the mobile OTP for ABHA-address login. Returns the linked ABHA address(es) in `users` and `tokens.token`. Send that token as the `X-token` header to the ABHA-address profile, PHR card and QR code APIs.

**Endpoint:** `POST /abha/api/v3/phr/web/login/abha/verify`

**Flow:** **ABHA Address Login - Mobile OTP** - step 3 of 6
- Previous: *ABHA address login via Mobile OTP - send OTP*
- Next: *Get ABHA-address profile*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-address-login", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/abha/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-address-login",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "41e59beb-6ee7-421e-a844-3652b2482038",
      "otpValue": "{{encryptedOtpValue}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: OTP Verification -Success Mobile Otp; OTP Verification -OTP expired
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.profilePhoto` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Missing Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "message": "OTP verified successfully",
  "authResult": "success",
  "users": [
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "<NAME>",
      "profilePhoto": "<BASE64_PHOTO>",
      "abhaNumber": "<ABHA_NUMBER>",
      "status": "ACTIVE",
      "kycStatus": "VERIFIED"
    }
  ],
  "tokens": {
    "token": "<TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<TOKEN>",
    "refreshExpiresIn": 1296000
  }
}
```


---

# Get ABHA-address profile

`GET /abha/api/v3/phr/web/login/profile/abha-profile`

**Endpoint:** `GET /abha/api/v3/phr/web/login/profile/abha-profile`

**Flow:** **ABHA Address Login - Mobile OTP** - step 4 of 6
- Previous: *ABHA address login via Mobile OTP - verify*
- Next: *Get PHR card*

---

This API endpoint retrieves the user’s ABHA (Ayushman Bharat Health Account) profile. Access to this profile is granted after the successful verification of the OTP, ensuring the user’s profile information is secure.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/profile/abha-profile \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{jwtToken}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it signifies that the user was successfully verified with the OTP in the previous API call. A valid JWT token was provided, which authenticated the user and allowed access to their profile. As a result, the user profile was successfully retrieved, including all ABHA profile details.
  - `abhaAddress` (string)
  - `fullName` (string)
  - `profilePhoto` (string)
  - `firstName` (string)
  - `middleName` (string)
  - `lastName` (string)
  - `dayOfBirth` (string)
  - `monthOfBirth` (string)
  - `yearOfBirth` (string)
  - `dateOfBirth` (string)
  - `gender` (string)
  - `email` (string)
  - `mobile` (string)
  - `abhaNumber` (string)
  - `address` (string)
  - `stateName` (string)
  - `pinCode` (string)
  - `stateCode` (string)
  - `districtCode` (string)
  - `authMethods` (string[])
  - `status` (string)
  - `subDistrictCode` (string)
  - `subDistrictName` (string)
  - `emailVerified` (string)
  - `mobileVerified` (string)
  - `kycStatus` (string)
- `400`: A  Bad Request error with the description “invalid X-token”  indicates that the server received a request with an invalid or missing authentication token.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: The 401 response code indicates that the request was not authorized due to invalid credentials. Ensure that your API invocation includes the appropriate authorization header.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "abhaAddress": "<ABHA_ADDRESS>",
  "fullName": "<NAME>",
  "profilePhoto": "<BASE64_PHOTO>",
  "firstName": "<NAME>",
  "middleName": "<NAME>",
  "lastName": "<NAME>",
  "dayOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "yearOfBirth": "<DOB>",
  "dateOfBirth": "<DOB>",
  "gender": "M",
  "email": "<EMAIL>",
  "mobile": "<MOBILE_NUMBER>",
  "abhaNumber": "<ABHA_NUMBER>",
  "address": "<ADDRESS>",
  "stateName": "MAHARASHTRA",
  "pinCode": "<PINCODE>",
  "stateCode": "27",
  "districtCode": "487",
  "authMethods": [
    "AADHAAR_OTP",
    "MOBILE_OTP"
  ],
  "status": "ACTIVE",
  "subDistrictCode": "",
  "subDistrictName": "",
  "emailVerified": "false",
  "mobileVerified": "true",
  "kycStatus": "VERIFIED"
}
```


---

# Get PHR card

`GET /abha/api/v3/phr/web/login/profile/abha/phr-card`

**Endpoint:** `GET /abha/api/v3/phr/web/login/profile/abha/phr-card`

**Flow:** **ABHA Address Login - Mobile OTP** - step 5 of 6
- Previous: *Get ABHA-address profile*
- Next: *Get ABHA-address QR code*

---

This API endpoint is used to generate a PHR Card profile. It requires valid credentials and headers for authentication.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/profile/abha/phr-card \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{jwtToken}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `202`: Indicates a successful generation of PHR card
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: A 400 Bad Request error with the description “invalid X-token”  indicates that the server received a request with an invalid or missing authentication token.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Invalid Credentials error occurs when a server receives a request but cannot authorize it due to incorrect or missing authentication
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors


---

# Get ABHA-address QR code

`GET /abha/api/v3/phr/web/login/profile/abha/qr-code`

**Endpoint:** `GET /abha/api/v3/phr/web/login/profile/abha/qr-code`

**Flow:** **ABHA Address Login - Mobile OTP** - step 6 of 6
- Previous: *Get PHR card*
- Next: none (last call of this flow)

---

This API endpoint is used to generate a QR code for a complete ABHA address profile. The QR code can be used to quickly access and share the user’s ABHA address profile information. This is particularly useful for healthcare providers to retrieve patient information efficiently and securely.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/web/login/profile/abha/qr-code \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: Receives a QR code as a response which can be used to quickly access and share the user’s ABHA profile information.
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors


---

# Get ABHA QR code

`GET /abha/api/v3/profile/account/qrCode`

**Endpoint:** `GET /abha/api/v3/profile/account/qrCode`

**Flow:** **ABHA Card & Profile** - independent API; call the one that fits your identifier / modality.

---

This API endpoint is used to generate a QR code for an ABHA (Ayushman Bharat Health Account) profile. The QR code can be used to quickly access and share the user’s ABHA profile information. This is particularly useful for healthcare providers to retrieve patient information efficiently and securely.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/qrCode \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: Receives a QR code as a response which can be used to quickly access and share the user’s ABHA profile information.
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors


---

# Retrieve ABHA card image

`GET /abha/api/v3/profile/account/abha-card`

**Endpoint:** `GET /abha/api/v3/profile/account/abha-card`

**Flow:** **ABHA Card & Profile** - independent API; call the one that fits your identifier / modality.

---

This API endpoint is used to retrieve the ABHA card image. It requires valid credentials and headers for authentication.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/abha-card \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: Successfully retrieved ABHA card image.
- `400`: Invalid X-token.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `message` (string)
  - `timestamp` (string)
- `401`: Unauthorized.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors


---

# Get ABHA profile

`GET /abha/api/v3/profile/account`

**Endpoint:** `GET /abha/api/v3/profile/account`

**Flow:** **ABHA Card & Profile** - independent API; call the one that fits your identifier / modality.

---

This API endpoint is used to manage ABHA (Ayushman Bharat Health Account) profiles. It allows users to fetch the user profile, ensuring that their details are accurate and up-to-date. This is essential for maintaining the integrity and security of the user’s health records.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: The account information was successfully retrieved or updated.
  - `ABHANumber` (string)
  - `preferredAbhaAddress` (string)
  - `mobile` (string)
  - `firstName` (string)
  - `middleName` (string)
  - `lastName` (string)
  - `name` (string)
  - `yearOfBirth` (string)
  - `dayOfBirth` (string)
  - `monthOfBirth` (string)
  - `gender` (string)
  - `profilePhoto` (string)
  - `status` (string)
  - `stateCode` (string)
  - `districtCode` (string)
  - `pincode` (string)
  - `address` (string)
  - `kycPhoto` (string)
  - `stateName` (string)
  - `districtName` (string)
  - `subdistrictName` (string)
  - `authMethods` (string[])
  - `tags` (object)
  - `kycVerified` (boolean)
  - `verificationStatus` (string)
  - `verificationType` (string)
  - `localizedDetails` (object)
  - `localizedDetails.name` (string)
  - `localizedDetails.stateName` (string)
  - `localizedDetails.districtName` (string)
  - `localizedDetails.villageName` (string)
  - `localizedDetails.townName` (string)
  - `localizedDetails.gender` (string)
  - `localizedDetails.localizedLabels` (object)
  - `localizedDetails.localizedLabels.name` (string)
  - `localizedDetails.localizedLabels.abhaNumber` (string)
  - `localizedDetails.localizedLabels.abhaAddress` (string)
  - `localizedDetails.localizedLabels.gender` (string)
  - `localizedDetails.localizedLabels.dob` (string)
  - `localizedDetails.localizedLabels.mobile` (string)
  - `createdDate` (string)
- `400`: Indicates various errors encountered during the account management process, such as invalid identifiers or missing parameters.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `message` (string)
  - `timestamp` (string)
- `401`: The request was unauthorized. This can occur due to invalid credentials or token.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "ABHANumber": "<ABHA_NUMBER>",
  "preferredAbhaAddress": "<ABHA_ADDRESS>",
  "mobile": "******0903",
  "firstName": "Username",
  "middleName": "<NAME>",
  "lastName": "<NAME>",
  "name": "<NAME>",
  "yearOfBirth": "<DOB>",
  "dayOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "gender": "M",
  "profilePhoto": "<BASE64_PHOTO>",
  "status": "ACTIVE",
  "stateCode": "27",
  "districtCode": "478",
  "pincode": "<PINCODE>",
  "address": "<ADDRESS>",
  "kycPhoto": "<BASE64_PHOTO>",
  "stateName": "MAHARASHTRA",
  "districtName": "<ADDRESS>",
  "subdistrictName": "<ADDRESS>",
  "authMethods": [
    "MOBILE_OTP",
    "AADHAAR_BIO",
    "... 3 more of the same shape"
  ],
  "tags": {},
  "kycVerified": true,
  "verificationStatus": "VERIFIED",
  "verificationType": "AADHAAR",
  "localizedDetails": {
    "name": "<NAME>",
    "stateName": "महाराष्ट्र",
    "districtName": "<ADDRESS>",
    "villageName": "<ADDRESS>",
    "townName": "<ADDRESS>",
    "gender": "पुरुष",
    "localizedLabels": {
      "name": "नाव",
      "abhaNumber": "आभा क्रमांक",
      "abhaAddress": "आभा पत्ता",
      "gender": "लिंग",
      "dob": "जन्मतारीख",
      "mobile": "मोबाईल"
    }
  },
  "createdDate": "07-05-2024"
}
```


---

# Download ABHA card

`GET /abha/api/v3/profile/account/download-abha-card`

**Endpoint:** `GET /abha/api/v3/profile/account/download-ABHA-card`

**Flow:** **ABHA Card & Profile** - independent API; call the one that fits your identifier / modality.

---

Downloads the ABHA card of the logged-in user (`X-token`).

> **Note:** This API is only in the Postman collection (ABHA Profile/3. ABHA Card/3.4). The response is assumed to be a PDF / binary card, the same as *Retrieve ABHA Card image*.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/download-abha-card \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: ABHA card file.
- `400`: Invalid X-token.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `message` (string)
  - `timestamp` (string)
- `401`: Unauthorized.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors


---

# Refresh user token

`GET /abha/api/v3/profile/account/request/token`

**Endpoint:** `GET /abha/api/v3/profile/account/request/token`

**Flow:** **Access Tokens & Encryption** - independent API; call the one that fits your identifier / modality.

---

This API endpoint is used to request a token for accessing a user’s ABHA (Ayushman Bharat Health Account) profile. This token is essential for authenticating and authorizing the user to perform various actions within their profile.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/request/token \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'R-token: Bearer {{R-jwtToken}}' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `R-token` (string, required): Refresh token (`Bearer <refreshToken>`) received at login.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.

## Responses

- `200`: The token was successfully generated and sent to the user’s registered contact method.
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
- `400`: The 400 response code indicates a bad request
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `message` (string)
  - `timestamp` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, it refers to the lack of proper authentication during the operation of the Invalid Credentials
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `value` (object)
  - `value.code` (string)
  - `value.message` (string)
  - `value.description` (string)
- `404`: A 404 Not Found error occurs when a server cannot find the requested resource. This error indicates that the server is reachable, but the specific page or resource is not available
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "token": "<TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "refreshExpiresIn": 1296000
}
```


---

# Generate access token

`POST /api/hiecm/gateway/v3/sessions`

Generate an access token. When invoked, it facilitates the authentication process by providing a secure token that can be used to access various services and resources within the system. This functionality is essential for ensuring secure and authorised access, enabling users to interact with protected endpoints and perform operations that require authentication. By using this API, users can obtain the necessary tokens to maintain secure sessions and access the system’s features effectively.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/gateway/v3/sessions \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "clientId": "SBX_0000",
  "clientSecret": "0******-***-***-***-a****",
  "grantType": "client_credentials"
}'
```

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `clientId` (string, required): The client ID issued to the integrator by ABDM at registration.
- `clientSecret` (string, required): The client secret issued to the integrator by ABDM along with the client ID.
- `grantType` (string, required): The method used by the client to obtain an access token, e.g. client_credentials. One of: client_credentials.

## Responses

- `202`: Accepted
  - `accessToken` (string)
  - `expiresIn` (integer)
  - `refreshExpiresIn` (integer)
  - `refreshToken` (string)
  - `tokenType` (string)
- `204`: No Content
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `400`: Bad Request
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1015 - Invalid Response. May be returned either bare (`ABDM-1015`) or with a trailing ": " separator (`ABDM-1015: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
- `500`: Internal Server Error
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 202 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "accessToken": "<TOKEN>",
  "expiresIn": 1200,
  "refreshExpiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "tokenType": "bearer"
}
```


---

# Get public certificate (RSA encryption key)

`GET /abha/api/v3/profile/public/certificate`

Fetch the public key used for encryption of Aadhaar, OTP, mobile and other fields which require encryption.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/public/certificate \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.

## Responses

- `200`: Successful response
  - `publicKey` (string)
  - `encryptionAlgorithm` (string)
- `400`: The 400 response code indicates a bad request
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, it refers to the lack of proper authentication during the operation of the Invalid Credentials
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `example` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "publicKey": "MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAstWB95C5pHLXiYW59qyO4Xb+59KYVm9Hywbo77qETZVAyc6VIsxU+UWhd/k/YtjZibCznB+HaXWX9TVTFs9Nwgv7LRGq5uLczpZQDrU7dnGkl/urRA8p0Jv/f8T0MZdFWQgks91uFffeBmJOb58u68ZRxSYGMPe4hb9XXKDVsgoSJaRNYviH7RgAI2QhTCwLEiMqIaUX3p1SAc178ZlN8qHXSSGXvhDR1GKM+y2DIyJqlzfik7lD14mDY/I4lcbftib8cv7llkybtjX1AayfZp4XpmIXKWv8nRM488/jOAF81Bi13paKgpjQUUuwq9tb5Qd/DChytYgBTBTJFe7irDFCmTIcqPr8+IMB7tXA3YXPp3z605Z6cGoYxezUm2Nz2o6oUmarDUntDhq/PnkNergmSeSvS8gD9DHBuJkJWZweG3xOPXiKQAUBr92mdFhJGm6fitO5jsBxgpmulxpG0oKDy9lAOLWSqK92JMcbMNHn4wRikdI9HSiXrrI7fLhJYTbyU3I4v5ESdEsayHXuiwO/1C8y56egzKSw44GAtEpbAkTNEEfK5H5R0QnVBIXOvfeF4tzGvmkfOO6nNXU3o/WAdOyV3xSQ9dqLY5MEL4sJCGY1iJBIAQ452s8v0ynJG5Yq+8hNhsCVnklCzAlsIzQpnSVDUVEzv17grVAw078CAwEAAQ==",
  "encryptionAlgorithm": "RSA/ECB/OAEPWithSHA-1AndMGF1Padding"
}
```


---

# Create ABHA - Demographic authentication (Demo Auth)

`POST /abha/api/v3/enrollment/enrol/byAadhaar`

Creates an ABHA number from Aadhaar demographic details (name, DOB, gender, state/district, mobile), without OTP or biometric. If an ABHA already exists for the Aadhaar, it is returned. **Only for integrators approved by NHA**, who must send the `Benefit-Name` header.

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/byAadhaar`

**Flow:** **Benefit - Child ABHA** - step 1 of 6
- Previous: none (first call of this flow)
- Next: *Create Child ABHA*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| REQUEST-ID | yes | Unique UUID for every request. |
| Benefit-Name | yes | **Applicable for user who is enrolling via Benefit Program.** |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["demo_auth"]` | yes | Authentication method used in this step. |
| `authData.demo_auth` | object | yes | Demographic authentication block (Aadhaar demographic match). |
| `authData.demo_auth.aadhaarNumber` | string | yes | Aadhaar number, RSA-encrypted. |
| `authData.demo_auth.districtCode` | string | yes | LGD district code. |
| `authData.demo_auth.stateCode` | string | yes | LGD state code. |
| `authData.demo_auth.dateOfBirth` | string | yes | Date of birth as per Aadhaar (dd-MM-yyyy). |
| `authData.demo_auth.gender` | string | yes | Gender (M / F / O). |
| `authData.demo_auth.name` | string | yes | Full name. |
| `authData.demo_auth.mobile` | string | no | Mobile number to be linked with the ABHA (plain, 10 digits). |
| `authData.demo_auth.profilePhoto` | string | no | Base64 encoded profile photo. |
| `authData.demo_auth.pinCode` | string | no | PIN code of the address. |
| `authData.demo_auth.address` | string | no | Address as per Aadhaar. |
| `consent` | object | yes | Consent captured from the user for ABHA enrolment. |
| `consent.code` | string | yes | Consent code. Use `ABHA-enrollment`. |
| `consent.version` | string | yes | Consent version. Use `1.4`. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/byAadhaar \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "authData": {
    "authMethods": [
      "demo_auth"
    ],
    "demo_auth": {
      "aadhaarNumber": "{{encrypted aadhaar number}}",
      "districtCode": "{{District code}}",
      "stateCode": "{{State code}}",
      "dateOfBirth": "{{DOB}}",
      "gender": "{{Gender}}",
      "name": "{{Full name}}",
      "mobile": "{{Mobile number}}",
      "profilePhoto": "{{Base64 plain String}}",
      "pinCode": "<PINCODE>",
      "address": "<ADDRESS>"
    }
  },
  "consent": {
    "code": "abha-enrollment",
    "version": "1.4"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `BENEFIT_NAME` (string, required): **Applicable for user who is enrolling via Benefit Program.**

## Body

- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.demo_auth` (object, required): Demographic authentication block (Aadhaar demographic match).
- `authData.demo_auth.aadhaarNumber` (string, required): Aadhaar number, RSA-encrypted.
- `authData.demo_auth.districtCode` (string, required): LGD district code.
- `authData.demo_auth.stateCode` (string, required): LGD state code.
- `authData.demo_auth.dateOfBirth` (string, required): Date of birth as per Aadhaar (dd-MM-yyyy).
- `authData.demo_auth.gender` (string, required): Gender (M / F / O).
- `authData.demo_auth.name` (string, required): Full name.
- `authData.demo_auth.mobile` (string): Mobile number to be linked with the ABHA (plain, 10 digits).
- `authData.demo_auth.profilePhoto` (string): Base64 encoded profile photo.
- `authData.demo_auth.pinCode` (string): PIN code of the address.
- `authData.demo_auth.address` (string): Address as per Aadhaar.
- `consent` (object, required): Consent captured from the user for ABHA enrolment.
- `consent.code` (string, required): Consent code. Use `abha-enrollment`.
- `consent.version` (string, required): Consent version. Use `1.4`.

## Responses

- `200`: Success: DemoAuth API - New ABHA creation; DemoAuth API - In case of Existing ABHA Number
  - `message` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `ABHAProfile` (object)
  - `ABHAProfile.firstName` (string)
  - `ABHAProfile.middleName` (string)
  - `ABHAProfile.lastName` (string)
  - `ABHAProfile.dob` (string)
  - `ABHAProfile.gender` (string)
  - `ABHAProfile.mobile` (string)
  - `ABHAProfile.phrAddress` (string[])
  - `ABHAProfile.districtCode` (string)
  - `ABHAProfile.stateCode` (string)
  - `ABHAProfile.abhaType` (string)
  - `ABHAProfile.stateName` (string)
  - `ABHAProfile.districtName` (string)
  - `ABHAProfile.ABHANumber` (string)
  - `ABHAProfile.abhaStatus` (string)
  - `isNew` (boolean)
- `400`: Bad Request (request validation failed): DemoAuth API-State District not matching
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): DemoAuth API-Invalid Benefit Name
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `message` (string)
  - `timestamp` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure): DemoAuth API-6 ABHA linked to Mobile; DemoAuth API-Details not matches against Aadhaar
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "healthIdNumber": "<ABHA_NUMBER>",
  "healthId": "<ABHA_ADDRESS>",
  "mobile": "******0903",
  "firstName": "Username",
  "middleName": "<NAME>",
  "lastName": "<NAME>",
  "name": "<NAME>",
  "yearOfBirth": "<DOB>",
  "dayOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "gender": "F",
  "stateCode": "27",
  "districtCode": "490",
  "stateName": "MAHARASHTRA",
  "districtName": "<ADDRESS>",
  "kycVerified": true,
  "token": "<TOKEN>",
  "jwtResponse": {
    "token": "<TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<TOKEN>",
    "refreshExpiresIn": 1296000
  },
  "status": "ACTIVE",
  "new": true
}
```


---

# Create Child ABHA

`POST /abha/api/v3/enrollment/enrol/byAadhaar`

Creates a Child ABHA linked to the parent's ABHA. Send the **parent's** `X-token` (from the parent's ABHA creation or login) and `Benefit-Name`.**Only for Government integrators approved by NHA.**

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/byAadhaar`

**Flow:** **Benefit - Child ABHA** - step 2 of 6
- Previous: *Create ABHA - Demographic authentication (Demo Auth)*
- Next: *Get Child ABHA list of the parent*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| REQUEST-ID | yes | Unique UUID for every request. |
| Benefit-Name | yes | **Applicable for user who is enrolling via Benefit Program.** |
| X-token | yes | **Applicable for child ABHA creation. X-token of Parent user, user can get X-token after login to the system** |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["child"]` | yes | Authentication method used in this step. |
| `authData.child` | object | yes | Child ABHA details. |
| `authData.child.dayOfBirth` | string | yes | Day of birth of the child. |
| `authData.child.monthOfBirth` | string | yes | Month of birth of the child. |
| `authData.child.yearOfBirth` | string | yes | Year of birth of the child. |
| `authData.child.gender` | string | yes | Gender (M / F / O). |
| `authData.child.password` | string | no | Password (RSA-encrypted) / password block. |
| `authData.child.name` | string | yes | Full name. |
| `authData.child.profilePhoto` | string | no | Base64 encoded profile photo. |
| `authData.child.parentConsent` | string | no | Parent consent flag for creating a child ABHA. |
| `consent` | object | yes | Consent captured from the user for ABHA enrolment. |
| `consent.code` | string | yes | Consent code. Use `ABHA-enrollment`. |
| `consent.version` | string | yes | Consent version. Use `1.4`. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/byAadhaar \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "authData": {
    "authMethods": [
      "child"
    ],
    "child": {
      "dayOfBirth": "{{day Of Birth}}",
      "monthOfBirth": "{{month Of Birth}}",
      "yearOfBirth": "{{year Of Birth}}",
      "gender": "{{Gender}}",
      "password": "",
      "name": "{{Name}}",
      "profilePhoto": "",
      "parentConsent": "true"
    }
  },
  "consent": {
    "code": "abha-enrollment",
    "version": "1.4"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `BENEFIT_NAME` (string, required): **Applicable for user who is enrolling via Benefit Program.**
- `X-token` (string, required): **Applicable for child abha creation. X-token of Parent user, user can get X-token after login to the system**

## Body

- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.child` (object, required): Child ABHA details.
- `authData.child.dayOfBirth` (string, required): Day of birth of the child.
- `authData.child.monthOfBirth` (string, required): Month of birth of the child.
- `authData.child.yearOfBirth` (string, required): Year of birth of the child.
- `authData.child.gender` (string, required): Gender (M / F / O).
- `authData.child.password` (string): Password (RSA-encrypted) / password block.
- `authData.child.name` (string, required): Full name.
- `authData.child.profilePhoto` (string): Base64 encoded profile photo.
- `authData.child.parentConsent` (string): Parent consent flag for creating a child ABHA.
- `consent` (object, required): Consent captured from the user for ABHA enrolment.
- `consent.code` (string, required): Consent code. Use `abha-enrollment`.
- `consent.version` (string, required): Consent version. Use `1.4`.

## Responses

- `200`: Success: Create CHILD ABHA - Positive Flow; CHILD ABHA - Account Already Exist
  - `message` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `ABHAProfile` (object)
  - `ABHAProfile.firstName` (string)
  - `ABHAProfile.middleName` (string)
  - `ABHAProfile.lastName` (string)
  - `ABHAProfile.dob` (string)
  - `ABHAProfile.gender` (string)
  - `ABHAProfile.mobile` (string)
  - `ABHAProfile.phrAddress` (string[])
  - `ABHAProfile.districtCode` (string)
  - `ABHAProfile.stateCode` (string)
  - `ABHAProfile.abhaType` (string)
  - `ABHAProfile.stateName` (string)
  - `ABHAProfile.districtName` (string)
  - `ABHAProfile.ABHANumber` (string)
  - `ABHAProfile.abhaStatus` (string)
  - `isNew` (boolean)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): CHILD ABHA-Invalid Benefit Name; CHILD ABHA-Access Issue; CHILD ABHA - X-token expired
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `message` (string)
  - `timestamp` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure): CHILD ABHA-CHILD LIMIT
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "message": "Account created successfully",
  "tokens": {
    "token": "<TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<TOKEN>",
    "refreshExpiresIn": 1296000
  },
  "ABHAProfile": {
    "firstName": "Username",
    "middleName": "",
    "lastName": "<NAME>",
    "dob": "<DOB>",
    "gender": "F",
    "photo": "",
    "mobile": "******0903",
    "districtCode": "490",
    "stateCode": "27",
    "abhaType": "CHILD",
    "stateName": "Maharashtra",
    "districtName": "<ADDRESS>",
    "ABHANumber": "<ABHA_NUMBER>",
    "abhaStatus": "ACTIVE"
  },
  "isNew": true
}
```


---

# Get Child ABHA list of the parent

`GET /abha/api/v3/enrollment/profile/children`

**Endpoint:** `GET /abha/api/v3/enrollment/profile/children`

**Flow:** **Benefit - Child ABHA** - step 3 of 6
- Previous: *Create Child ABHA*
- Next: *Update Child ABHA profile*

---

This API endpoint retrieves the ABHA (Ayushman Bharat Health Account) profile of a child, making it especially useful for managing minors’ health records and information. It provides essential details such as the child’s ABHA number, date of birth, name, and gender. Additionally, this endpoint allows users to access all child records linked to a parent’s ABHA number.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/profile/children \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'Content-Type: application/json' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'X-token: Bearer {{X-token}}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `Content-Type` (string, required): `application/json`.
- `BENEFIT_NAME` (string, required): Benefit / program name approved by NHA for the integrator.
- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.

## Responses

- `200`: Indicates a successful request. The response includes the updated child ABHA profile details
  - `parentAbhaNumber` (string)
  - `mobileNumber` (string)
  - `childrenCount` (integer)
  - `children` (object[])
  - `children.dateOfBirth` (string)
  - `children.name` (string)
  - `children.gender` (string)
  - `children.phrAddress` (string)
  - `children.ABHANumber` (string)
- `401`: Indicates an unauthorized request due to invalid credentials
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "parentAbhaNumber": "<ABHA_NUMBER>",
  "mobileNumber": "******0903",
  "childrenCount": 2,
  "children": [
    {
      "dateOfBirth": "<DOB>",
      "name": "<NAME>",
      "gender": "M",
      "phrAddress": "<ABHA_ADDRESS>",
      "ABHANumber": "<ABHA_NUMBER>"
    },
    {
      "dateOfBirth": "<DOB>",
      "name": "<NAME>",
      "gender": "F",
      "phrAddress": "<ABHA_ADDRESS>",
      "ABHANumber": "<ABHA_NUMBER>"
    }
  ]
}
```


---

# Update Child ABHA profile

`PATCH /abha/api/v3/profile/account`

Updates the demographic details (name, DOB, gender) of a Child ABHA. Send `Benefit-Name` and the `X-token` from the Child ABHA creation response. A non-KYC Child ABHA can be updated only once.

**Endpoint:** `PATCH /abha/api/v3/profile/account`

**Flow:** **Benefit - Child ABHA** - step 4 of 6
- Previous: *Get Child ABHA list of the parent*
- Next: *Child ABHA KYC - send Aadhaar OTP*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| REQUEST-ID | yes | Unique UUID for every request. |
| Benefit-Name | yes | Benefit / programme name approved by NHA for the integrator. |
| X-token | yes | User token (`Bearer <token>`) received after verification / login. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `abhaNumber` | string | yes | 14 digit ABHA number (xx-xxxx-xxxx-xxxx). |
| `dob` | string | yes | Date of birth (d-M-yyyy). |
| `name` | string | yes | Full name. |
| `gender` | string | yes | Gender (M / F / O). |

```bash
curl --request PATCH \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "abhaNumber": "<ABHA_NUMBER>",
  "dob": "<DOB>",
  "name": "<NAME>",
  "gender": "F"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `BENEFIT_NAME` (string, required): Benefit / program name approved by NHA for the integrator.
- `X-token` (string, required): User token (`Bearer <token>`) received after verification / login.

## Body

- `abhaNumber` (string, required): 14 digit ABHA number (xx-xxxx-xxxx-xxxx).
- `dob` (string, required): Date of birth (d-M-yyyy).
- `name` (string, required): Full name.
- `gender` (string, required): Gender (M / F / O).

## Responses

- `200`: Success: CHILD ABHA-Child Details
  - `ABHANumber` (string)
  - `preferredAbhaAddress` (string)
  - `mobile` (string)
  - `firstName` (string)
  - `middleName` (string)
  - `lastName` (string)
  - `yearOfBirth` (integer)
  - `monthOfBirth` (integer)
  - `dayOfBirth` (integer)
  - `gender` (string)
  - `status` (string)
  - `stateCode` (integer)
  - `districtCode` (integer)
  - `stateName` (string)
  - `districtName` (string)
  - `subdistrictName` (string)
  - `authMethods` (string[])
  - `tags` (object)
  - `kycVerified` (boolean)
  - `verificationStatus` (string)
  - `verificationType` (string)
  - `createdDate` (string)
- `400`: Bad Request (request validation failed): CHILD ABHA-Access Issue
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.message` (string)
  - `error.timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): CHILD ABHA-Access Issue
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `404`: Not Found: CHILD ABHA-Access Issue
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure): CHILD ABHA-Access Issue
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "ABHANumber": "<ABHA_NUMBER>",
  "preferredAbhaAddress": "<ABHA_ADDRESS>",
  "mobile": "******0903",
  "firstName": "<NAME>",
  "middleName": "<NAME>",
  "lastName": "<NAME>",
  "yearOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "dayOfBirth": "<DOB>",
  "gender": "F",
  "status": "ACTIVE",
  "stateCode": 27,
  "districtCode": 290,
  "stateName": "Maharashtra",
  "districtName": "<ADDRESS>",
  "subdistrictName": "<ADDRESS>",
  "authMethods": [
    "MOBILE_OTP"
  ],
  "tags": {},
  "kycVerified": false,
  "verificationStatus": "VERIFIED",
  "verificationType": "CHILD_ABHA",
  "createdDate": "10-05-2024"
}
```


---

# Child ABHA KYC - send Aadhaar OTP

`POST /abha/api/v3/profile/account/request/otp`

Starts KYC of a non-KYC Child ABHA. UIDAI sends an OTP to the mobile linked with the child's Aadhaar number. Send the child's `X-token`.

**Endpoint:** `POST /abha/api/v3/profile/account/request/otp`

**Flow:** **Benefit - Child ABHA** - step 5 of 6
- Previous: *Update Child ABHA profile*
- Next: *Child ABHA KYC - verify Aadhaar OTP*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| X-token | yes | User token (`Bearer <token>`) received after ABHA creation / login. |
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-profile", "re-KYC"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"Aadhaar"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"Aadhaar"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-profile",
    "re-kyc"
  ],
  "loginHint": "aadhaar",
  "loginId": "{{encrypted aadhaar number}}",
  "otpSystem": "aadhaar"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: aadhaar.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: aadhaar.

## Responses

- `200`: Success: KYC Child ABHA -Send OTP
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `Invalid Scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "c2095ea0-52ed-44ee-b8fc-02375b874e7a",
  "message": "OTP is sent to Aadhaar registered mobile number ending with *******0903"
}
```


---

# Child ABHA KYC - verify Aadhaar OTP

`POST /abha/api/v3/profile/account/verify`

Verifies the Aadhaar OTP sent by *Child ABHA KYC - send Aadhaar OTP* and marks the Child ABHA as KYC verified.

**Endpoint:** `POST /abha/api/v3/profile/account/verify`

**Flow:** **Benefit - Child ABHA** - step 6 of 6
- Previous: *Child ABHA KYC - send Aadhaar OTP*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| X-token | yes | User token (`Bearer <token>`) received after ABHA creation / login. |
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-profile", "re-KYC"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-profile",
    "re-kyc"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted otp value}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: CHILD ABHA KYC- Positive Flow
  - `txnId` (string)
  - `authResult` (string)
  - `message` (string)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `Invalid Scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `message` (string)
  - `timestamp` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "bb548986-e96d-4b48-be1b-1e36741e867d",
  "authResult": "success",
  "message": "KYC verification has been done",
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>"
    },
    {
      "mobileVerified": "true"
    }
  ]
}
```


---

# Create ABHA - Demographic authentication (Demo Auth)

`POST /abha/api/v3/enrollment/enrol/byAadhaar`

Creates an ABHA number from Aadhaar demographic details (name, DOB, gender, state/district, mobile), without OTP or biometric. If an ABHA already exists for the Aadhaar, it is returned. **Only for integrators approved by NHA**, who must send the `Benefit-Name` header.

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/byAadhaar`

**Flow:** **Benefit - Create ABHA via Demo Auth** - step 1 of 1
- Previous: none (first call of this flow)
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| REQUEST-ID | yes | Unique UUID for every request. |
| Benefit-Name | yes | **Applicable for user who is enrolling via Benefit Program.** |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["demo_auth"]` | yes | Authentication method used in this step. |
| `authData.demo_auth` | object | yes | Demographic authentication block (Aadhaar demographic match). |
| `authData.demo_auth.aadhaarNumber` | string | yes | Aadhaar number, RSA-encrypted. |
| `authData.demo_auth.districtCode` | string | yes | LGD district code. |
| `authData.demo_auth.stateCode` | string | yes | LGD state code. |
| `authData.demo_auth.dateOfBirth` | string | yes | Date of birth as per Aadhaar (dd-MM-yyyy). |
| `authData.demo_auth.gender` | string | yes | Gender (M / F / O). |
| `authData.demo_auth.name` | string | yes | Full name. |
| `authData.demo_auth.mobile` | string | no | Mobile number to be linked with the ABHA (plain, 10 digits). |
| `authData.demo_auth.profilePhoto` | string | no | Base64 encoded profile photo. |
| `authData.demo_auth.pinCode` | string | no | PIN code of the address. |
| `authData.demo_auth.address` | string | no | Address as per Aadhaar. |
| `consent` | object | yes | Consent captured from the user for ABHA enrolment. |
| `consent.code` | string | yes | Consent code. Use `ABHA-enrollment`. |
| `consent.version` | string | yes | Consent version. Use `1.4`. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/byAadhaar \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "authData": {
    "authMethods": [
      "demo_auth"
    ],
    "demo_auth": {
      "aadhaarNumber": "{{encrypted aadhaar number}}",
      "districtCode": "{{District code}}",
      "stateCode": "{{State code}}",
      "dateOfBirth": "{{DOB}}",
      "gender": "{{Gender}}",
      "name": "{{Full name}}",
      "mobile": "{{Mobile number}}",
      "profilePhoto": "{{Base64 plain String}}",
      "pinCode": "<PINCODE>",
      "address": "<ADDRESS>"
    }
  },
  "consent": {
    "code": "abha-enrollment",
    "version": "1.4"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `BENEFIT_NAME` (string, required): **Applicable for user who is enrolling via Benefit Program.**

## Body

- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.demo_auth` (object, required): Demographic authentication block (Aadhaar demographic match).
- `authData.demo_auth.aadhaarNumber` (string, required): Aadhaar number, RSA-encrypted.
- `authData.demo_auth.districtCode` (string, required): LGD district code.
- `authData.demo_auth.stateCode` (string, required): LGD state code.
- `authData.demo_auth.dateOfBirth` (string, required): Date of birth as per Aadhaar (dd-MM-yyyy).
- `authData.demo_auth.gender` (string, required): Gender (M / F / O).
- `authData.demo_auth.name` (string, required): Full name.
- `authData.demo_auth.mobile` (string): Mobile number to be linked with the ABHA (plain, 10 digits).
- `authData.demo_auth.profilePhoto` (string): Base64 encoded profile photo.
- `authData.demo_auth.pinCode` (string): PIN code of the address.
- `authData.demo_auth.address` (string): Address as per Aadhaar.
- `consent` (object, required): Consent captured from the user for ABHA enrolment.
- `consent.code` (string, required): Consent code. Use `abha-enrollment`.
- `consent.version` (string, required): Consent version. Use `1.4`.

## Responses

- `200`: Success: DemoAuth API - New ABHA creation; DemoAuth API - In case of Existing ABHA Number
  - `message` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `ABHAProfile` (object)
  - `ABHAProfile.firstName` (string)
  - `ABHAProfile.middleName` (string)
  - `ABHAProfile.lastName` (string)
  - `ABHAProfile.dob` (string)
  - `ABHAProfile.gender` (string)
  - `ABHAProfile.mobile` (string)
  - `ABHAProfile.phrAddress` (string[])
  - `ABHAProfile.districtCode` (string)
  - `ABHAProfile.stateCode` (string)
  - `ABHAProfile.abhaType` (string)
  - `ABHAProfile.stateName` (string)
  - `ABHAProfile.districtName` (string)
  - `ABHAProfile.ABHANumber` (string)
  - `ABHAProfile.abhaStatus` (string)
  - `isNew` (boolean)
- `400`: Bad Request (request validation failed): DemoAuth API-State District not matching
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): DemoAuth API-Invalid Benefit Name
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `message` (string)
  - `timestamp` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure): DemoAuth API-6 ABHA linked to Mobile; DemoAuth API-Details not matches against Aadhaar
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "healthIdNumber": "<ABHA_NUMBER>",
  "healthId": "<ABHA_ADDRESS>",
  "mobile": "******0903",
  "firstName": "Username",
  "middleName": "<NAME>",
  "lastName": "<NAME>",
  "name": "<NAME>",
  "yearOfBirth": "<DOB>",
  "dayOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "gender": "F",
  "stateCode": "27",
  "districtCode": "490",
  "stateName": "MAHARASHTRA",
  "districtName": "<ADDRESS>",
  "kycVerified": true,
  "token": "<TOKEN>",
  "jwtResponse": {
    "token": "<TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<TOKEN>",
    "refreshExpiresIn": 1296000
  },
  "status": "ACTIVE",
  "new": true
}
```


---

# Link / De-link benefit using X-token

`POST /abha/api/v3/profile/benefit/linkAndDelink`

Links (`scope: ["link"]`) or de-links (`scope: ["de-link"]`) the benefit named in the `BENEFIT_NAME` header for the ABHA of the logged-in user (`X-token`). The body has only `scope`.

**Endpoint:** `POST /abha/api/v3/profile/benefit/linkAndDelink`

**Flow:** **Benefit - Link / De-link** - independent API; call the one that fits your identifier / modality.

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| BENEFIT_NAME | yes | Benefit / programme name approved by NHA for the integrator. |
| X-token | yes | User token (`Bearer <token>`) received after verification / login. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["link"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/benefit/linkAndDelink \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "link"
  ]
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `BENEFIT_NAME` (string, required): Benefit / program name approved by NHA for the integrator.
- `X-token` (string, required): User token (`Bearer <token>`) received after verification / login.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.

## Responses

- `200`: Success: Linked successfully; Linked successfully (2); Linked successfully (Postman); De-linked successfully
  - `benefitName` (string)
  - `healthId` (string)
  - `status` (string)
- `400`: Bad Request (request validation failed): Already de-linked (spec); Already linked; Already de-linked; Invalid x-token
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token; Invalid benefit name; De-link_insurance restricted; link- Insurance restricted
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "benefitName": "COVIN",
  "healthId": "<ABHA_NUMBER>",
  "status": "Benefit record has been linked successfully"
}
```


---

# Link / De-link benefit using ABHA number

`POST /abha/api/v3/profile/benefit/linkAndDelink`

Links (`scope: ["link"]`) or de-links (`scope: ["de-link"]`) the benefit named in the `BENEFIT_NAME` header for an ABHA number. `loginId` is the RSA-encrypted ABHA number.

**Endpoint:** `POST /abha/api/v3/profile/benefit/linkAndDelink`

**Flow:** **Benefit - Link / De-link** - independent API; call the one that fits your identifier / modality.

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| BENEFIT_NAME | yes | Benefit / programme name approved by NHA for the integrator. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["link"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"ABHA-number"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/benefit/linkAndDelink \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "link"
  ],
  "loginHint": "abha-number",
  "loginId": "{{encrypted abha-number}}"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `BENEFIT_NAME` (string, required): Benefit / program name approved by NHA for the integrator.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: abha-number.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.

## Responses

- `200`: Success: Linked successfully; Linked successfully (2); Linked successfully (Postman); De-linked successfully
  - `benefitName` (string)
  - `healthId` (string)
  - `status` (string)
- `400`: Bad Request (request validation failed): Already de-linked (spec); Already linked; Already de-linked; Invalid Login ID
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token; Invalid Benefit Name - Link; Invalid Benefit Name - De-link; Insurance Restricted - Link; Insurance Restricted - De-link
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "benefitName": "COVIN",
  "healthId": "<ABHA_NUMBER>",
  "status": "Benefit record has been linked successfully"
}
```


---

# Link / De-link benefit using xmlUid

`POST /abha/api/v3/profile/benefit/linkAndDelink`

Links (`scope: ["link"]`) or de-links (`scope: ["de-link"]`) the benefit named in the `BENEFIT_NAME` header for an Aadhaar xmlUid. `loginId` is the RSA-encrypted xmlUid.

**Endpoint:** `POST /abha/api/v3/profile/benefit/linkAndDelink`

**Flow:** **Benefit - Link / De-link** - independent API; call the one that fits your identifier / modality.

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| BENEFIT_NAME | yes | Benefit / programme name approved by NHA for the integrator. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["de-link"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"xmlUid"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/benefit/linkAndDelink \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "de-link"
  ],
  "loginHint": "xmlUid",
  "loginId": "{{encrypted xmlUid}}"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `BENEFIT_NAME` (string, required): Benefit / program name approved by NHA for the integrator.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: xmlUid.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.

## Responses

- `200`: Success: Linked successfully; Linked successfully (2); Linked successfully (Postman); De-linked successfully
  - `benefitName` (string)
  - `healthId` (string)
  - `status` (string)
- `400`: Bad Request (request validation failed): Already de-linked (spec); Already linked; Already de-linked; Invalid Login ID
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token; Insurance Restricted - De-link; Insurance Restricted - Link; Invalid Benefit Name - Link; Invalid Benefit Name - De-link
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "benefitName": "COVIN",
  "healthId": "<ABHA_NUMBER>",
  "status": "Benefit record has been linked successfully"
}
```


---

# Benefit search by xmlUid

`POST /abha/api/v3/profile/benefit/search`

Lists the benefit programmes linked to an Aadhaar xmlUid. `loginId` is the RSA-encrypted xmlUid.

**Endpoint:** `POST /abha/api/v3/profile/benefit/search`

**Flow:** **Benefit - Search** - independent API; call the one that fits your identifier / modality.

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| BENEFIT_NAME | yes | Benefit / programme name approved by NHA for the integrator. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["search"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"xmlUid"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/benefit/search \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "search"
  ],
  "loginHint": "xmlUid",
  "loginId": "{{encrypted xmlUid}}"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `BENEFIT_NAME` (string, required): Benefit / program name approved by NHA for the integrator.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: xmlUid.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.

## Responses

- `200`: Success: Benefit Search via xmlUid; Benefit found (Postman)
- `400`: Bad Request (request validation failed): Invalid Scope; Invalid Login Hint; Invalid LoginId; Invalid Benefit Name
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `loginId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found: User Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
[
  {
    "benefitName": "healthid api",
    "abhaNumber": "<ABHA_NUMBER>",
    "status": 1
  }
]
```


---

# Benefit search by ABHA number

`POST /abha/api/v3/profile/benefit/search`

Lists the benefit programmes linked to an ABHA number. `loginId` is the RSA-encrypted ABHA number.

**Endpoint:** `POST /abha/api/v3/profile/benefit/search`

**Flow:** **Benefit - Search** - independent API; call the one that fits your identifier / modality.

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| BENEFIT_NAME | yes | Benefit / programme name approved by NHA for the integrator. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["search"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"ABHA-number"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/benefit/search \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "search"
  ],
  "loginHint": "abha-number",
  "loginId": "{{encrypted abha-number}}"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `BENEFIT_NAME` (string, required): Benefit / program name approved by NHA for the integrator.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: abha-number.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.

## Responses

- `200`: Success: Benefit Search via ABHA number; Benefit found (Postman); Benefit found - sandbox (Postman)
- `400`: Bad Request (request validation failed): Invalid Scope; Invalid Login Hint; Invalid LoginId; Invalid Benefit Name
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `loginId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found: User Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
[
  {
    "benefitName": "healthid api",
    "abhaNumber": "<ABHA_NUMBER>",
    "status": 1
  }
]
```


---

# Get benefits linked to an ABHA number

`GET /abha/api/v3/profile/benefit/abha/{abhanumber}`

**Endpoint:** `GET /abha/api/v3/profile/benefit/abha/{abhanumber}`

**Flow:** **Benefit - Search** - independent API; call the one that fits your identifier / modality.

---

This API endpoint is used to retrieve the benefit details associated with a specific ABHA (Ayushman Bharat Health Account) number. By providing the ABHA number in the request, the API returns information about the benefits linked to that account. This includes details such as the type of benefits, eligibility, and any other relevant information associated with the ABHA number. This endpoint ensures that users can access and manage their health benefits securely and efficiently.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/benefit/abha/{abhanumber} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `BENEFIT_NAME` (string, required): Benefit / program name approved by NHA for the integrator.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Path parameters

- `abhanumber` (string, required)

## Responses

- `200`: This scenario occurs when an ABHA (Ayushman Bharat Health Account) is linked to one or multiple benefit programs. Each benefit program may offer different types of health services, financial assistance, or other healthcare-related benefits. The system ensures that the ABHA number is correctly associated with all the relevant benefit programs, allowing the user to access and manage their benefits efficiently
  - `abhaNumber` (string)
  - `programme` (object[])
  - `programme.benefitName` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, it refers to the lack of proper authentication
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: The 404 response code indicates that the requested resource could not be found. In the context of searching for an ABHA (Ayushman Bharat Health Account) number using the endpoint API, this error occurs when the specified ABHA number does not exist or cannot be found in the system.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "abhaNumber": "<ABHA_NUMBER>",
  "programme": [
    {
      "benefitName": "Poshan Abhiyaan"
    },
    {
      "benefitName": "Test Benefit Program"
    },
    "... 1 more of the same shape"
  ]
}
```


---

# Create Child ABHA

`POST /abha/api/v3/enrollment/enrol/byAadhaar`

Creates a Child ABHA linked to the parent's ABHA. Send the **parent's** `X-token` (from the parent's ABHA creation or login) and `Benefit-Name`.**Only for Government integrators approved by NHA.**

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/byAadhaar`

**Flow:** **Child ABHA** - step 1 of 5
- Previous: none (first call of this flow)
- Next: *Get Child ABHA list of the parent*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| REQUEST-ID | yes | Unique UUID for every request. |
| Benefit-Name | yes | **Applicable for user who is enrolling via Benefit Program.** |
| X-token | yes | **Applicable for child ABHA creation. X-token of Parent user, user can get X-token after login to the system** |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["child"]` | yes | Authentication method used in this step. |
| `authData.child` | object | yes | Child ABHA details. |
| `authData.child.dayOfBirth` | string | yes | Day of birth of the child. |
| `authData.child.monthOfBirth` | string | yes | Month of birth of the child. |
| `authData.child.yearOfBirth` | string | yes | Year of birth of the child. |
| `authData.child.gender` | string | yes | Gender (M / F / O). |
| `authData.child.password` | string | no | Password (RSA-encrypted) / password block. |
| `authData.child.name` | string | yes | Full name. |
| `authData.child.profilePhoto` | string | no | Base64 encoded profile photo. |
| `authData.child.parentConsent` | string | no | Parent consent flag for creating a child ABHA. |
| `consent` | object | yes | Consent captured from the user for ABHA enrolment. |
| `consent.code` | string | yes | Consent code. Use `ABHA-enrollment`. |
| `consent.version` | string | yes | Consent version. Use `1.4`. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/byAadhaar \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "authData": {
    "authMethods": [
      "child"
    ],
    "child": {
      "dayOfBirth": "{{day Of Birth}}",
      "monthOfBirth": "{{month Of Birth}}",
      "yearOfBirth": "{{year Of Birth}}",
      "gender": "{{Gender}}",
      "password": "",
      "name": "{{Name}}",
      "profilePhoto": "",
      "parentConsent": "true"
    }
  },
  "consent": {
    "code": "abha-enrollment",
    "version": "1.4"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `BENEFIT_NAME` (string, required): **Applicable for user who is enrolling via Benefit Program.**
- `X-token` (string, required): **Applicable for child abha creation. X-token of Parent user, user can get X-token after login to the system**

## Body

- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.child` (object, required): Child ABHA details.
- `authData.child.dayOfBirth` (string, required): Day of birth of the child.
- `authData.child.monthOfBirth` (string, required): Month of birth of the child.
- `authData.child.yearOfBirth` (string, required): Year of birth of the child.
- `authData.child.gender` (string, required): Gender (M / F / O).
- `authData.child.password` (string): Password (RSA-encrypted) / password block.
- `authData.child.name` (string, required): Full name.
- `authData.child.profilePhoto` (string): Base64 encoded profile photo.
- `authData.child.parentConsent` (string): Parent consent flag for creating a child ABHA.
- `consent` (object, required): Consent captured from the user for ABHA enrolment.
- `consent.code` (string, required): Consent code. Use `abha-enrollment`.
- `consent.version` (string, required): Consent version. Use `1.4`.

## Responses

- `200`: Success: Create CHILD ABHA - Positive Flow; CHILD ABHA - Account Already Exist
  - `message` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `ABHAProfile` (object)
  - `ABHAProfile.firstName` (string)
  - `ABHAProfile.middleName` (string)
  - `ABHAProfile.lastName` (string)
  - `ABHAProfile.dob` (string)
  - `ABHAProfile.gender` (string)
  - `ABHAProfile.mobile` (string)
  - `ABHAProfile.phrAddress` (string[])
  - `ABHAProfile.districtCode` (string)
  - `ABHAProfile.stateCode` (string)
  - `ABHAProfile.abhaType` (string)
  - `ABHAProfile.stateName` (string)
  - `ABHAProfile.districtName` (string)
  - `ABHAProfile.ABHANumber` (string)
  - `ABHAProfile.abhaStatus` (string)
  - `isNew` (boolean)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): CHILD ABHA-Invalid Benefit Name; CHILD ABHA-Access Issue; CHILD ABHA - X-token expired
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `message` (string)
  - `timestamp` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure): CHILD ABHA-CHILD LIMIT
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "message": "Account created successfully",
  "tokens": {
    "token": "<TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<TOKEN>",
    "refreshExpiresIn": 1296000
  },
  "ABHAProfile": {
    "firstName": "Username",
    "middleName": "",
    "lastName": "<NAME>",
    "dob": "<DOB>",
    "gender": "F",
    "photo": "",
    "mobile": "******0903",
    "districtCode": "490",
    "stateCode": "27",
    "abhaType": "CHILD",
    "stateName": "Maharashtra",
    "districtName": "<ADDRESS>",
    "ABHANumber": "<ABHA_NUMBER>",
    "abhaStatus": "ACTIVE"
  },
  "isNew": true
}
```


---

# Get Child ABHA list of the parent

`GET /abha/api/v3/enrollment/profile/children`

**Endpoint:** `GET /abha/api/v3/enrollment/profile/children`

**Flow:** **Child ABHA** - step 2 of 5
- Previous: *Create Child ABHA*
- Next: *Update Child ABHA profile*

---

This API endpoint retrieves the ABHA (Ayushman Bharat Health Account) profile of a child, making it especially useful for managing minors’ health records and information. It provides essential details such as the child’s ABHA number, date of birth, name, and gender. Additionally, this endpoint allows users to access all child records linked to a parent’s ABHA number.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/profile/children \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'Content-Type: application/json' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'X-token: Bearer {{X-token}}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `Content-Type` (string, required): `application/json`.
- `BENEFIT_NAME` (string, required): Benefit / program name approved by NHA for the integrator.
- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.

## Responses

- `200`: Indicates a successful request. The response includes the updated child ABHA profile details
  - `parentAbhaNumber` (string)
  - `mobileNumber` (string)
  - `childrenCount` (integer)
  - `children` (object[])
  - `children.dateOfBirth` (string)
  - `children.name` (string)
  - `children.gender` (string)
  - `children.phrAddress` (string)
  - `children.ABHANumber` (string)
- `401`: Indicates an unauthorized request due to invalid credentials
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "parentAbhaNumber": "<ABHA_NUMBER>",
  "mobileNumber": "******0903",
  "childrenCount": 2,
  "children": [
    {
      "dateOfBirth": "<DOB>",
      "name": "<NAME>",
      "gender": "M",
      "phrAddress": "<ABHA_ADDRESS>",
      "ABHANumber": "<ABHA_NUMBER>"
    },
    {
      "dateOfBirth": "<DOB>",
      "name": "<NAME>",
      "gender": "F",
      "phrAddress": "<ABHA_ADDRESS>",
      "ABHANumber": "<ABHA_NUMBER>"
    }
  ]
}
```


---

# Update Child ABHA profile

`PATCH /abha/api/v3/profile/account`

Updates the demographic details (name, DOB, gender) of a Child ABHA. Send `Benefit-Name` and the `X-token` from the Child ABHA creation response. A non-KYC Child ABHA can be updated only once.

**Endpoint:** `PATCH /abha/api/v3/profile/account`

**Flow:** **Child ABHA** - step 3 of 5
- Previous: *Get Child ABHA list of the parent*
- Next: *Child ABHA KYC - send Aadhaar OTP*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| REQUEST-ID | yes | Unique UUID for every request. |
| Benefit-Name | yes | Benefit / programme name approved by NHA for the integrator. |
| X-token | yes | User token (`Bearer <token>`) received after verification / login. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `abhaNumber` | string | yes | 14 digit ABHA number (xx-xxxx-xxxx-xxxx). |
| `dob` | string | yes | Date of birth (d-M-yyyy). |
| `name` | string | yes | Full name. |
| `gender` | string | yes | Gender (M / F / O). |

```bash
curl --request PATCH \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "abhaNumber": "<ABHA_NUMBER>",
  "dob": "<DOB>",
  "name": "<NAME>",
  "gender": "F"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `BENEFIT_NAME` (string, required): Benefit / program name approved by NHA for the integrator.
- `X-token` (string, required): User token (`Bearer <token>`) received after verification / login.

## Body

- `abhaNumber` (string, required): 14 digit ABHA number (xx-xxxx-xxxx-xxxx).
- `dob` (string, required): Date of birth (d-M-yyyy).
- `name` (string, required): Full name.
- `gender` (string, required): Gender (M / F / O).

## Responses

- `200`: Success: CHILD ABHA-Child Details
  - `ABHANumber` (string)
  - `preferredAbhaAddress` (string)
  - `mobile` (string)
  - `firstName` (string)
  - `middleName` (string)
  - `lastName` (string)
  - `yearOfBirth` (integer)
  - `monthOfBirth` (integer)
  - `dayOfBirth` (integer)
  - `gender` (string)
  - `status` (string)
  - `stateCode` (integer)
  - `districtCode` (integer)
  - `stateName` (string)
  - `districtName` (string)
  - `subdistrictName` (string)
  - `authMethods` (string[])
  - `tags` (object)
  - `kycVerified` (boolean)
  - `verificationStatus` (string)
  - `verificationType` (string)
  - `createdDate` (string)
- `400`: Bad Request (request validation failed): CHILD ABHA-Access Issue
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.message` (string)
  - `error.timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): CHILD ABHA-Access Issue
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `404`: Not Found: CHILD ABHA-Access Issue
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure): CHILD ABHA-Access Issue
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "ABHANumber": "<ABHA_NUMBER>",
  "preferredAbhaAddress": "<ABHA_ADDRESS>",
  "mobile": "******0903",
  "firstName": "<NAME>",
  "middleName": "<NAME>",
  "lastName": "<NAME>",
  "yearOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "dayOfBirth": "<DOB>",
  "gender": "F",
  "status": "ACTIVE",
  "stateCode": 27,
  "districtCode": 290,
  "stateName": "Maharashtra",
  "districtName": "<ADDRESS>",
  "subdistrictName": "<ADDRESS>",
  "authMethods": [
    "MOBILE_OTP"
  ],
  "tags": {},
  "kycVerified": false,
  "verificationStatus": "VERIFIED",
  "verificationType": "CHILD_ABHA",
  "createdDate": "10-05-2024"
}
```


---

# Child ABHA KYC - send Aadhaar OTP

`POST /abha/api/v3/profile/account/request/otp`

Starts KYC of a non-KYC Child ABHA. UIDAI sends an OTP to the mobile linked with the child's Aadhaar number. Send the child's `X-token`.

**Endpoint:** `POST /abha/api/v3/profile/account/request/otp`

**Flow:** **Child ABHA** - step 4 of 5
- Previous: *Update Child ABHA profile*
- Next: *Child ABHA KYC - verify Aadhaar OTP*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| X-token | yes | User token (`Bearer <token>`) received after ABHA creation / login. |
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-profile", "re-KYC"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"Aadhaar"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"Aadhaar"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-profile",
    "re-kyc"
  ],
  "loginHint": "aadhaar",
  "loginId": "{{encrypted aadhaar number}}",
  "otpSystem": "aadhaar"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: aadhaar.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: aadhaar.

## Responses

- `200`: Success: KYC Child ABHA -Send OTP
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `Invalid Scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "c2095ea0-52ed-44ee-b8fc-02375b874e7a",
  "message": "OTP is sent to Aadhaar registered mobile number ending with *******0903"
}
```


---

# Child ABHA KYC - verify Aadhaar OTP

`POST /abha/api/v3/profile/account/verify`

Verifies the Aadhaar OTP sent by *Child ABHA KYC - send Aadhaar OTP* and marks the Child ABHA as KYC verified.

**Endpoint:** `POST /abha/api/v3/profile/account/verify`

**Flow:** **Child ABHA** - step 5 of 5
- Previous: *Child ABHA KYC - send Aadhaar OTP*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| X-token | yes | User token (`Bearer <token>`) received after ABHA creation / login. |
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-profile", "re-KYC"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-profile",
    "re-kyc"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted otp value}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: CHILD ABHA KYC- Positive Flow
  - `txnId` (string)
  - `authResult` (string)
  - `message` (string)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `Invalid Scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `message` (string)
  - `timestamp` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "bb548986-e96d-4b48-be1b-1e36741e867d",
  "authResult": "success",
  "message": "KYC verification has been done",
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>"
    },
    {
      "mobileVerified": "true"
    }
  ]
}
```


---

# Send Aadhaar OTP for ABHA enrolment

`POST /abha/api/v3/enrollment/request/otp`

Starts ABHA creation with Aadhaar OTP. UIDAI sends an OTP to the mobile number linked with the Aadhaar number. Use the `txnId` from the response in *Create ABHA - verify Aadhaar OTP*.

**Endpoint:** `POST /abha/api/v3/enrollment/request/otp`

**Flow:** **Create ABHA - Aadhaar OTP** - step 1 of 8
- Previous: none (first call of this flow)
- Next: *Create ABHA - verify Aadhaar OTP*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `txnId` | string | no | Transaction ID returned by the previous step of this flow. |
| `scope` | `["ABHA-enrol"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"Aadhaar"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"Aadhaar"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

> **Note:** `txnId` is optional here. Leave it empty on the first call, or send a previous `txnId` to resend the OTP.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "{{txnId}}",
  "scope": [
    "abha-enrol"
  ],
  "loginHint": "aadhaar",
  "loginId": "{{encrypted aadhaar number}}",
  "otpSystem": "aadhaar"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `txnId` (string): Transaction ID returned by the previous step of this flow.
- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: aadhaar.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: aadhaar.

## Responses

- `200`: Success: ABHA enrolment via Aadhaar-positive flow; ABHA Creation via Aadhaar OTP-REQUEST OTP FOR AADHAAR AUTHENTICATION
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): ABHA enrolment via Aadhaar-Invalid scope; ABHA enrolment via Aadhaar-Invalid LoginId; ABHA enrolment via Aadhaar-Invalid Login Hint; ABHA Creation via Aadhaar OTP-Invalid scope; ABHA Creation via Aadhaar OTP-Invalid Login Hint
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): ABHA enrolment via Aadhaar-Invalid access token; ABHA Creation via Aadhaar OTP-Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "message": "OTP sent to Aadhaar registered mobile number ending with ******0903"
}
```


---

# Create ABHA - verify Aadhaar OTP

`POST /abha/api/v3/enrollment/enrol/byAadhaar`

Verifies the Aadhaar OTP and creates the ABHA number, or returns the existing ABHA if one is already linked to the Aadhaar. The response contains the ABHA profile, `tokens.token` (user X-token) and a refresh token. `mobile` is the number to link with the ABHA. If it is not the Aadhaar-linked mobile, verify it next with *After ABHA creation - send OTP to verify mobile (optional)*.

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/byAadhaar`

**Flow:** **Create ABHA - Aadhaar OTP** - step 2 of 8
- Previous: *Send Aadhaar OTP for ABHA enrolment*
- Next: *After ABHA creation - send OTP to verify mobile (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| REQUEST-ID | yes | Unique UUID for every request. |
| Benefit-Name | no | **Applicable for user who is enrolling via Benefit Program.** |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |
| `authData.otp.mobile` | string | no | Mobile number to be linked with the ABHA (plain, 10 digits). |
| `consent` | object | yes | Consent captured from the user for ABHA enrolment. |
| `consent.code` | string | yes | Consent code. Use `ABHA-enrollment`. |
| `consent.version` | string | yes | Consent version. Use `1.4`. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/byAadhaar \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted otp}}",
      "mobile": "{{mobile number}}"
    }
  },
  "consent": {
    "code": "abha-enrollment",
    "version": "1.4"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `BENEFIT_NAME` (string): **Applicable for user who is enrolling via Benefit Program.**

## Body

- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.
- `authData.otp.mobile` (string): Mobile number to be linked with the ABHA (plain, 10 digits).
- `consent` (object, required): Consent captured from the user for ABHA enrolment.
- `consent.code` (string, required): Consent code. Use `abha-enrollment`.
- `consent.version` (string, required): Consent version. Use `1.4`.

## Responses

- `200`: Success: Create ABHA by verifying OTP - Positive flow
  - `message` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `ABHAProfile` (object)
  - `ABHAProfile.firstName` (string)
  - `ABHAProfile.middleName` (string)
  - `ABHAProfile.lastName` (string)
  - `ABHAProfile.dob` (string)
  - `ABHAProfile.gender` (string)
  - `ABHAProfile.mobile` (string)
  - `ABHAProfile.phrAddress` (string[])
  - `ABHAProfile.districtCode` (string)
  - `ABHAProfile.stateCode` (string)
  - `ABHAProfile.abhaType` (string)
  - `ABHAProfile.stateName` (string)
  - `ABHAProfile.districtName` (string)
  - `ABHAProfile.ABHANumber` (string)
  - `ABHAProfile.abhaStatus` (string)
  - `isNew` (boolean)
- `400`: Bad Request (request validation failed): Create ABHA by verifying OTP-Invalid Transaction Id; Create ABHA by verifying OTP-Invalid authMethod; Create ABHA by verifying OTP-Invalid Mobile Number
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Benefit Name (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `message` (string)
  - `timestamp` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure): Create ABHA by verifying OTP- Invalid OTP value
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "message": "This account already exist",
  "txnId": "b89ec10d-71fa-4280-83b3-1fedad66b5f5",
  "tokens": {
    "token": "<TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<TOKEN>",
    "refreshExpiresIn": 1296000
  },
  "ABHAProfile": {
    "firstName": "Username",
    "middleName": "<NAME>",
    "lastName": "<NAME>",
    "dob": "<DOB>",
    "gender": "M",
    "photo": "<BASE64_PHOTO>",
    "mobile": "******0903",
    "phrAddress": [
      "<ABHA_ADDRESS>"
    ],
    "address": "<ADDRESS>",
    "districtCode": "478",
    "stateCode": "27",
    "pinCode": "<PINCODE>",
    "abhaType": "STANDARD",
    "stateName": "MAHARASHTRA",
    "districtName": "<ADDRESS>",
    "ABHANumber": "<ABHA_NUMBER>",
    "abhaStatus": "ACTIVE"
  },
  "isNew": false
}
```


---

# After ABHA creation - send OTP to verify mobile (optional)

`POST /abha/api/v3/enrollment/request/otp`

Optional, called after the ABHA is created. Needed only when the `mobile` sent in the create-ABHA call is **not** the Aadhaar-linked mobile. ABDM sends an OTP to that mobile number so it can be linked to the ABHA. Send the `txnId` from the ABHA creation response.

**Endpoint:** `POST /abha/api/v3/enrollment/request/otp`

**Flow:** **Create ABHA - Aadhaar OTP** - step 3 of 8
- Previous: *Create ABHA - verify Aadhaar OTP*
- Next: *After ABHA creation - verify mobile OTP (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `scope` | `["ABHA-enrol", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"mobile"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "{{txnId}}",
  "scope": [
    "abha-enrol",
    "mobile-verify"
  ],
  "loginHint": "mobile",
  "loginId": "{{encrypted mobileNumber}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: mobile.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.

## Responses

- `200`: Success: Mobile Update - Send OTP- positive flow
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): Mobile Update - Send OTP-Invalid Scope; Mobile Update - Send OTP-Invalid LoginId; Mobile Update - Send OTP-Invalid Login Hint
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Mobile Update - Send OTP-Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-107h6b18a5fa",
  "message": "OTP sent to mobile number ending with ******0903"
}
```


---

# After ABHA creation - verify mobile OTP (optional)

`POST /abha/api/v3/enrollment/auth/byAbdm`

Verifies the OTP sent by *After ABHA creation - send OTP to verify mobile (optional)* and links the mobile number to the newly created ABHA.

**Endpoint:** `POST /abha/api/v3/enrollment/auth/byAbdm`

**Flow:** **Create ABHA - Aadhaar OTP** - step 4 of 8
- Previous: *After ABHA creation - send OTP to verify mobile (optional)*
- Next: *After ABHA creation - send OTP to verify email (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-enrol", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/auth/byAbdm \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-enrol",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted otp}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Mobile Update - Verify OTP-positive flow; Mobile Update - Verify OTP-OTP EXPIRED
  - `txnId` (string)
  - `authResult` (string)
  - `message` (string)
  - `accounts` (object[])
- `400`: Bad Request (request validation failed): Mobile Update - Verify OTP; Invalid Transaction Id; Invalid Scope; Invalid AuthMethod
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error: Mobile Update - Verify OTP-Invalid access token
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "authResult": "success",
  "message": "Mobile number is now successfully linked to your Account",
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>"
    }
  ]
}
```


---

# After ABHA creation - send OTP to verify email (optional)

`POST /abha/api/v3/enrollment/request/otp`

Optional. Sends an ABDM OTP to an email address so it can be linked to the newly created ABHA. Send the `txnId` from the previous enrolment step.

**Endpoint:** `POST /abha/api/v3/enrollment/request/otp`

**Flow:** **Create ABHA - Aadhaar OTP** - step 5 of 8
- Previous: *After ABHA creation - verify mobile OTP (optional)*
- Next: *After ABHA creation - verify email OTP (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `scope` | `["ABHA-enrol", "email-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"email"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "{{txnId}}",
  "scope": [
    "abha-enrol",
    "email-verify"
  ],
  "loginHint": "email",
  "loginId": "{{encrypted email}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: email.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.

## Responses

- `200`: Success: Email Verify via OTP-positive flow
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): ABHA Verify via Email-Invalid scope; ABHA Verify via Email-Invalid LoginId; ABHA Verify via Email-Invalid Login Hint
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Email verify via  OTP-Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "message": "OTP sent to email address ending with *************<EMAIL>"
}
```


---

# After ABHA creation - verify email OTP (optional)

`POST /abha/api/v3/enrollment/auth/byAbdm`

Verifies the OTP sent by *After ABHA creation - send OTP to verify email (optional)* and links the email address to the newly created ABHA.

**Endpoint:** `POST /abha/api/v3/enrollment/auth/byAbdm`

**Flow:** **Create ABHA - Aadhaar OTP** - step 6 of 8
- Previous: *After ABHA creation - send OTP to verify email (optional)*
- Next: *After ABHA creation - get ABHA address suggestions*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-enrol", "email-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/auth/byAbdm \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-enrol",
    "email-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted otp}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Email Update - Verify OTP-positive flow; Email Update - Verify OTP-OTP EXPIRED
  - `txnId` (string)
  - `authResult` (string)
  - `message` (string)
  - `accounts` (object[])
- `400`: Bad Request (request validation failed): Invalid Transaction Id; Invalid Scope; Invalid AuthMethod
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error: Unclassified Authentication Failure (generic)
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "authResult": "success",
  "message": "Email address is now successfully linked to your Account",
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>"
    }
  ]
}
```


---

# After ABHA creation - get ABHA address suggestions

`GET /abha/api/v3/enrollment/enrol/suggestion`

**Endpoint:** `GET /abha/api/v3/enrollment/enrol/suggestion`

**Flow:** **Create ABHA - Aadhaar OTP** - step 7 of 8
- Previous: *After ABHA creation - verify email OTP (optional)*
- Next: *After ABHA creation - create ABHA address*

---

This API endpoint is used to provide suggestions for ABHA addresses based on the user’s personal information. It helps users find suitable ABHA addresses by generating a list of suggestions. This is particularly useful during the ABHA enrolment process to ensure that users can choose an appropriate and unique ABHA address.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/suggestion \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TRANSACTION_ID: {{txnId}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TRANSACTION_ID` (string, required): Transaction ID from the ABHA creation response.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it refers to the successful operation of the Suggestion API, suggestions for ABHA addresses based on the user’s personal information.
  - `txnId` (string)
  - `abhaAddressList` (string[])
- `400`: The 400 response code indicates a bad request. In this context, it refers to various errors encountered during the operation of the Suggestion API. **Types of Suggestion API Errors:** **Abha Address - Invalid Transaction Id:** This error occurs when the transaction ID provided in the request is invalid. The transaction ID is essential for tracking the request and ensuring that the correct information is processed.. **Abha Address - Invalid Preferred Flag:** This error occurs when the preferred flag provided in the request is invalid. The preferred flag indicates the user’s preference for the suggested ABHA address.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, This error occurs when the transaction ID provided in the request is invalid. The transaction ID is essential for tracking the request and ensuring that the correct information is processed. An invalid transaction ID means the server cannot verify the request, leading to a failure in generating ABHA address suggestions.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "abhaAddressList": [
    "<ABHA_ADDRESS>",
    "<ABHA_ADDRESS>",
    "... 11 more of the same shape"
  ]
}
```


---

# After ABHA creation - create ABHA address

`POST /abha/api/v3/enrollment/enrol/abha-address`

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/abha-address`

**Flow:** **Create ABHA - Aadhaar OTP** - step 8 of 8
- Previous: *After ABHA creation - get ABHA address suggestions*
- Next: none (last call of this flow)

---

This API endpoint is used to enrol a new ABHA address. It allows users to create a unique ABHA address that can be used for accessing and managing their health records. The endpoint ensures that the provided ABHA address is unique and valid..

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/abha-address \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "{{txnId}}",
  "abhaAddress": "{{ABHA Address}}",
  "preferred": 1
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `txnId` (string, required): The transaction ID returned by the previous call in this flow.
- `abhaAddress` (string, required): The ABHA address chosen for the account, without the @ suffix.
- `preferred` (integer, required): 1 to make this the preferred ABHA address of the account, 0 otherwise.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it refers to the successful operation of the Enroll ABHA Address API.
  - `txnId` (string)
  - `abhaAddress` (string)
  - `preferred` (integer)
- `400`: The 400 response code indicates a bad request. In this context, it refers to various errors encountered during the operation of the Suggestion API. **Types of Suggestion API Errors:** **Invalid Preferred Flag:** This error occurs when the transaction ID provided in the request is invalid. The transaction ID is essential for tracking the request and ensuring that the correct information is processed. An invalid transaction ID means the server cannot verify the request, leading to a failure in enrolling the ABHA address. . **Invalid Transaction Id:** This error occurs when the preferred flag provided in the request is invalid. The preferred flag indicates the user’s preference for the suggested ABHA address. An invalid preferred flag means the server cannot process the user’s preference correctly, leading to a failure in enrolling the ABHA address.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `preferred` (string)
  - `timestamp` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, it refers to the lack of proper authentication during the operation of the Invalid Credentials.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "healthIdNumber": "<ABHA_NUMBER>",
  "preferredAbhaAddress": "<ABHA_ADDRESS>"
}
```


---

# Create ABHA - Demographic authentication (Demo Auth)

`POST /abha/api/v3/enrollment/enrol/byAadhaar`

Creates an ABHA number from Aadhaar demographic details (name, DOB, gender, state/district, mobile), without OTP or biometric. If an ABHA already exists for the Aadhaar, it is returned. **Only for integrators approved by NHA**, who must send the `Benefit-Name` header.

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/byAadhaar`

**Flow:** **Create ABHA - Demo Auth** - step 1 of 1
- Previous: none (first call of this flow)
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| REQUEST-ID | yes | Unique UUID for every request. |
| Benefit-Name | yes | **Applicable for user who is enrolling via Benefit Program.** |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["demo_auth"]` | yes | Authentication method used in this step. |
| `authData.demo_auth` | object | yes | Demographic authentication block (Aadhaar demographic match). |
| `authData.demo_auth.aadhaarNumber` | string | yes | Aadhaar number, RSA-encrypted. |
| `authData.demo_auth.districtCode` | string | yes | LGD district code. |
| `authData.demo_auth.stateCode` | string | yes | LGD state code. |
| `authData.demo_auth.dateOfBirth` | string | yes | Date of birth as per Aadhaar (dd-MM-yyyy). |
| `authData.demo_auth.gender` | string | yes | Gender (M / F / O). |
| `authData.demo_auth.name` | string | yes | Full name. |
| `authData.demo_auth.mobile` | string | no | Mobile number to be linked with the ABHA (plain, 10 digits). |
| `authData.demo_auth.profilePhoto` | string | no | Base64 encoded profile photo. |
| `authData.demo_auth.pinCode` | string | no | PIN code of the address. |
| `authData.demo_auth.address` | string | no | Address as per Aadhaar. |
| `consent` | object | yes | Consent captured from the user for ABHA enrolment. |
| `consent.code` | string | yes | Consent code. Use `ABHA-enrollment`. |
| `consent.version` | string | yes | Consent version. Use `1.4`. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/byAadhaar \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "authData": {
    "authMethods": [
      "demo_auth"
    ],
    "demo_auth": {
      "aadhaarNumber": "{{encrypted aadhaar number}}",
      "districtCode": "{{District code}}",
      "stateCode": "{{State code}}",
      "dateOfBirth": "{{DOB}}",
      "gender": "{{Gender}}",
      "name": "{{Full name}}",
      "mobile": "{{Mobile number}}",
      "profilePhoto": "{{Base64 plain String}}",
      "pinCode": "<PINCODE>",
      "address": "<ADDRESS>"
    }
  },
  "consent": {
    "code": "abha-enrollment",
    "version": "1.4"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `BENEFIT_NAME` (string, required): **Applicable for user who is enrolling via Benefit Program.**

## Body

- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.demo_auth` (object, required): Demographic authentication block (Aadhaar demographic match).
- `authData.demo_auth.aadhaarNumber` (string, required): Aadhaar number, RSA-encrypted.
- `authData.demo_auth.districtCode` (string, required): LGD district code.
- `authData.demo_auth.stateCode` (string, required): LGD state code.
- `authData.demo_auth.dateOfBirth` (string, required): Date of birth as per Aadhaar (dd-MM-yyyy).
- `authData.demo_auth.gender` (string, required): Gender (M / F / O).
- `authData.demo_auth.name` (string, required): Full name.
- `authData.demo_auth.mobile` (string): Mobile number to be linked with the ABHA (plain, 10 digits).
- `authData.demo_auth.profilePhoto` (string): Base64 encoded profile photo.
- `authData.demo_auth.pinCode` (string): PIN code of the address.
- `authData.demo_auth.address` (string): Address as per Aadhaar.
- `consent` (object, required): Consent captured from the user for ABHA enrolment.
- `consent.code` (string, required): Consent code. Use `abha-enrollment`.
- `consent.version` (string, required): Consent version. Use `1.4`.

## Responses

- `200`: Success: DemoAuth API - New ABHA creation; DemoAuth API - In case of Existing ABHA Number
  - `message` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `ABHAProfile` (object)
  - `ABHAProfile.firstName` (string)
  - `ABHAProfile.middleName` (string)
  - `ABHAProfile.lastName` (string)
  - `ABHAProfile.dob` (string)
  - `ABHAProfile.gender` (string)
  - `ABHAProfile.mobile` (string)
  - `ABHAProfile.phrAddress` (string[])
  - `ABHAProfile.districtCode` (string)
  - `ABHAProfile.stateCode` (string)
  - `ABHAProfile.abhaType` (string)
  - `ABHAProfile.stateName` (string)
  - `ABHAProfile.districtName` (string)
  - `ABHAProfile.ABHANumber` (string)
  - `ABHAProfile.abhaStatus` (string)
  - `isNew` (boolean)
- `400`: Bad Request (request validation failed): DemoAuth API-State District not matching
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): DemoAuth API-Invalid Benefit Name
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `message` (string)
  - `timestamp` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure): DemoAuth API-6 ABHA linked to Mobile; DemoAuth API-Details not matches against Aadhaar
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "healthIdNumber": "<ABHA_NUMBER>",
  "healthId": "<ABHA_ADDRESS>",
  "mobile": "******0903",
  "firstName": "Username",
  "middleName": "<NAME>",
  "lastName": "<NAME>",
  "name": "<NAME>",
  "yearOfBirth": "<DOB>",
  "dayOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "gender": "F",
  "stateCode": "27",
  "districtCode": "490",
  "stateName": "MAHARASHTRA",
  "districtName": "<ADDRESS>",
  "kycVerified": true,
  "token": "<TOKEN>",
  "jwtResponse": {
    "token": "<TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<TOKEN>",
    "refreshExpiresIn": 1296000
  },
  "status": "ACTIVE",
  "new": true
}
```


---

# Face auth - generate transaction ID (init)

`POST /abha/api/v3/enrollment/enrol/auth/init`

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/auth/init`

**Flow:** **Create ABHA - Face Authentication** - step 1 of 9
- Previous: none (first call of this flow)
- Next: *Face auth - capture PID / track status*

---

This API will help to generate transaction ID. This transaction ID will be used for whole face authentication process.

 The user can submit this transaction ID to the **ABHA** app using either intent-based sharing or by generating a QR code.

User can use this transaction ID to generate QR code using any QR generator tool. Open ABHA app and scan this QR code on ABHA App to start and complete the face capture process.

The data format of the QR code should follow this pattern:
https:///face-auth?txnId=.

**For example:** https://phrsbx.abdm.gov.in/face-auth?txnId=bac7251b-cd25-44d5-9707-f3d2ba181c1c

 For Sandbox- PHR-env-base-URL - https://phrsbx.abdm.gov.in
 For Production - PHR-env-base-URL - https://phr.abdm.gov.in

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/auth/init \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-enrol",
    "face-auth"
  ]
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): The scopes of the request, which name the flow this call belongs to.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it refers to the successful generation of Transaction Id.
  - `txnId` (string)
  - `message` (string)
- `400`: The 400 response code indicates a bad request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `scope` (string)
  - `timestamp` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, it refers to the lack of proper authentication during the operation of the Invalid Credentials
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "message": "Transaction Id generated Successfully"
}
```


---

# Face auth - capture PID / track status

`POST /abha/api/v3/enrollment/enrol/capturePID`

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/capturePID`

**Flow:** **Create ABHA - Face Authentication** - step 2 of 9
- Previous: *Face auth - generate transaction ID (init)*
- Next: *Create ABHA - Aadhaar face authentication*

---

This API is designed to verify the status of a transaction ID that was generated during the invocation of the `auth/init` API. It serves as a follow-up mechanism to ensure that the transaction is still valid, active, and has not expired or been invalidated.

 Wait for PID capture and submission confirmation from the ABHA App. The response of the API will return status of that transactionId. It can be either **PENDING,VERIFIED,FAILED,COMPLETE.**

 Once the status in the response of this API is returned as **COMPLETE**, it indicates that the face authentication process has been successfully completed. At this stage, the next step is to invoke the `/enrollment/enrol/byAadhaar` (You can find this API in ABHA ENROLLMENT Via Aadhaar section) API to proceed further.

User can poll the `/capturePID` API in every 5 - 10 seconds interval to check the status of face capture process or alternatively skip this step and call the `/enrollment/enrol/byAadhaar` API once they see the PID submission success message in the ABHA app.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/capturePID \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-enrol",
    "face-verify"
  ],
  "txnId": "ea1dc7aa-d7c3-40ab-bee8-84c6f1eb90fa"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): The scopes of the request, which name the flow this call belongs to.
- `txnId` (string, required): The transaction ID returned by the previous call in this flow.

## Responses

- `200`: The 200 response code indicates a successful request. The reponse of the API will return status of that transactionId. It can be either **PENDING,VERIFIED,FAILED,COMPLETE.**
  - `status` (string)
  - `message` (string)
- `400`: The 400 response code indicates a bad request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, it refers to the lack of proper authentication during the operation of the Invalid Credentials
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "status": "PENDING",
  "message": "Awaiting PID capture"
}
```


---

# Create ABHA - Aadhaar face authentication

`POST /abha/api/v3/enrollment/enrol/byAadhaar`

Creates an ABHA number with Aadhaar face authentication. First call *Face auth - generate transaction ID (init)*, then poll *Face auth - capture PID / track status* until the status is `COMPLETE`. Then send the same `txnId` here.

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/byAadhaar`

**Flow:** **Create ABHA - Face Authentication** - step 3 of 9
- Previous: *Face auth - capture PID / track status*
- Next: *After ABHA creation - send OTP to verify mobile (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| REQUEST-ID | yes | Unique UUID for every request. |
| Benefit-Name | no | **Applicable for user who is enrolling via Benefit Program.** |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["face_auth"]` | yes | Authentication method used in this step. |
| `authData.face` | object | yes | Face authentication block. |
| `authData.face.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.face.aadhaar` | string | yes | Aadhaar number, RSA-encrypted. |
| `authData.face.mobile` | string | no | Mobile number to be linked with the ABHA (plain, 10 digits). |
| `consent` | object | yes | Consent captured from the user for ABHA enrolment. |
| `consent.code` | string | yes | Consent code. Use `ABHA-enrollment`. |
| `consent.version` | string | yes | Consent version. Use `1.4`. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/byAadhaar \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "authData": {
    "authMethods": [
      "face_auth"
    ],
    "face": {
      "txnId": "881f2bf5-7377-4067-b50e-1e6ff100b3cc",
      "aadhaar": "{{encrypted aadhaar number}}",
      "mobile": "{{mobile number}}"
    }
  },
  "consent": {
    "code": "abha-enrollment",
    "version": "1.4"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `BENEFIT_NAME` (string): **Applicable for user who is enrolling via Benefit Program.**

## Body

- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.face` (object, required): Face authentication block.
- `authData.face.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.face.aadhaar` (string, required): Aadhaar number, RSA-encrypted.
- `authData.face.mobile` (string): Mobile number to be linked with the ABHA (plain, 10 digits).
- `consent` (object, required): Consent captured from the user for ABHA enrolment.
- `consent.code` (string, required): Consent code. Use `abha-enrollment`.
- `consent.version` (string, required): Consent version. Use `1.4`.

## Responses

- `200`: Success: Create ABHA via Face - Positive Flow
  - `message` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `ABHAProfile` (object)
  - `ABHAProfile.firstName` (string)
  - `ABHAProfile.middleName` (string)
  - `ABHAProfile.lastName` (string)
  - `ABHAProfile.dob` (string)
  - `ABHAProfile.gender` (string)
  - `ABHAProfile.mobile` (string)
  - `ABHAProfile.phrAddress` (string[])
  - `ABHAProfile.districtCode` (string)
  - `ABHAProfile.stateCode` (string)
  - `ABHAProfile.abhaType` (string)
  - `ABHAProfile.stateName` (string)
  - `ABHAProfile.districtName` (string)
  - `ABHAProfile.ABHANumber` (string)
  - `ABHAProfile.abhaStatus` (string)
  - `isNew` (boolean)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Benefit Name (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `message` (string)
  - `timestamp` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "message": "Account created successfully",
  "txnId": "b764e218-72b7-4bd7-a11e-2c9f2880fd61",
  "tokens": {
    "token": "<TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<TOKEN>",
    "refreshExpiresIn": 1296000
  },
  "ABHAProfile": {
    "firstName": "Username",
    "middleName": "",
    "lastName": "<NAME>",
    "dob": "<DOB>",
    "gender": "F",
    "photo": "",
    "mobile": "******0903",
    "email": null,
    "phrAddress": [
      "<ABHA_ADDRESS>"
    ],
    "districtCode": "490",
    "stateCode": "27",
    "abhaType": "CHILD",
    "stateName": "Maharashtra",
    "districtName": "<ADDRESS>",
    "ABHANumber": "<ABHA_NUMBER>",
    "abhaStatus": "ACTIVE"
  },
  "isNew": true
}
```


---

# After ABHA creation - send OTP to verify mobile (optional)

`POST /abha/api/v3/enrollment/request/otp`

Optional, called after the ABHA is created. Needed only when the `mobile` sent in the create-ABHA call is **not** the Aadhaar-linked mobile. ABDM sends an OTP to that mobile number so it can be linked to the ABHA. Send the `txnId` from the ABHA creation response.

**Endpoint:** `POST /abha/api/v3/enrollment/request/otp`

**Flow:** **Create ABHA - Face Authentication** - step 4 of 9
- Previous: *Create ABHA - Aadhaar face authentication*
- Next: *After ABHA creation - verify mobile OTP (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `scope` | `["ABHA-enrol", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"mobile"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "{{txnId}}",
  "scope": [
    "abha-enrol",
    "mobile-verify"
  ],
  "loginHint": "mobile",
  "loginId": "{{encrypted mobileNumber}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: mobile.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.

## Responses

- `200`: Success: Mobile Update - Send OTP- positive flow
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): Mobile Update - Send OTP-Invalid Scope; Mobile Update - Send OTP-Invalid LoginId; Mobile Update - Send OTP-Invalid Login Hint
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Mobile Update - Send OTP-Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-107h6b18a5fa",
  "message": "OTP sent to mobile number ending with ******0903"
}
```


---

# After ABHA creation - verify mobile OTP (optional)

`POST /abha/api/v3/enrollment/auth/byAbdm`

Verifies the OTP sent by *After ABHA creation - send OTP to verify mobile (optional)* and links the mobile number to the newly created ABHA.

**Endpoint:** `POST /abha/api/v3/enrollment/auth/byAbdm`

**Flow:** **Create ABHA - Face Authentication** - step 5 of 9
- Previous: *After ABHA creation - send OTP to verify mobile (optional)*
- Next: *After ABHA creation - send OTP to verify email (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-enrol", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/auth/byAbdm \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-enrol",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted otp}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Mobile Update - Verify OTP-positive flow; Mobile Update - Verify OTP-OTP EXPIRED
  - `txnId` (string)
  - `authResult` (string)
  - `message` (string)
  - `accounts` (object[])
- `400`: Bad Request (request validation failed): Mobile Update - Verify OTP; Invalid Transaction Id; Invalid Scope; Invalid AuthMethod
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error: Mobile Update - Verify OTP-Invalid access token
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "authResult": "success",
  "message": "Mobile number is now successfully linked to your Account",
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>"
    }
  ]
}
```


---

# After ABHA creation - send OTP to verify email (optional)

`POST /abha/api/v3/enrollment/request/otp`

Optional. Sends an ABDM OTP to an email address so it can be linked to the newly created ABHA. Send the `txnId` from the previous enrolment step.

**Endpoint:** `POST /abha/api/v3/enrollment/request/otp`

**Flow:** **Create ABHA - Face Authentication** - step 6 of 9
- Previous: *After ABHA creation - verify mobile OTP (optional)*
- Next: *After ABHA creation - verify email OTP (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `scope` | `["ABHA-enrol", "email-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"email"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "{{txnId}}",
  "scope": [
    "abha-enrol",
    "email-verify"
  ],
  "loginHint": "email",
  "loginId": "{{encrypted email}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: email.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.

## Responses

- `200`: Success: Email Verify via OTP-positive flow
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): ABHA Verify via Email-Invalid scope; ABHA Verify via Email-Invalid LoginId; ABHA Verify via Email-Invalid Login Hint
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Email verify via  OTP-Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "message": "OTP sent to email address ending with *************<EMAIL>"
}
```


---

# After ABHA creation - verify email OTP (optional)

`POST /abha/api/v3/enrollment/auth/byAbdm`

Verifies the OTP sent by *After ABHA creation - send OTP to verify email (optional)* and links the email address to the newly created ABHA.

**Endpoint:** `POST /abha/api/v3/enrollment/auth/byAbdm`

**Flow:** **Create ABHA - Face Authentication** - step 7 of 9
- Previous: *After ABHA creation - send OTP to verify email (optional)*
- Next: *After ABHA creation - get ABHA address suggestions*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-enrol", "email-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/auth/byAbdm \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-enrol",
    "email-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted otp}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Email Update - Verify OTP-positive flow; Email Update - Verify OTP-OTP EXPIRED
  - `txnId` (string)
  - `authResult` (string)
  - `message` (string)
  - `accounts` (object[])
- `400`: Bad Request (request validation failed): Invalid Transaction Id; Invalid Scope; Invalid AuthMethod
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error: Unclassified Authentication Failure (generic)
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "authResult": "success",
  "message": "Email address is now successfully linked to your Account",
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>"
    }
  ]
}
```


---

# After ABHA creation - get ABHA address suggestions

`GET /abha/api/v3/enrollment/enrol/suggestion`

**Endpoint:** `GET /abha/api/v3/enrollment/enrol/suggestion`

**Flow:** **Create ABHA - Face Authentication** - step 8 of 9
- Previous: *After ABHA creation - verify email OTP (optional)*
- Next: *After ABHA creation - create ABHA address*

---

This API endpoint is used to provide suggestions for ABHA addresses based on the user’s personal information. It helps users find suitable ABHA addresses by generating a list of suggestions. This is particularly useful during the ABHA enrolment process to ensure that users can choose an appropriate and unique ABHA address.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/suggestion \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TRANSACTION_ID: {{txnId}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TRANSACTION_ID` (string, required): Transaction ID from the ABHA creation response.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it refers to the successful operation of the Suggestion API, suggestions for ABHA addresses based on the user’s personal information.
  - `txnId` (string)
  - `abhaAddressList` (string[])
- `400`: The 400 response code indicates a bad request. In this context, it refers to various errors encountered during the operation of the Suggestion API. **Types of Suggestion API Errors:** **Abha Address - Invalid Transaction Id:** This error occurs when the transaction ID provided in the request is invalid. The transaction ID is essential for tracking the request and ensuring that the correct information is processed.. **Abha Address - Invalid Preferred Flag:** This error occurs when the preferred flag provided in the request is invalid. The preferred flag indicates the user’s preference for the suggested ABHA address.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, This error occurs when the transaction ID provided in the request is invalid. The transaction ID is essential for tracking the request and ensuring that the correct information is processed. An invalid transaction ID means the server cannot verify the request, leading to a failure in generating ABHA address suggestions.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "abhaAddressList": [
    "<ABHA_ADDRESS>",
    "<ABHA_ADDRESS>",
    "... 11 more of the same shape"
  ]
}
```


---

# After ABHA creation - create ABHA address

`POST /abha/api/v3/enrollment/enrol/abha-address`

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/abha-address`

**Flow:** **Create ABHA - Face Authentication** - step 9 of 9
- Previous: *After ABHA creation - get ABHA address suggestions*
- Next: none (last call of this flow)

---

This API endpoint is used to enrol a new ABHA address. It allows users to create a unique ABHA address that can be used for accessing and managing their health records. The endpoint ensures that the provided ABHA address is unique and valid..

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/abha-address \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "{{txnId}}",
  "abhaAddress": "{{ABHA Address}}",
  "preferred": 1
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `txnId` (string, required): The transaction ID returned by the previous call in this flow.
- `abhaAddress` (string, required): The ABHA address chosen for the account, without the @ suffix.
- `preferred` (integer, required): 1 to make this the preferred ABHA address of the account, 0 otherwise.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it refers to the successful operation of the Enroll ABHA Address API.
  - `txnId` (string)
  - `abhaAddress` (string)
  - `preferred` (integer)
- `400`: The 400 response code indicates a bad request. In this context, it refers to various errors encountered during the operation of the Suggestion API. **Types of Suggestion API Errors:** **Invalid Preferred Flag:** This error occurs when the transaction ID provided in the request is invalid. The transaction ID is essential for tracking the request and ensuring that the correct information is processed. An invalid transaction ID means the server cannot verify the request, leading to a failure in enrolling the ABHA address. . **Invalid Transaction Id:** This error occurs when the preferred flag provided in the request is invalid. The preferred flag indicates the user’s preference for the suggested ABHA address. An invalid preferred flag means the server cannot process the user’s preference correctly, leading to a failure in enrolling the ABHA address.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `preferred` (string)
  - `timestamp` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, it refers to the lack of proper authentication during the operation of the Invalid Credentials.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "healthIdNumber": "<ABHA_NUMBER>",
  "preferredAbhaAddress": "<ABHA_ADDRESS>"
}
```


---

# Create ABHA - Aadhaar fingerprint (bio)

`POST /abha/api/v3/enrollment/enrol/byAadhaar`

Creates an ABHA number by authenticating the Aadhaar holder's fingerprint. The PID block is captured with a UIDAI-registered fingerprint RD device. The response contains the ABHA profile and `tokens.token` (user X-token).

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/byAadhaar`

**Flow:** **Create ABHA - Fingerprint** - step 1 of 7
- Previous: none (first call of this flow)
- Next: *After ABHA creation - send OTP to verify mobile (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| REQUEST-ID | yes | Unique UUID for every request. |
| Benefit-Name | no | **Applicable for user who is enrolling via Benefit Program.** |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["bio"]` | yes | Authentication method used in this step. |
| `authData.bio` | object | yes | Fingerprint authentication block. |
| `authData.bio.aadhaar` | string | yes | Aadhaar number, RSA-encrypted. |
| `authData.bio.fingerPrintAuthPid` | string | yes | Base64 PID block captured from a registered fingerprint RD device. |
| `authData.bio.mobile` | string | no | Mobile number to be linked with the ABHA (plain, 10 digits). |
| `consent` | object | yes | Consent captured from the user for ABHA enrolment. |
| `consent.code` | string | yes | Consent code. Use `ABHA-enrollment`. |
| `consent.version` | string | yes | Consent version. Use `1.4`. |

> **Note:** The Postman collection (Create ABHA - Fingerprint 3.1) sends `authMethods: ["OTP"]`. This spec uses `["bio"]`; confirm with NHA.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/byAadhaar \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "authData": {
    "authMethods": [
      "bio"
    ],
    "bio": {
      "aadhaar": "{{encrypted aadhaar number}}",
      "fingerPrintAuthPid": "{{fingerPrintAuthPid}}",
      "mobile": "{{mobile number}}"
    }
  },
  "consent": {
    "code": "abha-enrollment",
    "version": "1.4"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `BENEFIT_NAME` (string): **Applicable for user who is enrolling via Benefit Program.**

## Body

- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.bio` (object, required): Fingerprint authentication block.
- `authData.bio.aadhaar` (string, required): Aadhaar number, RSA-encrypted.
- `authData.bio.fingerPrintAuthPid` (string, required): Base64 PID block captured from a registered fingerprint RD device.
- `authData.bio.mobile` (string): Mobile number to be linked with the ABHA (plain, 10 digits).
- `consent` (object, required): Consent captured from the user for ABHA enrolment.
- `consent.code` (string, required): Consent code. Use `abha-enrollment`.
- `consent.version` (string, required): Consent version. Use `1.4`.

## Responses

- `200`: Success: Create ABHA via Fingerprint - Positive Flow
  - `message` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `ABHAProfile` (object)
  - `ABHAProfile.firstName` (string)
  - `ABHAProfile.middleName` (string)
  - `ABHAProfile.lastName` (string)
  - `ABHAProfile.dob` (string)
  - `ABHAProfile.gender` (string)
  - `ABHAProfile.mobile` (string)
  - `ABHAProfile.phrAddress` (string[])
  - `ABHAProfile.districtCode` (string)
  - `ABHAProfile.stateCode` (string)
  - `ABHAProfile.abhaType` (string)
  - `ABHAProfile.stateName` (string)
  - `ABHAProfile.districtName` (string)
  - `ABHAProfile.ABHANumber` (string)
  - `ABHAProfile.abhaStatus` (string)
  - `isNew` (boolean)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Aadhaar Bio-Invalid Benefit Name
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `message` (string)
  - `timestamp` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure): Aadhaar Bio-Invalid certificate
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "message": "Account created successfully",
  "txnId": "b764e218-72b7-4bd7-a11e-2c9f2880fd61",
  "tokens": {
    "token": "<TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<TOKEN>",
    "refreshExpiresIn": 1296000
  },
  "ABHAProfile": {
    "firstName": "Username",
    "middleName": "",
    "lastName": "<NAME>",
    "dob": "<DOB>",
    "gender": "F",
    "photo": "",
    "mobile": "******0903",
    "email": null,
    "phrAddress": [
      "<ABHA_ADDRESS>"
    ],
    "districtCode": "490",
    "stateCode": "27",
    "abhaType": "CHILD",
    "stateName": "Maharashtra",
    "districtName": "<ADDRESS>",
    "ABHANumber": "<ABHA_NUMBER>",
    "abhaStatus": "ACTIVE"
  },
  "isNew": true
}
```


---

# After ABHA creation - send OTP to verify mobile (optional)

`POST /abha/api/v3/enrollment/request/otp`

Optional, called after the ABHA is created. Needed only when the `mobile` sent in the create-ABHA call is **not** the Aadhaar-linked mobile. ABDM sends an OTP to that mobile number so it can be linked to the ABHA. Send the `txnId` from the ABHA creation response.

**Endpoint:** `POST /abha/api/v3/enrollment/request/otp`

**Flow:** **Create ABHA - Fingerprint** - step 2 of 7
- Previous: *Create ABHA - Aadhaar fingerprint (bio)*
- Next: *After ABHA creation - verify mobile OTP (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `scope` | `["ABHA-enrol", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"mobile"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "{{txnId}}",
  "scope": [
    "abha-enrol",
    "mobile-verify"
  ],
  "loginHint": "mobile",
  "loginId": "{{encrypted mobileNumber}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: mobile.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.

## Responses

- `200`: Success: Mobile Update - Send OTP- positive flow
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): Mobile Update - Send OTP-Invalid Scope; Mobile Update - Send OTP-Invalid LoginId; Mobile Update - Send OTP-Invalid Login Hint
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Mobile Update - Send OTP-Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-107h6b18a5fa",
  "message": "OTP sent to mobile number ending with ******0903"
}
```


---

# After ABHA creation - verify mobile OTP (optional)

`POST /abha/api/v3/enrollment/auth/byAbdm`

Verifies the OTP sent by *After ABHA creation - send OTP to verify mobile (optional)* and links the mobile number to the newly created ABHA.

**Endpoint:** `POST /abha/api/v3/enrollment/auth/byAbdm`

**Flow:** **Create ABHA - Fingerprint** - step 3 of 7
- Previous: *After ABHA creation - send OTP to verify mobile (optional)*
- Next: *After ABHA creation - send OTP to verify email (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-enrol", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/auth/byAbdm \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-enrol",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted otp}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Mobile Update - Verify OTP-positive flow; Mobile Update - Verify OTP-OTP EXPIRED
  - `txnId` (string)
  - `authResult` (string)
  - `message` (string)
  - `accounts` (object[])
- `400`: Bad Request (request validation failed): Mobile Update - Verify OTP; Invalid Transaction Id; Invalid Scope; Invalid AuthMethod
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error: Mobile Update - Verify OTP-Invalid access token
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "authResult": "success",
  "message": "Mobile number is now successfully linked to your Account",
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>"
    }
  ]
}
```


---

# After ABHA creation - send OTP to verify email (optional)

`POST /abha/api/v3/enrollment/request/otp`

Optional. Sends an ABDM OTP to an email address so it can be linked to the newly created ABHA. Send the `txnId` from the previous enrolment step.

**Endpoint:** `POST /abha/api/v3/enrollment/request/otp`

**Flow:** **Create ABHA - Fingerprint** - step 4 of 7
- Previous: *After ABHA creation - verify mobile OTP (optional)*
- Next: *After ABHA creation - verify email OTP (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `scope` | `["ABHA-enrol", "email-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"email"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "{{txnId}}",
  "scope": [
    "abha-enrol",
    "email-verify"
  ],
  "loginHint": "email",
  "loginId": "{{encrypted email}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: email.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.

## Responses

- `200`: Success: Email Verify via OTP-positive flow
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): ABHA Verify via Email-Invalid scope; ABHA Verify via Email-Invalid LoginId; ABHA Verify via Email-Invalid Login Hint
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Email verify via  OTP-Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "message": "OTP sent to email address ending with *************<EMAIL>"
}
```


---

# After ABHA creation - verify email OTP (optional)

`POST /abha/api/v3/enrollment/auth/byAbdm`

Verifies the OTP sent by *After ABHA creation - send OTP to verify email (optional)* and links the email address to the newly created ABHA.

**Endpoint:** `POST /abha/api/v3/enrollment/auth/byAbdm`

**Flow:** **Create ABHA - Fingerprint** - step 5 of 7
- Previous: *After ABHA creation - send OTP to verify email (optional)*
- Next: *After ABHA creation - get ABHA address suggestions*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-enrol", "email-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/auth/byAbdm \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-enrol",
    "email-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted otp}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Email Update - Verify OTP-positive flow; Email Update - Verify OTP-OTP EXPIRED
  - `txnId` (string)
  - `authResult` (string)
  - `message` (string)
  - `accounts` (object[])
- `400`: Bad Request (request validation failed): Invalid Transaction Id; Invalid Scope; Invalid AuthMethod
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error: Unclassified Authentication Failure (generic)
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "authResult": "success",
  "message": "Email address is now successfully linked to your Account",
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>"
    }
  ]
}
```


---

# After ABHA creation - get ABHA address suggestions

`GET /abha/api/v3/enrollment/enrol/suggestion`

**Endpoint:** `GET /abha/api/v3/enrollment/enrol/suggestion`

**Flow:** **Create ABHA - Fingerprint** - step 6 of 7
- Previous: *After ABHA creation - verify email OTP (optional)*
- Next: *After ABHA creation - create ABHA address*

---

This API endpoint is used to provide suggestions for ABHA addresses based on the user’s personal information. It helps users find suitable ABHA addresses by generating a list of suggestions. This is particularly useful during the ABHA enrolment process to ensure that users can choose an appropriate and unique ABHA address.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/suggestion \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TRANSACTION_ID: {{txnId}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TRANSACTION_ID` (string, required): Transaction ID from the ABHA creation response.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it refers to the successful operation of the Suggestion API, suggestions for ABHA addresses based on the user’s personal information.
  - `txnId` (string)
  - `abhaAddressList` (string[])
- `400`: The 400 response code indicates a bad request. In this context, it refers to various errors encountered during the operation of the Suggestion API. **Types of Suggestion API Errors:** **Abha Address - Invalid Transaction Id:** This error occurs when the transaction ID provided in the request is invalid. The transaction ID is essential for tracking the request and ensuring that the correct information is processed.. **Abha Address - Invalid Preferred Flag:** This error occurs when the preferred flag provided in the request is invalid. The preferred flag indicates the user’s preference for the suggested ABHA address.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, This error occurs when the transaction ID provided in the request is invalid. The transaction ID is essential for tracking the request and ensuring that the correct information is processed. An invalid transaction ID means the server cannot verify the request, leading to a failure in generating ABHA address suggestions.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "abhaAddressList": [
    "<ABHA_ADDRESS>",
    "<ABHA_ADDRESS>",
    "... 11 more of the same shape"
  ]
}
```


---

# After ABHA creation - create ABHA address

`POST /abha/api/v3/enrollment/enrol/abha-address`

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/abha-address`

**Flow:** **Create ABHA - Fingerprint** - step 7 of 7
- Previous: *After ABHA creation - get ABHA address suggestions*
- Next: none (last call of this flow)

---

This API endpoint is used to enrol a new ABHA address. It allows users to create a unique ABHA address that can be used for accessing and managing their health records. The endpoint ensures that the provided ABHA address is unique and valid..

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/abha-address \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "{{txnId}}",
  "abhaAddress": "{{ABHA Address}}",
  "preferred": 1
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `txnId` (string, required): The transaction ID returned by the previous call in this flow.
- `abhaAddress` (string, required): The ABHA address chosen for the account, without the @ suffix.
- `preferred` (integer, required): 1 to make this the preferred ABHA address of the account, 0 otherwise.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it refers to the successful operation of the Enroll ABHA Address API.
  - `txnId` (string)
  - `abhaAddress` (string)
  - `preferred` (integer)
- `400`: The 400 response code indicates a bad request. In this context, it refers to various errors encountered during the operation of the Suggestion API. **Types of Suggestion API Errors:** **Invalid Preferred Flag:** This error occurs when the transaction ID provided in the request is invalid. The transaction ID is essential for tracking the request and ensuring that the correct information is processed. An invalid transaction ID means the server cannot verify the request, leading to a failure in enrolling the ABHA address. . **Invalid Transaction Id:** This error occurs when the preferred flag provided in the request is invalid. The preferred flag indicates the user’s preference for the suggested ABHA address. An invalid preferred flag means the server cannot process the user’s preference correctly, leading to a failure in enrolling the ABHA address.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `preferred` (string)
  - `timestamp` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, it refers to the lack of proper authentication during the operation of the Invalid Credentials.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "healthIdNumber": "<ABHA_NUMBER>",
  "preferredAbhaAddress": "<ABHA_ADDRESS>"
}
```


---

# Create ABHA - Aadhaar IRIS

`POST /abha/api/v3/enrollment/enrol/byAadhaar`

Creates an ABHA number by authenticating the Aadhaar holder's IRIS. The PID block is captured with a UIDAI-registered IRIS RD device. The response contains the ABHA profile and `tokens.token` (user X-token).

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/byAadhaar`

**Flow:** **Create ABHA - IRIS** - step 1 of 7
- Previous: none (first call of this flow)
- Next: *After ABHA creation - send OTP to verify mobile (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| REQUEST-ID | yes | Unique UUID for every request. |
| Benefit-Name | no | **Applicable for user who is enrolling via Benefit Program.** |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["iris"]` | yes | Authentication method used in this step. |
| `authData.iris` | object | yes | IRIS authentication block. |
| `authData.iris.aadhaar` | string | yes | Aadhaar number, RSA-encrypted. |
| `authData.iris.pid` | string | yes | Base64 PID block captured from a registered IRIS RD device. |
| `authData.iris.mobile` | string | no | Mobile number to be linked with the ABHA (plain, 10 digits). |
| `consent` | object | yes | Consent captured from the user for ABHA enrolment. |
| `consent.code` | string | yes | Consent code. Use `ABHA-enrollment`. |
| `consent.version` | string | yes | Consent version. Use `1.4`. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/byAadhaar \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "authData": {
    "authMethods": [
      "iris"
    ],
    "iris": {
      "aadhaar": "{{encrypted aadhaar number}}",
      "pid": "{{PID}}",
      "mobile": "{{mobile number}}"
    }
  },
  "consent": {
    "code": "abha-enrollment",
    "version": "1.4"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `BENEFIT_NAME` (string): **Applicable for user who is enrolling via Benefit Program.**

## Body

- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.iris` (object, required): IRIS authentication block.
- `authData.iris.aadhaar` (string, required): Aadhaar number, RSA-encrypted.
- `authData.iris.pid` (string, required): Base64 PID block captured from a registered IRIS RD device.
- `authData.iris.mobile` (string): Mobile number to be linked with the ABHA (plain, 10 digits).
- `consent` (object, required): Consent captured from the user for ABHA enrolment.
- `consent.code` (string, required): Consent code. Use `abha-enrollment`.
- `consent.version` (string, required): Consent version. Use `1.4`.

## Responses

- `200`: Success: Create ABHA via IRIS - Positive Flow
  - `message` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `ABHAProfile` (object)
  - `ABHAProfile.firstName` (string)
  - `ABHAProfile.middleName` (string)
  - `ABHAProfile.lastName` (string)
  - `ABHAProfile.dob` (string)
  - `ABHAProfile.gender` (string)
  - `ABHAProfile.mobile` (string)
  - `ABHAProfile.phrAddress` (string[])
  - `ABHAProfile.districtCode` (string)
  - `ABHAProfile.stateCode` (string)
  - `ABHAProfile.abhaType` (string)
  - `ABHAProfile.stateName` (string)
  - `ABHAProfile.districtName` (string)
  - `ABHAProfile.ABHANumber` (string)
  - `ABHAProfile.abhaStatus` (string)
  - `isNew` (boolean)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Benefit Name (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `message` (string)
  - `timestamp` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "message": "Account created successfully",
  "txnId": "b764e218-72b7-4bd7-a11e-2c9f2880fd61",
  "tokens": {
    "token": "<TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<TOKEN>",
    "refreshExpiresIn": 1296000
  },
  "ABHAProfile": {
    "firstName": "Username",
    "middleName": "",
    "lastName": "<NAME>",
    "dob": "<DOB>",
    "gender": "F",
    "photo": "",
    "mobile": "******0903",
    "email": null,
    "phrAddress": [
      "<ABHA_ADDRESS>"
    ],
    "districtCode": "490",
    "stateCode": "27",
    "abhaType": "CHILD",
    "stateName": "Maharashtra",
    "districtName": "<ADDRESS>",
    "ABHANumber": "<ABHA_NUMBER>",
    "abhaStatus": "ACTIVE"
  },
  "isNew": true
}
```


---

# After ABHA creation - send OTP to verify mobile (optional)

`POST /abha/api/v3/enrollment/request/otp`

Optional, called after the ABHA is created. Needed only when the `mobile` sent in the create-ABHA call is **not** the Aadhaar-linked mobile. ABDM sends an OTP to that mobile number so it can be linked to the ABHA. Send the `txnId` from the ABHA creation response.

**Endpoint:** `POST /abha/api/v3/enrollment/request/otp`

**Flow:** **Create ABHA - IRIS** - step 2 of 7
- Previous: *Create ABHA - Aadhaar IRIS*
- Next: *After ABHA creation - verify mobile OTP (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `scope` | `["ABHA-enrol", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"mobile"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "{{txnId}}",
  "scope": [
    "abha-enrol",
    "mobile-verify"
  ],
  "loginHint": "mobile",
  "loginId": "{{encrypted mobileNumber}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: mobile.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.

## Responses

- `200`: Success: Mobile Update - Send OTP- positive flow
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): Mobile Update - Send OTP-Invalid Scope; Mobile Update - Send OTP-Invalid LoginId; Mobile Update - Send OTP-Invalid Login Hint
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Mobile Update - Send OTP-Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-107h6b18a5fa",
  "message": "OTP sent to mobile number ending with ******0903"
}
```


---

# After ABHA creation - verify mobile OTP (optional)

`POST /abha/api/v3/enrollment/auth/byAbdm`

Verifies the OTP sent by *After ABHA creation - send OTP to verify mobile (optional)* and links the mobile number to the newly created ABHA.

**Endpoint:** `POST /abha/api/v3/enrollment/auth/byAbdm`

**Flow:** **Create ABHA - IRIS** - step 3 of 7
- Previous: *After ABHA creation - send OTP to verify mobile (optional)*
- Next: *After ABHA creation - send OTP to verify email (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-enrol", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/auth/byAbdm \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-enrol",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted otp}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Mobile Update - Verify OTP-positive flow; Mobile Update - Verify OTP-OTP EXPIRED
  - `txnId` (string)
  - `authResult` (string)
  - `message` (string)
  - `accounts` (object[])
- `400`: Bad Request (request validation failed): Mobile Update - Verify OTP; Invalid Transaction Id; Invalid Scope; Invalid AuthMethod
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error: Mobile Update - Verify OTP-Invalid access token
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "authResult": "success",
  "message": "Mobile number is now successfully linked to your Account",
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>"
    }
  ]
}
```


---

# After ABHA creation - send OTP to verify email (optional)

`POST /abha/api/v3/enrollment/request/otp`

Optional. Sends an ABDM OTP to an email address so it can be linked to the newly created ABHA. Send the `txnId` from the previous enrolment step.

**Endpoint:** `POST /abha/api/v3/enrollment/request/otp`

**Flow:** **Create ABHA - IRIS** - step 4 of 7
- Previous: *After ABHA creation - verify mobile OTP (optional)*
- Next: *After ABHA creation - verify email OTP (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `scope` | `["ABHA-enrol", "email-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"email"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "{{txnId}}",
  "scope": [
    "abha-enrol",
    "email-verify"
  ],
  "loginHint": "email",
  "loginId": "{{encrypted email}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: email.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.

## Responses

- `200`: Success: Email Verify via OTP-positive flow
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): ABHA Verify via Email-Invalid scope; ABHA Verify via Email-Invalid LoginId; ABHA Verify via Email-Invalid Login Hint
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Email verify via  OTP-Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "message": "OTP sent to email address ending with *************<EMAIL>"
}
```


---

# After ABHA creation - verify email OTP (optional)

`POST /abha/api/v3/enrollment/auth/byAbdm`

Verifies the OTP sent by *After ABHA creation - send OTP to verify email (optional)* and links the email address to the newly created ABHA.

**Endpoint:** `POST /abha/api/v3/enrollment/auth/byAbdm`

**Flow:** **Create ABHA - IRIS** - step 5 of 7
- Previous: *After ABHA creation - send OTP to verify email (optional)*
- Next: *After ABHA creation - get ABHA address suggestions*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-enrol", "email-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/auth/byAbdm \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-enrol",
    "email-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted otp}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Email Update - Verify OTP-positive flow; Email Update - Verify OTP-OTP EXPIRED
  - `txnId` (string)
  - `authResult` (string)
  - `message` (string)
  - `accounts` (object[])
- `400`: Bad Request (request validation failed): Invalid Transaction Id; Invalid Scope; Invalid AuthMethod
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error: Unclassified Authentication Failure (generic)
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "authResult": "success",
  "message": "Email address is now successfully linked to your Account",
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>"
    }
  ]
}
```


---

# After ABHA creation - get ABHA address suggestions

`GET /abha/api/v3/enrollment/enrol/suggestion`

**Endpoint:** `GET /abha/api/v3/enrollment/enrol/suggestion`

**Flow:** **Create ABHA - IRIS** - step 6 of 7
- Previous: *After ABHA creation - verify email OTP (optional)*
- Next: *After ABHA creation - create ABHA address*

---

This API endpoint is used to provide suggestions for ABHA addresses based on the user’s personal information. It helps users find suitable ABHA addresses by generating a list of suggestions. This is particularly useful during the ABHA enrolment process to ensure that users can choose an appropriate and unique ABHA address.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/suggestion \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TRANSACTION_ID: {{txnId}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TRANSACTION_ID` (string, required): Transaction ID from the ABHA creation response.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it refers to the successful operation of the Suggestion API, suggestions for ABHA addresses based on the user’s personal information.
  - `txnId` (string)
  - `abhaAddressList` (string[])
- `400`: The 400 response code indicates a bad request. In this context, it refers to various errors encountered during the operation of the Suggestion API. **Types of Suggestion API Errors:** **Abha Address - Invalid Transaction Id:** This error occurs when the transaction ID provided in the request is invalid. The transaction ID is essential for tracking the request and ensuring that the correct information is processed.. **Abha Address - Invalid Preferred Flag:** This error occurs when the preferred flag provided in the request is invalid. The preferred flag indicates the user’s preference for the suggested ABHA address.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, This error occurs when the transaction ID provided in the request is invalid. The transaction ID is essential for tracking the request and ensuring that the correct information is processed. An invalid transaction ID means the server cannot verify the request, leading to a failure in generating ABHA address suggestions.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "abhaAddressList": [
    "<ABHA_ADDRESS>",
    "<ABHA_ADDRESS>",
    "... 11 more of the same shape"
  ]
}
```


---

# After ABHA creation - create ABHA address

`POST /abha/api/v3/enrollment/enrol/abha-address`

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/abha-address`

**Flow:** **Create ABHA - IRIS** - step 7 of 7
- Previous: *After ABHA creation - get ABHA address suggestions*
- Next: none (last call of this flow)

---

This API endpoint is used to enrol a new ABHA address. It allows users to create a unique ABHA address that can be used for accessing and managing their health records. The endpoint ensures that the provided ABHA address is unique and valid..

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/abha-address \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "{{txnId}}",
  "abhaAddress": "{{ABHA Address}}",
  "preferred": 1
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `txnId` (string, required): The transaction ID returned by the previous call in this flow.
- `abhaAddress` (string, required): The ABHA address chosen for the account, without the @ suffix.
- `preferred` (integer, required): 1 to make this the preferred ABHA address of the account, 0 otherwise.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it refers to the successful operation of the Enroll ABHA Address API.
  - `txnId` (string)
  - `abhaAddress` (string)
  - `preferred` (integer)
- `400`: The 400 response code indicates a bad request. In this context, it refers to various errors encountered during the operation of the Suggestion API. **Types of Suggestion API Errors:** **Invalid Preferred Flag:** This error occurs when the transaction ID provided in the request is invalid. The transaction ID is essential for tracking the request and ensuring that the correct information is processed. An invalid transaction ID means the server cannot verify the request, leading to a failure in enrolling the ABHA address. . **Invalid Transaction Id:** This error occurs when the preferred flag provided in the request is invalid. The preferred flag indicates the user’s preference for the suggested ABHA address. An invalid preferred flag means the server cannot process the user’s preference correctly, leading to a failure in enrolling the ABHA address.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `preferred` (string)
  - `timestamp` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, it refers to the lack of proper authentication during the operation of the Invalid Credentials.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "healthIdNumber": "<ABHA_NUMBER>",
  "preferredAbhaAddress": "<ABHA_ADDRESS>"
}
```


---

# Search ABHA by mobile

`POST /abha/api/v3/profile/account/abha/search`

**Endpoint:** `POST /abha/api/v3/profile/account/abha/search`

**Flow:** **Find ABHA - Aadhaar OTP** - step 1 of 3
- Previous: none (first call of this flow)
- Next: *Find ABHA via Aadhaar OTP - send OTP*

---

This API endpoint is used to search for ABHA (Ayushman Bharat Health Account) profiles. It allows users to retrieve information about their ABHA profiles using mobile numbers. This is essential for verifying the user’s identity and ensuring secure access to their ABHA profile.

 **Note:** You need to use the Encryption API first. Only an RSA-encrypted mobile number should be in the request body.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/abha/search \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "search-abha"
  ],
  "mobile": "{{rsaMobileEncryptionOutput}}"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): The scope of the request. Use search-abha.
- `mobile` (string, required): The mobile number, encrypted with the public key from GET /abha/api/v3/profile/public/certificate.

## Responses

- `200`: Successfully retrieved ABHA details.
- `400`: Invalid mobile number.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `mobile` (string)
  - `timestamp` (string)
- `401`: Missing Credentials.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: User not found.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
[
  {
    "txnId": "d5b1fb36-e0be-401d-b4cf-cc71c5aca98a",
    "ABHA": [
      {
        "index": 1,
        "ABHANumber": "xx-xxxx-xxxx-XX31",
        "name": "<NAME>",
        "gender": "F",
        "kycVerified": "true",
        "authMethods": [
          "AADHAAR_OTP",
          "MOBILE_OTP",
          "... 2 more of the same shape"
        ]
      }
    ]
  }
]
```


---

# Find ABHA via Aadhaar OTP - send OTP

`POST /abha/api/v3/profile/login/request/otp`

Sends an Aadhaar OTP for the ABHA account picked from *Search ABHA by mobile*. Send `loginHint: index`, the RSA-encrypted `index` of the chosen account, and the `txnId` returned by the search.

**Endpoint:** `POST /abha/api/v3/profile/login/request/otp`

**Flow:** **Find ABHA - Aadhaar OTP** - step 2 of 3
- Previous: *Search ABHA by mobile*
- Next: *Find ABHA via Aadhaar OTP - verify OTP*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "search-ABHA", "Aadhaar-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"index"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"Aadhaar"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |
| `txnId` | string | yes | Transaction ID returned by the previous step of this flow. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "search-abha",
    "aadhaar-verify"
  ],
  "loginHint": "index",
  "loginId": "{{rsaIndexEncryptionOutput}}",
  "otpSystem": "aadhaar",
  "txnId": "{{searchTxnId}}"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: index.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: aadhaar.
- `txnId` (string, required): Transaction ID returned by the previous step of this flow.

## Responses

- `200`: Success: Find ABHA via Aadhaar OTP - Send OTP
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found: Resource not found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `timestamp` (string)
  - `path` (string)
  - `description` (string)
  - `error` (string)
  - `requestId` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "86b3d4c8-114e-4fd1-8604-93a684730827",
  "message": "OTP sent to Aadhaar registered mobile number ending with ******0903"
}
```


---

# Find ABHA via Aadhaar OTP - verify OTP

`POST /abha/api/v3/profile/login/verify`

Verifies the Aadhaar OTP for the chosen account. Returns the ABHA details and the user token.

**Endpoint:** `POST /abha/api/v3/profile/login/verify`

**Flow:** **Find ABHA - Aadhaar OTP** - step 3 of 3
- Previous: *Find ABHA via Aadhaar OTP - send OTP*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted OTP}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Find ABHA via Aadhaar OTP - Positive flow
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)
  - `accounts.profilePhoto` (string)
- `400`: Bad Request (request validation failed): Invalid Transaction Id
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `404`: Not Found: User Not Found; Resource Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "dcc22def-8102-4c9a-a36e-15743556fdc4",
  "authResult": "success",
  "message": "OTP verified successfully",
  "token": "<TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "refreshExpiresIn": 1296000,
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "status": "ACTIVE",
      "profilePhoto": "<BASE64_PHOTO>"
    }
  ]
}
```


---

# Search ABHA by mobile

`POST /abha/api/v3/profile/account/abha/search`

**Endpoint:** `POST /abha/api/v3/profile/account/abha/search`

**Flow:** **Find ABHA - Face** - step 1 of 4
- Previous: none (first call of this flow)
- Next: *Find ABHA via Face - send authentication request*

---

This API endpoint is used to search for ABHA (Ayushman Bharat Health Account) profiles. It allows users to retrieve information about their ABHA profiles using mobile numbers. This is essential for verifying the user’s identity and ensuring secure access to their ABHA profile.

 **Note:** You need to use the Encryption API first. Only an RSA-encrypted mobile number should be in the request body.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/abha/search \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "search-abha"
  ],
  "mobile": "{{rsaMobileEncryptionOutput}}"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): The scope of the request. Use search-abha.
- `mobile` (string, required): The mobile number, encrypted with the public key from GET /abha/api/v3/profile/public/certificate.

## Responses

- `200`: Successfully retrieved ABHA details.
- `400`: Invalid mobile number.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `mobile` (string)
  - `timestamp` (string)
- `401`: Missing Credentials.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: User not found.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
[
  {
    "txnId": "d5b1fb36-e0be-401d-b4cf-cc71c5aca98a",
    "ABHA": [
      {
        "index": 1,
        "ABHANumber": "xx-xxxx-xxxx-XX31",
        "name": "<NAME>",
        "gender": "F",
        "kycVerified": "true",
        "authMethods": [
          "AADHAAR_OTP",
          "MOBILE_OTP",
          "... 2 more of the same shape"
        ]
      }
    ]
  }
]
```


---

# Find ABHA via Face - send authentication request

`POST /abha/api/v3/profile/login/request/otp`

Starts face authentication for the ABHA account picked from *Search ABHA by mobile*. Send `loginHint: index`, the RSA-encrypted `index` of the chosen account, and the `txnId` returned by the search. Then poll *Face auth - capture PID / track status* until `COMPLETE`.

**Endpoint:** `POST /abha/api/v3/profile/login/request/otp`

**Flow:** **Find ABHA - Face** - step 2 of 4
- Previous: *Search ABHA by mobile*
- Next: *Face auth - capture PID / track status*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "search-ABHA", "Aadhaar-face-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"index"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"Aadhaar"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |
| `txnId` | string | yes | Transaction ID returned by the previous step of this flow. |

> **Note:** The Postman collection sends scope `["ABHA-login","search-ABHA","face-auth"]` for this step. This spec uses `Aadhaar-face-verify`; confirm with NHA.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "search-abha",
    "aadhaar-face-verify"
  ],
  "loginHint": "index",
  "loginId": "{{rsaIndexEncryptionOutput}}",
  "otpSystem": "aadhaar",
  "txnId": "{{searchTxnId}}"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: index.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: aadhaar.
- `txnId` (string, required): Transaction ID returned by the previous step of this flow.

## Responses

- `200`: Success: Find ABHA Via Biometric (Face) - Send Face Authentication Request; Positive flow
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Biometric is not allowed
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found: Resource not found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `timestamp` (string)
  - `path` (string)
  - `description` (string)
  - `error` (string)
  - `requestId` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "message": "Face authentication request successfully sent."
}
```


---

# Face auth - capture PID / track status

`POST /abha/api/v3/enrollment/enrol/capturePID`

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/capturePID`

**Flow:** **Find ABHA - Face** - step 3 of 4
- Previous: *Find ABHA via Face - send authentication request*
- Next: *Find ABHA via Face - verify*

> **Note:** The original description below says the next step is ABHA enrolment. In this flow the next step is the verify API named above.

---

This API is designed to verify the status of a transaction ID that was generated during the invocation of the `auth/init` API. It serves as a follow-up mechanism to ensure that the transaction is still valid, active, and has not expired or been invalidated.

 Wait for PID capture and submission confirmation from the ABHA App. The response of the API will return status of that transactionId. It can be either **PENDING,VERIFIED,FAILED,COMPLETE.**

 Once the status in the response of this API is returned as **COMPLETE**, it indicates that the face authentication process has been successfully completed. At this stage, the next step is to invoke the `/enrollment/enrol/byAadhaar` (You can find this API in ABHA ENROLLMENT Via Aadhaar section) API to proceed further.

User can poll the `/capturePID` API in every 5 - 10 seconds interval to check the status of face capture process or alternatively skip this step and call the `/enrollment/enrol/byAadhaar` API once they see the PID submission success message in the ABHA app.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/capturePID \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-enrol",
    "face-verify"
  ],
  "txnId": "ea1dc7aa-d7c3-40ab-bee8-84c6f1eb90fa"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): The scopes of the request, which name the flow this call belongs to.
- `txnId` (string, required): The transaction ID returned by the previous call in this flow.

## Responses

- `200`: The 200 response code indicates a successful request. The reponse of the API will return status of that transactionId. It can be either **PENDING,VERIFIED,FAILED,COMPLETE.**
  - `status` (string)
  - `message` (string)
- `400`: The 400 response code indicates a bad request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, it refers to the lack of proper authentication during the operation of the Invalid Credentials
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "status": "PENDING",
  "message": "Awaiting PID capture"
}
```


---

# Find ABHA via Face - verify

`POST /abha/api/v3/profile/login/verify`

Completes face authentication for the chosen account. Once *Face auth - capture PID / track status* reports `COMPLETE`, send the same `txnId` here (the body has no PID).

**Endpoint:** `POST /abha/api/v3/profile/login/verify`

**Flow:** **Find ABHA - Face** - step 4 of 4
- Previous: *Face auth - capture PID / track status*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-face-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["face_auth"]` | yes | Authentication method used in this step. |
| `authData.face` | object | yes | Face authentication block. |
| `authData.face.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-face-verify"
  ],
  "authData": {
    "authMethods": [
      "face_auth"
    ],
    "face": {
      "txnId": "{{txnId}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.face` (object, required): Face authentication block.
- `authData.face.txnId` (string, required): Transaction ID returned by the previous step of this flow.

## Responses

- `200`: Success: Positive flow
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)
  - `accounts.profilePhoto` (string)
- `400`: Bad Request (request validation failed): Invalid DTO; Invalid DTO (2); Invalid PID; Empty Body; Invalid TxnId; Invalid AuthMethod; Invalid AuthMethod (2)
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Authorization
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `404`: Not Found: Invalid URL
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure): Used PID; Expired PID; Used Bio PID; Another User PID; Biometric not matched
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object, required)
  - `error.code` (string, required): Consent code. Use `abha-enrollment`.
  - `error.message` (string, required)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "d17cb533-9bfa-40f5-a7bc-b84143516787",
  "authResult": "success",
  "message": "Aadhaar Face Authentication Success",
  "token": "<TOKEN>...",
  "expiresIn": 1800,
  "refreshToken": "<TOKEN>...",
  "refreshExpiresIn": 1296000,
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "status": "ACTIVE",
      "profilePhoto": "{{base64 profile photo}}",
      "mobileVerified": false
    }
  ]
}
```


---

# Search ABHA by mobile

`POST /abha/api/v3/profile/account/abha/search`

**Endpoint:** `POST /abha/api/v3/profile/account/abha/search`

**Flow:** **Find ABHA - Fingerprint** - step 1 of 3
- Previous: none (first call of this flow)
- Next: *Find ABHA via Fingerprint - send authentication request*

---

This API endpoint is used to search for ABHA (Ayushman Bharat Health Account) profiles. It allows users to retrieve information about their ABHA profiles using mobile numbers. This is essential for verifying the user’s identity and ensuring secure access to their ABHA profile.

 **Note:** You need to use the Encryption API first. Only an RSA-encrypted mobile number should be in the request body.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/abha/search \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "search-abha"
  ],
  "mobile": "{{rsaMobileEncryptionOutput}}"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): The scope of the request. Use search-abha.
- `mobile` (string, required): The mobile number, encrypted with the public key from GET /abha/api/v3/profile/public/certificate.

## Responses

- `200`: Successfully retrieved ABHA details.
- `400`: Invalid mobile number.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `mobile` (string)
  - `timestamp` (string)
- `401`: Missing Credentials.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: User not found.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
[
  {
    "txnId": "d5b1fb36-e0be-401d-b4cf-cc71c5aca98a",
    "ABHA": [
      {
        "index": 1,
        "ABHANumber": "xx-xxxx-xxxx-XX31",
        "name": "<NAME>",
        "gender": "F",
        "kycVerified": "true",
        "authMethods": [
          "AADHAAR_OTP",
          "MOBILE_OTP",
          "... 2 more of the same shape"
        ]
      }
    ]
  }
]
```


---

# Find ABHA via Fingerprint - send authentication request

`POST /abha/api/v3/profile/login/request/otp`

Starts fingerprint authentication for the ABHA account picked from *Search ABHA by mobile*. Send `loginHint: index`, the RSA-encrypted `index` of the chosen account, and the `txnId` returned by the search.

**Endpoint:** `POST /abha/api/v3/profile/login/request/otp`

**Flow:** **Find ABHA - Fingerprint** - step 2 of 3
- Previous: *Search ABHA by mobile*
- Next: *Find ABHA via Fingerprint - verify*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "search-ABHA", "Aadhaar-bio-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"index"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"Aadhaar"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |
| `txnId` | string | yes | Transaction ID returned by the previous step of this flow. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "search-abha",
    "aadhaar-bio-verify"
  ],
  "loginHint": "index",
  "loginId": "{{rsaIndexEncryptionOutput}}",
  "otpSystem": "aadhaar",
  "txnId": "{{searchTxnId}}"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: index.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: aadhaar.
- `txnId` (string, required): Transaction ID returned by the previous step of this flow.

## Responses

- `200`: Success: Find ABHA Via Biometric (Fingerprint) - Send Fingerprint Authentication Request
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found: Resource not found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `timestamp` (string)
  - `path` (string)
  - `description` (string)
  - `error` (string)
  - `requestId` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "message": "FingerPrint authentication request successfully sent."
}
```


---

# Find ABHA via Fingerprint - verify

`POST /abha/api/v3/profile/login/verify`

Completes fingerprint authentication for the chosen account. Send the `txnId` from *Find ABHA via Fingerprint - send authentication request* with the fingerprint PID.

**Endpoint:** `POST /abha/api/v3/profile/login/verify`

**Flow:** **Find ABHA - Fingerprint** - step 3 of 3
- Previous: *Find ABHA via Fingerprint - send authentication request*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-bio-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["bio"]` | yes | Authentication method used in this step. |
| `authData.bio` | object | yes | Fingerprint authentication block. |
| `authData.bio.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.bio.fingerPrintAuthPid` | string | yes | Base64 PID block captured from a registered fingerprint RD device. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-bio-verify"
  ],
  "authData": {
    "authMethods": [
      "bio"
    ],
    "bio": {
      "txnId": "{{txnId}}",
      "fingerPrintAuthPid": "{{fingerPrintAuthPid}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.bio` (object, required): Fingerprint authentication block.
- `authData.bio.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.bio.fingerPrintAuthPid` (string, required): Base64 PID block captured from a registered fingerprint RD device.

## Responses

- `200`: Success: Find ABHA via Fingerprint - Positive flow
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)
  - `accounts.profilePhoto` (string)
- `400`: Bad Request (request validation failed): Invalid Fingerprint PID
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `404`: Not Found: User Not Found; Resource Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "fe1c527e-1ab8-40c4-84d2-9eedb3378d39",
  "authResult": "success",
  "message": "BIO verified successfully",
  "token": "<TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "refreshExpiresIn": 1296000,
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "status": "ACTIVE",
      "profilePhoto": "<BASE64_PHOTO>"
    }
  ]
}
```


---

# Search ABHA by mobile

`POST /abha/api/v3/profile/account/abha/search`

**Endpoint:** `POST /abha/api/v3/profile/account/abha/search`

**Flow:** **Find ABHA - IRIS** - step 1 of 3
- Previous: none (first call of this flow)
- Next: *Find ABHA via IRIS - send authentication request*

---

This API endpoint is used to search for ABHA (Ayushman Bharat Health Account) profiles. It allows users to retrieve information about their ABHA profiles using mobile numbers. This is essential for verifying the user’s identity and ensuring secure access to their ABHA profile.

 **Note:** You need to use the Encryption API first. Only an RSA-encrypted mobile number should be in the request body.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/abha/search \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "search-abha"
  ],
  "mobile": "{{rsaMobileEncryptionOutput}}"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): The scope of the request. Use search-abha.
- `mobile` (string, required): The mobile number, encrypted with the public key from GET /abha/api/v3/profile/public/certificate.

## Responses

- `200`: Successfully retrieved ABHA details.
- `400`: Invalid mobile number.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `mobile` (string)
  - `timestamp` (string)
- `401`: Missing Credentials.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: User not found.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
[
  {
    "txnId": "d5b1fb36-e0be-401d-b4cf-cc71c5aca98a",
    "ABHA": [
      {
        "index": 1,
        "ABHANumber": "xx-xxxx-xxxx-XX31",
        "name": "<NAME>",
        "gender": "F",
        "kycVerified": "true",
        "authMethods": [
          "AADHAAR_OTP",
          "MOBILE_OTP",
          "... 2 more of the same shape"
        ]
      }
    ]
  }
]
```


---

# Find ABHA via IRIS - send authentication request

`POST /abha/api/v3/profile/login/request/otp`

Starts IRIS authentication for the ABHA account picked from *Search ABHA by mobile*. Send `loginHint: index`, the RSA-encrypted `index` of the chosen account, and the `txnId` returned by the search.

**Endpoint:** `POST /abha/api/v3/profile/login/request/otp`

**Flow:** **Find ABHA - IRIS** - step 2 of 3
- Previous: *Search ABHA by mobile*
- Next: *Find ABHA via IRIS - verify*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "search-ABHA", "Aadhaar-iris-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"index"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"Aadhaar"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |
| `txnId` | string | yes | Transaction ID returned by the previous step of this flow. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "search-abha",
    "aadhaar-iris-verify"
  ],
  "loginHint": "index",
  "loginId": "{{rsaIndexEncryptionOutput}}",
  "otpSystem": "aadhaar",
  "txnId": "{{searchTxnId}}"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: index.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: aadhaar.
- `txnId` (string, required): Transaction ID returned by the previous step of this flow.

## Responses

- `200`: Success: Find ABHA Via Biometric (Iris) - Send Iris Authentication Request
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found: Resource not found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `timestamp` (string)
  - `path` (string)
  - `description` (string)
  - `error` (string)
  - `requestId` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "message": "Iris authentication request successfully sent."
}
```


---

# Find ABHA via IRIS - verify

`POST /abha/api/v3/profile/login/verify`

Completes IRIS authentication for the chosen account. Send the `txnId` from *Find ABHA via IRIS - send authentication request* with the IRIS PID.

**Endpoint:** `POST /abha/api/v3/profile/login/verify`

**Flow:** **Find ABHA - IRIS** - step 3 of 3
- Previous: *Find ABHA via IRIS - send authentication request*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-iris-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["iris"]` | yes | Authentication method used in this step. |
| `authData.iris` | object | yes | IRIS authentication block. |
| `authData.iris.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.iris.irisAuthPid` | string | yes | Base64 PID block captured from a registered IRIS RD device. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-iris-verify"
  ],
  "authData": {
    "authMethods": [
      "iris"
    ],
    "iris": {
      "txnId": "{{txnId}}",
      "irisAuthPid": "{{PID}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.iris` (object, required): IRIS authentication block.
- `authData.iris.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.iris.irisAuthPid` (string, required): Base64 PID block captured from a registered IRIS RD device.

## Responses

- `200`: Success: Find ABHA via IRIS - Positive flow
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)
  - `accounts.profilePhoto` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `404`: Not Found: User Not Found; Resource Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "a2s9f59d-dfba-4261-8ea2-16541cfd6f2a",
  "authResult": "success",
  "message": "IRIS verified successfully",
  "token": "<TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "refreshExpiresIn": 1296000,
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "status": "ACTIVE",
      "profilePhoto": "<BASE64_PHOTO>"
    }
  ]
}
```


---

# Search ABHA by mobile

`POST /abha/api/v3/profile/account/abha/search`

**Endpoint:** `POST /abha/api/v3/profile/account/abha/search`

**Flow:** **Find ABHA - Mobile OTP** - step 1 of 3
- Previous: none (first call of this flow)
- Next: *Find ABHA via Mobile - send OTP*

---

This API endpoint is used to search for ABHA (Ayushman Bharat Health Account) profiles. It allows users to retrieve information about their ABHA profiles using mobile numbers. This is essential for verifying the user’s identity and ensuring secure access to their ABHA profile.

 **Note:** You need to use the Encryption API first. Only an RSA-encrypted mobile number should be in the request body.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/abha/search \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "search-abha"
  ],
  "mobile": "{{rsaMobileEncryptionOutput}}"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): The scope of the request. Use search-abha.
- `mobile` (string, required): The mobile number, encrypted with the public key from GET /abha/api/v3/profile/public/certificate.

## Responses

- `200`: Successfully retrieved ABHA details.
- `400`: Invalid mobile number.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `mobile` (string)
  - `timestamp` (string)
- `401`: Missing Credentials.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: User not found.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
[
  {
    "txnId": "d5b1fb36-e0be-401d-b4cf-cc71c5aca98a",
    "ABHA": [
      {
        "index": 1,
        "ABHANumber": "xx-xxxx-xxxx-XX31",
        "name": "<NAME>",
        "gender": "F",
        "kycVerified": "true",
        "authMethods": [
          "AADHAAR_OTP",
          "MOBILE_OTP",
          "... 2 more of the same shape"
        ]
      }
    ]
  }
]
```


---

# Find ABHA via Mobile - send OTP

`POST /abha/api/v3/profile/login/request/otp`

Sends a mobile OTP for the ABHA account picked from *Search ABHA by mobile*. Send `loginHint: index`, the RSA-encrypted `index` of the chosen account, and the `txnId` returned by the search.

**Endpoint:** `POST /abha/api/v3/profile/login/request/otp`

**Flow:** **Find ABHA - Mobile OTP** - step 2 of 3
- Previous: *Search ABHA by mobile*
- Next: *Find ABHA via Mobile - verify OTP*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "search-ABHA", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"index"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |
| `txnId` | string | yes | Transaction ID returned by the previous step of this flow. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "search-abha",
    "mobile-verify"
  ],
  "loginHint": "index",
  "loginId": "{{rsaIndexEncryptionOutput}}",
  "otpSystem": "abdm",
  "txnId": "{{searchTxnId}}"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: index.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.
- `txnId` (string, required): Transaction ID returned by the previous step of this flow.

## Responses

- `200`: Success: Search ABHA Via Mobile Number - Send OTP
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): Search ABHA Via Mobile Number - Invalid LoginId
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found: Resource not found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `timestamp` (string)
  - `path` (string)
  - `description` (string)
  - `error` (string)
  - `requestId` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "dcc22def-8102-4c9a-a36e-15743556fdc4",
  "message": "OTP sent to Aadhaar registered mobile number ending with ******7828"
}
```


---

# Find ABHA via Mobile - verify OTP

`POST /abha/api/v3/profile/login/verify`

Verifies the mobile OTP for the chosen account. Returns the ABHA details and the user token.

**Endpoint:** `POST /abha/api/v3/profile/login/verify`

**Flow:** **Find ABHA - Mobile OTP** - step 3 of 3
- Previous: *Find ABHA via Mobile - send OTP*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted OTP}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Find ABHA - Verify Mobile OTP
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)
  - `accounts.profilePhoto` (string)
- `400`: Bad Request (request validation failed): Find ABHA  - Invalid Transaction Id
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `404`: Not Found: User Not Found; Resource Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "dcc22def-8102-4c9a-a36e-15743556fdc4",
  "authResult": "success",
  "message": "OTP verified successfully",
  "token": "<TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "refreshExpiresIn": 1296000,
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "status": "ACTIVE",
      "profilePhoto": "<BASE64_PHOTO>"
    }
  ]
}
```


---

# Forgot ABHA via Aadhaar - send OTP

`POST /abha/api/v3/profile/login/request/otp`

Starts recovery of a forgotten ABHA number. UIDAI sends an OTP to the Aadhaar-linked mobile.

**Endpoint:** `POST /abha/api/v3/profile/login/request/otp`

**Flow:** **Forgot ABHA - Aadhaar OTP** - step 1 of 2
- Previous: none (first call of this flow)
- Next: *Forgot ABHA via Aadhaar - verify OTP*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"Aadhaar"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"Aadhaar"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-verify"
  ],
  "loginHint": "aadhaar",
  "loginId": "{{encrypted Aadhaar}}",
  "otpSystem": "aadhaar"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: aadhaar.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: aadhaar.

## Responses

- `200`: Success: Forgot ABHA via Aadhaar OTP- Positive Flow
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): Forgot ABHA via Aadhaar OTP- Invalid LoginHint; Forgot ABHA via Aadhaar OTP-Invalid scope
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Forgot ABHA via Aadhaar OTP- Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found: Resource not found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `timestamp` (string)
  - `path` (string)
  - `description` (string)
  - `error` (string)
  - `requestId` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "86b3d4c8-114e-4fd1-8604-93a684730827",
  "message": "OTP sent to Aadhaar registered mobile number ending with ******1670"
}
```


---

# Forgot ABHA via Aadhaar - verify OTP

`POST /abha/api/v3/profile/login/verify`

Verifies the Aadhaar OTP. Returns the ABHA linked to the Aadhaar number, with the user token.

**Endpoint:** `POST /abha/api/v3/profile/login/verify`

**Flow:** **Forgot ABHA - Aadhaar OTP** - step 2 of 2
- Previous: *Forgot ABHA via Aadhaar - send OTP*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted OTP}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Forgot ABHA via Aadhaar OTP-Positive flow
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)
  - `accounts.profilePhoto` (string)
- `400`: Bad Request (request validation failed): Forgot ABHA via Aadhaar OTP-Invalid OTP
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `404`: Not Found: User Not Found; Resource Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "725a7e53-96c3-49c2-9596-232a726f62a5",
  "authResult": "success",
  "message": "OTP verified successfully",
  "token": "<TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "refreshExpiresIn": 1296000,
  "accounts": [
    {
      "ABHANumber": "91-****-****-5727",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "status": "ACTIVE"
    }
  ]
}
```


---

# Forgot ABHA via Mobile - send OTP

`POST /abha/api/v3/profile/login/request/otp`

Starts recovery of a forgotten ABHA number. ABDM sends an OTP to the mobile number.

**Endpoint:** `POST /abha/api/v3/profile/login/request/otp`

**Flow:** **Forgot ABHA - Mobile OTP** - step 1 of 2
- Previous: none (first call of this flow)
- Next: *Forgot ABHA via Mobile - verify OTP*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"mobile"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "mobile-verify"
  ],
  "loginHint": "mobile",
  "loginId": "{{encrypted mobile number}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: mobile.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.

## Responses

- `200`: Success: Forgot ABHA via Mobile OTP- Positive flow
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): Forgot ABHA via Mobile OTP-Invalid LoginId; Forgot ABHA via Mobile OTP-Invalid LoginHint
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found: Resource not found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `timestamp` (string)
  - `path` (string)
  - `description` (string)
  - `error` (string)
  - `requestId` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "d41a143c-4751-46d4-aee5-94bf6d9c1bd6",
  "message": "OTP sent to Aadhaar registered mobile number ending with ******0903"
}
```


---

# Forgot ABHA via Mobile - verify OTP

`POST /abha/api/v3/profile/login/verify`

Verifies the mobile OTP. Returns the ABHA accounts linked to the mobile number, and a short-lived token.

**Endpoint:** `POST /abha/api/v3/profile/login/verify`

**Flow:** **Forgot ABHA - Mobile OTP** - step 2 of 2
- Previous: *Forgot ABHA via Mobile - send OTP*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted OTP}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Forgot ABHA via Mobile OTP- Positive Flow
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)
  - `accounts.profilePhoto` (string)
- `400`: Bad Request (request validation failed): Forgot ABHA via Mobile OTP-Invalid OTP Value; Forgot ABHA via Mobile OTP-Invalid Transaction Id; Forgot ABHA via Mobile OTP-Invalid scope; Forgot ABHA via Mobile OTP-Invalid authMethod
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `404`: Not Found: User Not Found; Resource Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "c837a1bd-7694-4c06-a42c-7eb36e445d1d",
  "authResult": "success",
  "message": "OTP verified successfully",
  "token": "<TOKEN>",
  "expiresIn": 300,
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "gender": "M",
      "dob": "<DOB>",
      "verifiedStatus": "VERIFIED",
      "verificationType": "AADHAAR",
      "status": "ACTIVE",
      "profilePhoto": "<BASE64_PHOTO>"
    },
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "gender": "M",
      "dob": "<DOB>",
      "verifiedStatus": "VERIFIED",
      "verificationType": "AADHAAR",
      "status": "ACTIVE",
      "profilePhoto": "<BASE64_PHOTO>"
    },
    "... 2 more of the same shape"
  ]
}
```


---

# Login via Aadhaar number - send Aadhaar OTP

`POST /abha/api/v3/profile/login/request/otp`

Starts login with an Aadhaar number. UIDAI sends an OTP to the Aadhaar-linked mobile.

**Endpoint:** `POST /abha/api/v3/profile/login/request/otp`

**Flow:** **Login - Aadhaar Number** - step 1 of 2
- Previous: none (first call of this flow)
- Next: *Login via Aadhaar number - verify Aadhaar OTP*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"Aadhaar"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"Aadhaar"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-verify"
  ],
  "loginHint": "aadhaar",
  "loginId": "{{encrypted aadhaar-number}}",
  "otpSystem": "aadhaar"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: aadhaar.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: aadhaar.

## Responses

- `200`: Success: Login Via Aadhaar Number - Using Aadhaar OTP - Send OTP
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): Login via Aadhaar - Invalid Login Hint; Login via Aadhaar OTP - Invalid Scope; Login via Aadhaar OTP - Invalid LoginId
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Login via Aadhaar - Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found: Resource not found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `timestamp` (string)
  - `path` (string)
  - `description` (string)
  - `error` (string)
  - `requestId` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "86b3d4c8-114e-4fd1-8604-93a684730827",
  "message": "OTP sent to Aadhaar registered mobile number ending with ******0903"
}
```


---

# Login via Aadhaar number - verify Aadhaar OTP

`POST /abha/api/v3/profile/login/verify`

Verifies the Aadhaar OTP for Aadhaar-number login. Returns the user X-token (`token`) of the ABHA linked to the Aadhaar.

**Endpoint:** `POST /abha/api/v3/profile/login/verify`

**Flow:** **Login - Aadhaar Number** - step 2 of 2
- Previous: *Login via Aadhaar number - send Aadhaar OTP*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted OTP}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Verify Login Via Aadhaar Number - Positive flow
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)
  - `accounts.profilePhoto` (string)
- `400`: Bad Request (request validation failed): Invalid OTP Value; Invalid Transaction Id
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `404`: Not Found: ABHA user not registered
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "9fc6af6a-374f-4b6a-9cbe-791d360dfc28",
  "authResult": "success",
  "message": "OTP verified successfully",
  "token": "<TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "refreshExpiresIn": 1296000,
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "status": "ACTIVE",
      "profilePhoto": "<BASE64_PHOTO>"
    }
  ]
}
```


---

# Login via ABHA number - send Aadhaar OTP

`POST /abha/api/v3/profile/login/request/otp`

Starts login with an ABHA number. UIDAI sends an OTP to the mobile linked with the Aadhaar of this ABHA.

**Endpoint:** `POST /abha/api/v3/profile/login/request/otp`

**Flow:** **Login - ABHA Number (Aadhaar OTP)** - step 1 of 2
- Previous: none (first call of this flow)
- Next: *Login via ABHA number - verify Aadhaar OTP*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"ABHA-number"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"Aadhaar"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-verify"
  ],
  "loginHint": "abha-number",
  "loginId": "{{encrypted abha-number}}",
  "otpSystem": "aadhaar"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: abha-number.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: aadhaar.

## Responses

- `200`: Success: Login Via ABHA Number - Using Aadhaar OTP - Send OTP
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): Login Via ABHA Number - Using Aadhaar OTP - Invalid Login Hint
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Login Via ABHA Number -Using Aadhaar OTP-Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found: Resource not found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `timestamp` (string)
  - `path` (string)
  - `description` (string)
  - `error` (string)
  - `requestId` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "message": "OTP sent to Aadhaar registered mobile number ending with ******0903"
}
```


---

# Login via ABHA number - verify Aadhaar OTP

`POST /abha/api/v3/profile/login/verify`

Verifies the Aadhaar OTP for ABHA-number login. Returns the user X-token (`token`) and a refresh token.

**Endpoint:** `POST /abha/api/v3/profile/login/verify`

**Flow:** **Login - ABHA Number (Aadhaar OTP)** - step 2 of 2
- Previous: *Login via ABHA number - send Aadhaar OTP*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted OTP}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Verify Login Via ABHA Number - Using Aadhaar OTP
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)
  - `accounts.profilePhoto` (string)
- `400`: Bad Request (request validation failed): Verify Login via ABHA Number using Aadhaar OTP - Invalid OTP Value
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `404`: Not Found: User Not Found; Resource Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "9fc6af6a-374f-4b6a-9cbe-791d360dfc28",
  "authResult": "success",
  "message": "OTP verified successfully",
  "token": "<TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "refreshExpiresIn": 1296000,
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "status": "ACTIVE",
      "profilePhoto": "<BASE64_PHOTO>"
    }
  ]
}
```


---

# Login via ABHA number - send ABHA (mobile) OTP

`POST /abha/api/v3/profile/login/request/otp`

Starts login with an ABHA number. ABDM sends an OTP to the mobile registered with this ABHA.

**Endpoint:** `POST /abha/api/v3/profile/login/request/otp`

**Flow:** **Login - ABHA Number (Mobile OTP)** - step 1 of 2
- Previous: none (first call of this flow)
- Next: *Login via ABHA number - verify ABHA (mobile) OTP*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"ABHA-number"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "mobile-verify"
  ],
  "loginHint": "abha-number",
  "loginId": "{{encrypted abha-number}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: abha-number.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.

## Responses

- `200`: Success: Login Via ABHA Number - Using ABHA OTP - Send OTP
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): Login Via ABHA Number - Using ABHA OTP - Invalid Login Hint
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Login Via ABHA Number - Using ABHA OTP- Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found: Resource not found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `timestamp` (string)
  - `path` (string)
  - `description` (string)
  - `error` (string)
  - `requestId` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "message": "OTP sent to Aadhaar registered mobile number ending with ******0903"
}
```


---

# Login via ABHA number - verify ABHA (mobile) OTP

`POST /abha/api/v3/profile/login/verify`

Verifies the ABHA (mobile) OTP for ABHA-number login. Returns the user X-token (`token`) and a refresh token.

**Endpoint:** `POST /abha/api/v3/profile/login/verify`

**Flow:** **Login - ABHA Number (Mobile OTP)** - step 2 of 2
- Previous: *Login via ABHA number - send ABHA (mobile) OTP*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted OTP}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Verify Login Via ABHA Number - Using ABHA OTP
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)
  - `accounts.profilePhoto` (string)
- `400`: Bad Request (request validation failed): Verify Login via ABHA Number using ABHA OTP - Invalid OTP Value
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `404`: Not Found: User Not Found; Resource Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "160ce506-4ef8-462e-ba2f-413c6f17852e",
  "authResult": "success",
  "message": "OTP verified successfully",
  "token": "<TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "refreshExpiresIn": 1296000,
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "status": "ACTIVE",
      "profilePhoto": "<BASE64_PHOTO>"
    }
  ]
}
```


---

# Login via Biometric (Fingerprint) - v3.1 single step

`POST /abha/api/v3.1/profile/login/verify`

v3.1 fingerprint login in a single call. Send the encrypted Aadhaar number and the fingerprint PID. Returns the user X-token (`token`). No send-request step is needed.

**Endpoint:** `POST /abha/api/v3.1/profile/login/verify`

**Flow:** **Login - Biometric v3.1** - independent API; call the one that fits your identifier / modality.

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-bio-login-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["bio_login"]` | yes | Authentication method used in this step. |
| `authData.bio_login` | object | yes | Fingerprint login block (v3.1). |
| `authData.bio_login.aadhaar` | string | yes | Aadhaar number, RSA-encrypted. |
| `authData.bio_login.fingerPrintAuthPid` | string | yes | Base64 PID block captured from a registered fingerprint RD device. |

> **Note:** This API is only in the Postman collection (v3.1). The request/response is taken from there, and the success response shape reuses the v3 biometric verify example.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3.1/profile/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-bio-login-verify"
  ],
  "authData": {
    "authMethods": [
      "bio_login"
    ],
    "bio_login": {
      "aadhaar": "{{encryptedAadhaar}}",
      "fingerPrintAuthPid": "{{fingerPrintAuthPid}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.bio_login` (object, required): Fingerprint login block (v3.1).
- `authData.bio_login.aadhaar` (string, required): Aadhaar number, RSA-encrypted.
- `authData.bio_login.fingerPrintAuthPid` (string, required): Base64 PID block captured from a registered fingerprint RD device.

## Responses

- `200`: Success: Verify Login via Fingerprint (v3.1) - Positive flow
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)
  - `accounts.profilePhoto` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `404`: Not Found: User Not Found; Resource Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "fe1c527e-1ab8-40c4-84d2-9eedb3378d39",
  "authResult": "success",
  "message": "BIO verified successfully",
  "token": "<TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "refreshExpiresIn": 1296000,
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "status": "ACTIVE",
      "profilePhoto": "<BASE64_PHOTO>"
    }
  ]
}
```


---

# Login via Biometric (Iris) - v3.1 single step

`POST /abha/api/v3.1/profile/login/verify`

v3.1 IRIS login in a single call. Send the encrypted Aadhaar number and the IRIS PID. Returns the user X-token (`token`). No send-request step is needed.

**Endpoint:** `POST /abha/api/v3.1/profile/login/verify`

**Flow:** **Login - Biometric v3.1** - independent API; call the one that fits your identifier / modality.

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-iris-login-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["iris_login"]` | yes | Authentication method used in this step. |
| `authData.iris_login` | object | yes | IRIS login block (v3.1). |
| `authData.iris_login.aadhaar` | string | yes | Aadhaar number, RSA-encrypted. |
| `authData.iris_login.irisAuthPid` | string | yes | Base64 PID block captured from a registered IRIS RD device. |

> **Note:** This API is only in the Postman collection (v3.1). The request/response is taken from there, and the success response shape reuses the v3 biometric verify example.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3.1/profile/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-iris-login-verify"
  ],
  "authData": {
    "authMethods": [
      "iris_login"
    ],
    "iris_login": {
      "aadhaar": "{{encryptedAadhaar}}",
      "irisAuthPid": "{{irisAuthPid}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.iris_login` (object, required): IRIS login block (v3.1).
- `authData.iris_login.aadhaar` (string, required): Aadhaar number, RSA-encrypted.
- `authData.iris_login.irisAuthPid` (string, required): Base64 PID block captured from a registered IRIS RD device.

## Responses

- `200`: Success: Verify Login via Iris (v3.1) - Positive flow
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)
  - `accounts.profilePhoto` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `404`: Not Found: User Not Found; Resource Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "a2s9f59d-dfba-4261-8ea2-16541cfd6f2a",
  "authResult": "success",
  "message": "IRIS verified successfully",
  "token": "<TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "refreshExpiresIn": 1296000,
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "status": "ACTIVE",
      "profilePhoto": "<BASE64_PHOTO>"
    }
  ]
}
```


---

# Login via Biometric (Fingerprint) - send authentication request

`POST /abha/api/v3/profile/login/request/otp`

Starts fingerprint login for an ABHA number. Use the returned `txnId` in *Login via Biometric (Fingerprint) - verify*.

**Endpoint:** `POST /abha/api/v3/profile/login/request/otp`

**Flow:** **Login - Biometric v3 (Fingerprint)** - step 1 of 2
- Previous: none (first call of this flow)
- Next: *Login via Biometric (Fingerprint) - verify*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-bio-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"ABHA-number"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

> **Note:** The Postman collection does biometric login with a single call to `/abha/api/v3.1/profile/login/verify` (see tag *Login - Biometric v3.1*). Confirm which contract is current.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-bio-verify"
  ],
  "loginHint": "abha-number",
  "loginId": "{{encrypted abha-number}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: abha-number.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.

## Responses

- `200`: Success: Login Via Biometric - Using Fingerprint - Send OTP
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found: Resource not found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `timestamp` (string)
  - `path` (string)
  - `description` (string)
  - `error` (string)
  - `requestId` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "message": "FingerPrint authentication request successfully sent."
}
```


---

# Login via Biometric (Fingerprint) - verify

`POST /abha/api/v3/profile/login/verify`

Completes fingerprint login. Send the `txnId` from *Login via Biometric (Fingerprint) - send authentication request* with the fingerprint PID. Returns the user X-token (`token`).

**Endpoint:** `POST /abha/api/v3/profile/login/verify`

**Flow:** **Login - Biometric v3 (Fingerprint)** - step 2 of 2
- Previous: *Login via Biometric (Fingerprint) - send authentication request*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-bio-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["bio"]` | yes | Authentication method used in this step. |
| `authData.bio` | object | yes | Fingerprint authentication block. |
| `authData.bio.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.bio.fingerPrintAuthPid` | string | yes | Base64 PID block captured from a registered fingerprint RD device. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-bio-verify"
  ],
  "authData": {
    "authMethods": [
      "bio"
    ],
    "bio": {
      "txnId": "{{txnId}}",
      "fingerPrintAuthPid": "{{PID}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.bio` (object, required): Fingerprint authentication block.
- `authData.bio.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.bio.fingerPrintAuthPid` (string, required): Base64 PID block captured from a registered fingerprint RD device.

## Responses

- `200`: Success: Verify Login Via Biometric - FingerPrint
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)
  - `accounts.profilePhoto` (string)
- `400`: Bad Request (request validation failed): Verify Login via Biometric (FingerPrint) - Invalid Pid
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `404`: Not Found: User Not Found; Resource Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "fe1c527e-1ab8-40c4-84d2-9eedb3378d39",
  "authResult": "success",
  "message": "BIO verified successfully",
  "token": "<TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "refreshExpiresIn": 1296000,
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "status": "ACTIVE",
      "profilePhoto": "<BASE64_PHOTO>"
    }
  ]
}
```


---

# Login via Biometric (Iris) - send authentication request

`POST /abha/api/v3/profile/login/request/otp`

Starts IRIS login for an ABHA number. Use the returned `txnId` in *Login via Biometric (Iris) - verify*.

**Endpoint:** `POST /abha/api/v3/profile/login/request/otp`

**Flow:** **Login - Biometric v3 (Iris)** - step 1 of 2
- Previous: none (first call of this flow)
- Next: *Login via Biometric (Iris) - verify*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-iris-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"ABHA-number"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

> **Note:** The Postman collection does biometric login with a single call to `/abha/api/v3.1/profile/login/verify` (see tag *Login - Biometric v3.1*). Confirm which contract is current.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-iris-verify"
  ],
  "loginHint": "abha-number",
  "loginId": "{{encrypted abha-number}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: abha-number.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.

## Responses

- `200`: Success: Login Via Biometric - Using Iris - Send OTP
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found: Resource not found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `timestamp` (string)
  - `path` (string)
  - `description` (string)
  - `error` (string)
  - `requestId` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "message": "IRIS authentication request successfully sent."
}
```


---

# Login via Biometric (Iris) - verify

`POST /abha/api/v3/profile/login/verify`

Completes IRIS login. Send the `txnId` from *Login via Biometric (Iris) - send authentication request* with the IRIS PID. Returns the user X-token (`token`).

**Endpoint:** `POST /abha/api/v3/profile/login/verify`

**Flow:** **Login - Biometric v3 (Iris)** - step 2 of 2
- Previous: *Login via Biometric (Iris) - send authentication request*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-iris-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["iris"]` | yes | Authentication method used in this step. |
| `authData.iris` | object | yes | IRIS authentication block. |
| `authData.iris.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.iris.irisAuthPid` | string | yes | Base64 PID block captured from a registered IRIS RD device. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-iris-verify"
  ],
  "authData": {
    "authMethods": [
      "iris"
    ],
    "iris": {
      "txnId": "{{txnId}}",
      "irisAuthPid": "{{PID}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.iris` (object, required): IRIS authentication block.
- `authData.iris.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.iris.irisAuthPid` (string, required): Base64 PID block captured from a registered IRIS RD device.

## Responses

- `200`: Success: Verify Login Via Biometric - IRIS
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)
  - `accounts.profilePhoto` (string)
- `400`: Bad Request (request validation failed): Invalid Transaction Id
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `404`: Not Found: User Not Found; Resource Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "a2s9f59d-dfba-4261-8ea2-16541cfd6f2a",
  "authResult": "success",
  "message": "IRIS verified successfully",
  "token": "<TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "refreshExpiresIn": 1296000,
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "status": "ACTIVE",
      "profilePhoto": "<BASE64_PHOTO>"
    }
  ]
}
```


---

# Face auth - generate transaction ID (init)

`POST /abha/api/v3/enrollment/enrol/auth/init`

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/auth/init`

**Flow:** **Login - Face Auth QR (v3.1)** - step 1 of 3
- Previous: none (first call of this flow)
- Next: *Face auth - capture PID / track status*

---

This API will help to generate transaction ID. This transaction ID will be used for whole face authentication process.

 The user can submit this transaction ID to the **ABHA** app using either intent-based sharing or by generating a QR code.

User can use this transaction ID to generate QR code using any QR generator tool. Open ABHA app and scan this QR code on ABHA App to start and complete the face capture process.

The data format of the QR code should follow this pattern:
https:///face-auth?txnId=.

**For example:** https://phrsbx.abdm.gov.in/face-auth?txnId=bac7251b-cd25-44d5-9707-f3d2ba181c1c

 For Sandbox- PHR-env-base-URL - https://phrsbx.abdm.gov.in
 For Production - PHR-env-base-URL - https://phr.abdm.gov.in

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/auth/init \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-enrol",
    "face-auth"
  ]
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): The scopes of the request, which name the flow this call belongs to.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it refers to the successful generation of Transaction Id.
  - `txnId` (string)
  - `message` (string)
- `400`: The 400 response code indicates a bad request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `scope` (string)
  - `timestamp` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, it refers to the lack of proper authentication during the operation of the Invalid Credentials
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "message": "Transaction Id generated Successfully"
}
```


---

# Face auth - capture PID / track status

`POST /abha/api/v3/enrollment/enrol/capturePID`

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/capturePID`

**Flow:** **Login - Face Auth QR (v3.1)** - step 2 of 3
- Previous: *Face auth - generate transaction ID (init)*
- Next: *Login via Face Auth (QR) - verify*

> **Note:** The original description below says the next step is ABHA enrolment. In this flow the next step is the verify API named above.

---

This API is designed to verify the status of a transaction ID that was generated during the invocation of the `auth/init` API. It serves as a follow-up mechanism to ensure that the transaction is still valid, active, and has not expired or been invalidated.

 Wait for PID capture and submission confirmation from the ABHA App. The response of the API will return status of that transactionId. It can be either **PENDING,VERIFIED,FAILED,COMPLETE.**

 Once the status in the response of this API is returned as **COMPLETE**, it indicates that the face authentication process has been successfully completed. At this stage, the next step is to invoke the `/enrollment/enrol/byAadhaar` (You can find this API in ABHA ENROLLMENT Via Aadhaar section) API to proceed further.

User can poll the `/capturePID` API in every 5 - 10 seconds interval to check the status of face capture process or alternatively skip this step and call the `/enrollment/enrol/byAadhaar` API once they see the PID submission success message in the ABHA app.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/capturePID \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-enrol",
    "face-verify"
  ],
  "txnId": "ea1dc7aa-d7c3-40ab-bee8-84c6f1eb90fa"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): The scopes of the request, which name the flow this call belongs to.
- `txnId` (string, required): The transaction ID returned by the previous call in this flow.

## Responses

- `200`: The 200 response code indicates a successful request. The reponse of the API will return status of that transactionId. It can be either **PENDING,VERIFIED,FAILED,COMPLETE.**
  - `status` (string)
  - `message` (string)
- `400`: The 400 response code indicates a bad request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, it refers to the lack of proper authentication during the operation of the Invalid Credentials
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "status": "PENDING",
  "message": "Awaiting PID capture"
}
```


---

# Login via Face Auth (QR) - verify

`POST /abha/api/v3.1/profile/login/verify`

Completes login through the face-auth QR / ABHA-app flow. First call *Face auth - generate transaction ID (init)*, then poll *Face auth - capture PID / track status* until `COMPLETE`. Then send the same `txnId` here. Returns the user X-token (`token`).

**Endpoint:** `POST /abha/api/v3.1/profile/login/verify`

**Flow:** **Login - Face Auth QR (v3.1)** - step 3 of 3
- Previous: *Face auth - capture PID / track status*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "Aadhaar-face-login-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["face_auth"]` | yes | Authentication method used in this step. |
| `authData.face_login` | object | yes | Face login block (v3.1). |
| `authData.face_login.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.face_login.aadhaar` | string | yes | Aadhaar number, RSA-encrypted. |

> **Note:** This API is only in the Postman collection (v3.1).

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3.1/profile/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-face-login-verify"
  ],
  "authData": {
    "authMethods": [
      "face_auth"
    ],
    "face_login": {
      "txnId": "8220299c-40ad-40b6-bc52-13a7d46a69d0",
      "aadhaar": "{{encrypted aadhaar number}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.face_login` (object, required): Face login block (v3.1).
- `authData.face_login.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.face_login.aadhaar` (string, required): Aadhaar number, RSA-encrypted.

## Responses

- `200`: Success: Positive flow
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)
  - `accounts.profilePhoto` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `404`: Not Found: User Not Found; Resource Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "ad0aff4b-77dc-48c0-9c4a-18ac4f13af49",
  "authResult": "success",
  "message": "FACE verified successfully",
  "token": "<TOKEN>...",
  "expiresIn": 1800,
  "refreshToken": "<TOKEN>...",
  "refreshExpiresIn": 1296000,
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "status": "ACTIVE",
      "profilePhoto": "{{base64 profile photo}}"
    }
  ]
}
```


---

# Login via Mobile number - send OTP

`POST /abha/api/v3/profile/login/request/otp`

Starts login with a mobile number. ABDM sends an OTP to the mobile number.

**Endpoint:** `POST /abha/api/v3/profile/login/request/otp`

**Flow:** **Login - Mobile Number** - step 1 of 3
- Previous: none (first call of this flow)
- Next: *Login via Mobile number - verify OTP*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"mobile"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "mobile-verify"
  ],
  "loginHint": "mobile",
  "loginId": "{{encrypted mobile number}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: mobile.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.

## Responses

- `200`: Success: Login Via Mobile Number - Using Mobile OTP - Send OTP
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): Login Via Mobile Number - Invalid LoginHint
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Login Via Mobile Number - Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found: Login ABHA API's
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `timestamp` (string)
  - `path` (string)
  - `description` (string)
  - `error` (string)
  - `requestId` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "d4196ae3-f302-45bc-9460-a798a17b4c3a",
  "message": "OTP sent to Aadhaar registered mobile number ending with ******0903"
}
```


---

# Login via Mobile number - verify OTP

`POST /abha/api/v3/profile/login/verify`

Verifies the mobile OTP. Returns a short-lived token (`token`, used as the `T-token` header) and the list of ABHA accounts linked to the mobile. Then call *Login via Mobile number - verify user (select ABHA)* with the chosen ABHA number to get the user X-token.

**Endpoint:** `POST /abha/api/v3/profile/login/verify`

**Flow:** **Login - Mobile Number** - step 2 of 3
- Previous: *Login via Mobile number - send OTP*
- Next: *Login via Mobile number - verify user (select ABHA)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-login", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted OTP}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Verify Login Via Mobile Number
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)
  - `accounts.profilePhoto` (string)
- `400`: Bad Request (request validation failed): Invalid OTP Value; Invalid Transaction Id
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Credentials (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `description` (string)
  - `message` (string)
- `404`: Not Found: User Not Found; Resource Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "588453aa-4bb0-44c0-bbdd-62ebd53c37c6",
  "authResult": "success",
  "message": "OTP verified successfully",
  "token": "<TOKEN>",
  "expiresIn": 300,
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "gender": "M",
      "dob": "<DOB>",
      "verifiedStatus": "VERIFIED",
      "verificationType": "AADHAAR",
      "status": "ACTIVE",
      "profilePhoto": "<BASE64_PHOTO>",
      "kycVerified": true
    },
    {
      "ABHANumber": "<ABHA_NUMBER>",
      "preferredAbhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "gender": "M",
      "dob": "<DOB>",
      "verifiedStatus": "VERIFIED",
      "verificationType": "CHILD_ABHA",
      "status": "ACTIVE",
      "profilePhoto": "<BASE64_PHOTO>"
    }
  ]
}
```


---

# Login via Mobile number - verify user (select ABHA)

`POST /abha/api/v3/profile/login/verify/user`

**Endpoint:** `POST /abha/api/v3/profile/login/verify/user`

**Flow:** **Login - Mobile Number** - step 3 of 3
- Previous: *Login via Mobile number - verify OTP*
- Next: none (last call of this flow)

---

This API is used to verify the selected ABHA user during the login journey after the user has searched or identified available ABHA accounts. It confirms that the user is proceeding with the correct ABHA number and validates the requested authentication flow. This step helps securely continue login for the chosen account and prevents access to the wrong profile. It is typically used when multiple ABHA accounts are available against the same mobile number or identifier. After successful verification, the user can proceed with the remaining authentication steps.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/login/verify/user \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'T-token: Bearer {{jwtToken}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "ABHANumber": "{{abha-number}}",
  "txnId": "{{txnId}}"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `T-token` (string, required): Short-lived token (`Bearer <token>`) returned by *Login via Mobile number - verify OTP*.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `ABHANumber` (string, required): The 14 digit ABHA number to sign in to, chosen from the accounts the previous call listed.
- `txnId` (string, required): The transaction ID returned by the previous call in this flow.

## Responses

- `200`: The 200 response code indicates a successful request. **
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
- `400`: The 400 response code indicates a bad request. In this context, it refers to various errors encountered during the OTP (One-Time Password) verification process due to invalid inputs or parameters. **Types of OTP Verification Errors:** **Invakid T-Token:** This error occurs when the T -token. **Verify OTP - Invalid Abha Number:** This error occurs when the authentication methods provided for invalid abha number are invalid.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `message` (string)
  - `timestamp` (string)
- `401`: **Unauthorized:** Indicates that the request requires user authentication. The server returns a 401 status code when the client has not provided valid authentication credentials.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "token": "<TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "refreshExpiresIn": 1296000
}
```


---

# Re-KYC - send Aadhaar OTP

`POST /abha/api/v3/profile/account/request/otp`

Starts Re-KYC of a logged-in ABHA (`X-token`). UIDAI sends an OTP to the Aadhaar-linked mobile.

**Endpoint:** `POST /abha/api/v3/profile/account/request/otp`

**Flow:** **Profile - Re-KYC** - step 1 of 2
- Previous: none (first call of this flow)
- Next: *Re-KYC - verify Aadhaar OTP*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| X-token | yes | User token (`Bearer <token>`) received after ABHA creation / login. |
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-profile", "re-KYC"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"ABHA-number"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"Aadhaar"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-profile",
    "re-kyc"
  ],
  "loginHint": "abha-number",
  "loginId": "{{encrypted abha-number}}",
  "otpSystem": "aadhaar"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: abha-number.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: aadhaar.

## Responses

- `200`: Success: ReKYC-Send OTP
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): Re-KYC- Invalid Scope; Re-KYC- Invalid X-token; Re-KYC- Invalid LoginId; Re-KYC- Invalid Login Hint
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `Invalid Scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "c2095ea0-52ed-44ee-b8fc-02375b874e7a",
  "message": "OTP is sent to Aadhaar registered mobile number ending with *******0903"
}
```


---

# Re-KYC - verify Aadhaar OTP

`POST /abha/api/v3/profile/account/verify`

Verifies the Aadhaar OTP sent by *Re-KYC - send Aadhaar OTP* and refreshes the ABHA's KYC details from Aadhaar.

**Endpoint:** `POST /abha/api/v3/profile/account/verify`

**Flow:** **Profile - Re-KYC** - step 2 of 2
- Previous: *Re-KYC - send Aadhaar OTP*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| X-token | yes | User token (`Bearer <token>`) received after ABHA creation / login. |
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-profile", "re-KYC"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-profile",
    "re-kyc"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted otp}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Re-KYC- Positive Flow
  - `txnId` (string)
  - `authResult` (string)
  - `message` (string)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
- `400`: Bad Request (request validation failed): Re-KYC- Invalid Transaction Id; Re-KYC- Invalid Scope; ReKyc- Invalid Auth Method; Re-KYC- Invalid X-token; Re-Kyc- Invalid OTP Value
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `Invalid Scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): ReKyc- Invalid access token; ReKYC- X-token expired
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure): Re-KYC-INVALID OTP
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `message` (string)
  - `timestamp` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "bb548986-e96d-4b48-be1b-1e36741e867d",
  "authResult": "success",
  "message": "Re-kyc done successfully",
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>"
    }
  ]
}
```


---

# Update mobile - send OTP

`POST /abha/api/v3/profile/account/request/otp`

Starts a mobile number change for a logged-in ABHA user (`X-token`). ABDM sends an OTP to the **new** mobile number.

**Endpoint:** `POST /abha/api/v3/profile/account/request/otp`

**Flow:** **Profile - Update Mobile** - step 1 of 2
- Previous: none (first call of this flow)
- Next: *Update mobile - verify OTP*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| X-token | yes | User token (`Bearer <token>`) received after ABHA creation / login. |
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-profile", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"mobile"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-profile",
    "mobile-verify"
  ],
  "loginHint": "mobile",
  "loginId": "{{encrypted mobile number}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: mobile.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.

## Responses

- `200`: Success: Update Mobile-Positive flow
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): Update Mobile- Invalid Scope; Update Mobile- Invalid LoginId; Update Mobile- Invalid Login Hint; Update Mobile-Already verified mobile number
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `Invalid Scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "1c5fa806-67e1-4ad5-a848-0c4d805cd824",
  "message": "OTP sent to mobile number ending with ******0903"
}
```


---

# Update mobile - verify OTP

`POST /abha/api/v3/profile/account/verify`

Verifies the OTP sent by *Update mobile - send OTP* and updates the mobile number on the ABHA profile.

**Endpoint:** `POST /abha/api/v3/profile/account/verify`

**Flow:** **Profile - Update Mobile** - step 2 of 2
- Previous: *Update mobile - send OTP*
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| X-token | yes | User token (`Bearer <token>`) received after ABHA creation / login. |
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-profile", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-profile",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted otp}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Update Mobile- Positive Flow
  - `txnId` (string)
  - `authResult` (string)
  - `message` (string)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
- `400`: Bad Request (request validation failed): Update Mobile- Invalid Transaction Id; Update Mobile- Invalid Scope; Update Mobile- Invalid Auth Methods; Update Mobile- Invalid X-token; Update Mobile- Invalid OTP Value
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `Invalid Scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Update Mobile- Invalid access token; Update Mobile- X-token expired
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `message` (string)
  - `timestamp` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "01bb3a4c-4588-4734-aff4-23d3978e50be",
  "authResult": "success",
  "message": "Mobile Number linked successfully",
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>"
    }
  ]
}
```


---

# Update profile photo

`PATCH /abha/api/v3/profile/account`

Updates the profile photo of the logged-in ABHA user (`X-token`). Send the photo as a Base64 string.

**Endpoint:** `PATCH /abha/api/v3/profile/account`

**Flow:** **Profile - Update Photo** - step 1 of 1
- Previous: none (first call of this flow)
- Next: none (last call of this flow)

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| REQUEST-ID | yes | Unique UUID for every request. |
| X-token | yes | User token (`Bearer <token>`) received after verification / login. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `profilePhoto` | string | no | Base64 encoded profile photo. |

> **Note:** The source spec has no response example for this use case. Its only examples are for Child ABHA.

```bash
curl --request PATCH \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "profilePhoto": "{{profile photo string}}"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `X-token` (string, required): User token (`Bearer <token>`) received after verification / login.

## Body

- `profilePhoto` (string): Base64 encoded profile photo.

## Responses

- `200`: Success.
  - `ABHANumber` (string)
  - `preferredAbhaAddress` (string)
  - `mobile` (string)
  - `firstName` (string)
  - `middleName` (string)
  - `lastName` (string)
  - `yearOfBirth` (integer)
  - `monthOfBirth` (integer)
  - `dayOfBirth` (integer)
  - `gender` (string)
  - `status` (string)
  - `stateCode` (integer)
  - `districtCode` (integer)
  - `stateName` (string)
  - `districtName` (string)
  - `subdistrictName` (string)
  - `authMethods` (string[])
  - `tags` (object)
  - `kycVerified` (boolean)
  - `verificationStatus` (string)
  - `verificationType` (string)
  - `createdDate` (string)
- `400`: Bad Request (request validation failed).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.message` (string)
  - `error.timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access).
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `404`: Not Found.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure).
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "ABHANumber": "<ABHA_NUMBER>",
  "preferredAbhaAddress": "<ABHA_ADDRESS>",
  "mobile": "******0903",
  "firstName": "<NAME>",
  "middleName": "<NAME>",
  "lastName": "<NAME>",
  "yearOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "dayOfBirth": "<DOB>",
  "gender": "F",
  "status": "ACTIVE",
  "stateCode": 27,
  "districtCode": 290,
  "stateName": "Maharashtra",
  "districtName": "<ADDRESS>",
  "subdistrictName": "<ADDRESS>",
  "authMethods": [
    "MOBILE_OTP"
  ],
  "kycVerified": false,
  "verificationStatus": "VERIFIED",
  "verificationType": "CHILD_ABHA",
  "createdDate": "10-05-2024"
}
```


---

# M1 Identity errors

Seeing a symptom rather than a code? Start at [Troubleshooting](/docs/hiecm/v3/troubleshooting/).

## Codes

| Code        | HTTP | Message                                                                                                                         | Returned by                                                        |
| ----------- | ---- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `404`       | 404  | Runtime Error                                                                                                                   | `m1_post_v3_profile_login_verify_find_abha_face`                   |
| `900900`    | 500  | Unclassified Authentication Failure                                                                                             | `m1_post_v3_enrollment_auth_byabdm_mobile_verify_create_ab_091285` |
| `900901`    | 401  | Invalid Credentials                                                                                                             | `m1_post_v3_enrollment_request_otp_aadhaar_otp`                    |
| `900902`    | 401  | Missing Credentials                                                                                                             | `m1_post_v3_profile_benefit_search_xmluid`                         |
| `ABDM-1017` | 401  | Invalid Transaction Id                                                                                                          | `m1_get_v3_enrollment_enrol_suggestion_create_abha_aadhaar_otp`    |
| `ABDM-1021` | 401  | Lack of required priviledges                                                                                                    | `m1_post_v3_enrollment_enrol_byaadhaar_child_child_abha`           |
| `ABDM-1094` | 401  | X-token expired                                                                                                                 | `m1_post_v3_enrollment_enrol_byaadhaar_child_child_abha`           |
| `ABDM-1114` | 404  | User not found                                                                                                                  | `m1_patch_v3_profile_account_child_child_abha`                     |
| `ABDM-1124` | 422  | The mobile number provided by you is already linked to 6 ABHA Numbers. Please provide a different Mobile Number.                | `m1_post_v3_enrollment_enrol_byaadhaar_demo_auth_create_ab_81107d` |
| `ABDM-1138` | 400  | The benefit record has already been de-linked                                                                                   | `m1_post_v3_profile_benefit_linkanddelink_x_token`                 |
| `ABDM-1140` | 400  | The benefit record has already been linked                                                                                      | `m1_post_v3_profile_benefit_linkanddelink_x_token`                 |
| `ABDM-1157` | 422  | Child ABHA’s account limit has been exceeded for the requested Abha ID number ‘\<ABHA\_NUMBER>                                  | `m1_post_v3_enrollment_enrol_byaadhaar_child_child_abha`           |
| `ABDM-1160` | 422  | Non KYC CHILD ABHA is allowed to update their profile only once                                                                 | `m1_patch_v3_profile_account_child_child_abha`                     |
| `ABDM-1204` | 422  | UIDAI Error code : 400 : Invalid Aadhaar OTP value.                                                                             | `m1_post_v3_enrollment_enrol_byaadhaar_otp`                        |
| `ABDM-1207` | 422  | The information you provided does not match the details on record with Aadhaar. Please verify and provide accurate information. | `m1_post_v3_enrollment_enrol_byaadhaar_demo_auth_create_ab_81107d` |
| `ABDM-1211` | 400  | User not found.                                                                                                                 | `m1_post_v3_phr_web_login_abha_search_abha_address_login_m_27a20f` |
| `ABDM-1224` | 401  | Login via Biometric is not allowed.                                                                                             | `m1_post_v3_profile_login_request_otp_find_abha_face`              |

Every code above is recorded in the specification that owns it. The aggregated list across modules is at [error codes](/docs/hiecm/v3/reference/error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# M1 Identity: Create and verify ABHA

Create an ABHA, authenticate a holder, and read or update the profile, QR code and linked mobile number.

## Base URLs

| Environment | Base URL                                   |
| ----------- | ------------------------------------------ |
| Sandbox     | `https://abhasbx.abdm.gov.in/abha/api/v3/` |

Login by fingerprint or iris uses the same base URL, through `profile/login/verify` with a `bio` or `iris` block.

[See the user journeyWhat the person experiences, screen by screen, before you write any code.](/docs/hiecm/v3/milestones/m1)[When it goes wrongThe recorded error shapes and codes, and what to do about each.](/docs/hiecm/v3/api/m1/errors)

New to this? Start with [M1 Identity](/docs/hiecm/v3/milestones/m1).


---

# Perform HIP initiated linking

`POST /api/hiecm/hip/v3/link/carecontext`

**Note:** While generating the link-token the user/patient is providing both ABHA_number and ABHA_address, then at the time of linking both must be mandatory. If not one should be mandatory either 'ABHA_number' or 'ABHA_address'.

 This API endpoint is used by the Ayushman Bharat Digital Mission (ABDM) system to store care context or health record references. Upon successful validation of the ABHA (Ayushman Bharat Health Account) address and the associated link token, the system securely records the relevant care context information. This process ensures that health records are accurately linked and accessible, facilitating efficient and seamless health information exchange across the network. The API plays a critical role in maintaining the integrity and continuity of patient health records, thereby supporting comprehensive and coordinated care.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/hip/v3/link/carecontext \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'X-LINK-TOKEN: <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "abhaNumber": 12345678901234,
  "abhaAddress": "<ABHA_ADDRESS>",
  "patient": [
    {
      "referenceNumber": "TMH-PUID-001",
      "display": "String",
      "careContexts": [
        {
          "referenceNumber": "TMH-PUID-001",
          "display": "display 1"
        }
      ],
      "hiTypes": "DiagnosticReport",
      "count": 1
    }
  ]
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended
- `X-LINK-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Body

- `abhaNumber` (number): The abha number of the patient. Should be only 14 digit and it allows numeric character like ^\\d{14}$
- `abhaAddress` (string, required): The abha address of the patient. Should start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx also allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.]+[a-zA-Z0-9]@(abdm|sbx)$
- `patient` (object[], required)
- `patient.referenceNumber` (string, required): Patient identifier with which patient is registered in the facility/hospital or patient can also pass his abha_address in the reference number. Allows alpha numeric character and special characters like ^[a-zA-Z0-9_\-@,. "':|()/]{0,255}$
- `patient.display` (string, required): The display text for patient reference(regex:^[a-zA-Z0-9_\-@,. "':|()/]{0,255}$)
- `patient.careContexts` (object[], required): List of care contexts linked at the HIP end for the identified patient.
- `patient.careContexts.referenceNumber` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data) and it should be unique for each care-context.Allows alpha numeric character and special characters like ^[a-zA-Z0-9_\-@,. ()/:\\]{0,255}$
- `patient.careContexts.display` (string, required): The display text for care context reference(regex:^[a-zA-Z0-9_\-@,. "':|()/]{0,255}$)
- `patient.hiTypes` (string, required): Types of health information document. One of: DiagnosticReport, DischargeSummary, HealthDocumentRecord, ImmunizationRecord, OPConsultation, Prescription, WellnessRecord, Invoice.
- `patient.count` (number, required): The count should match with the number of care contexts

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare (`ABDM-1006`) or with a trailing ": " separator (`ABDM-1006: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900902 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `message` (string)


---

# Notify a change to a linked care context

`POST /api/hiecm/hip/v3/link/context/notify`

Notify the Consent Management (CM) system about any updates HiTypes of the already linked care context for a patient. By invoking this API, Health Information Providers (HIPs) can inform the CM system of changes or updates to the patient’s care context, ensuring that the most current and accurate health information is maintained. This process is crucial for the integrity and synchronization of patient health records across the network, supporting seamless and efficient health information exchange.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/hip/v3/link/context/notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "notification": {
    "patient": {
      "id": "<ABHA_ADDRESS>"
    },
    "careContext": {
      "patientReference": "<ABHA_ADDRESS>",
      "careContextReference": "b009a970-8b04-4779-abd1-b50f113245bf"
    },
    "hiTypes": [
      "DiagnosticReport"
    ],
    "date": "2024-05-09T10:34:00.387Z",
    "hip": {
      "id": "ABDM_HIP"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `notification` (object, required)
- `notification.patient` (object, required)
- `notification.patient.id` (string, required): The abha address of the patient
- `notification.careContext` (object, required): A care context - one episode or record grouping at the HIP.
- `notification.careContext.patientReference` (string, required): "A patient identifier with which patient is registered in the facility/hospital"
- `notification.careContext.careContextReference` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data)
- `notification.hiTypes` (string[], required): Type of health data that created in the care context
- `notification.date` (string, required): This should be a UTC Date & Time in ISO format
- `notification.hip` (object, required): The HIP that linked the care context. Only id is required.
- `notification.hip.id` (string, required): The service ID of the health information provider

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare (`ABDM-1006`) or with a trailing ": " separator (`ABDM-1006: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900902 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `message` (string)


---

# Send SMS notification to patient that a care context is linked

`POST /api/hiecm/hip/v3/link/patient/links/sms/notify2`

Send SMS notifications to patients, informing them that a care context has been successfully linked to their ABHA (Ayushman Bharat Health Account) address. By invoking this API, HIPs can ensure that patients are promptly notified about the linkage of their health records, enhancing transparency and patient engagement. This notification process is essential for keeping patients informed and involved in the management of their health information, thereby supporting a more connected and responsive healthcare system.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/hip/v3/link/patient/links/sms/notify2 \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "notification": {
    "phoneNo": "986543***",
    "hip": {
      "id": "ABDM_HIP",
      "name": "ABC Hospital"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `notification` (object, required)
- `notification.phoneNo` (string, required): The mobile number to send SMS
- `notification.hip` (object, required): Identifier and name of the health information provider.
- `notification.hip.id` (string, required): The service ID of the health information provider
- `notification.hip.name` (string, required): The name of the health information provider

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare (`ABDM-1006`) or with a trailing ": " separator (`ABDM-1006: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900902 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `message` (string)


---

# Generate link token to link the health records

`POST /api/hiecm/v3/token/generate-token`

Generate a link token which will be valid for 6 months.. This token can be used for Health Information Provider (HIP) Initiated Linking, enabling HIPs to securely link patient health records to their ABHA (Ayushman Bharat Health Account) address. The generated token ensures that the linking process is authenticated and authorised, maintaining the integrity and security of health information exchange. This functionality is crucial for facilitating seamless and efficient linking of health records within the healthcare ecosystem.

**Authorisation:** We are passing the access-token in the authorisation [Example: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJBbFJiNVd]

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/v3/token/generate-token \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "abhaNumber": 12345678901234,
  "abhaAddress": "<ABHA_ADDRESS>",
  "name": "first_name + middle_name + last_name",
  "gender": "M",
  "yearOfBirth": 9999
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `abhaNumber` (number): it can be null if abhaNumber is not linked with abhaAddress. Allows numeric character like ^\d{14}$
- `abhaAddress` (string, required): abhaAddress of the user/patient. Allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.]+[a-zA-Z0-9]@(abdm|sbx)$
- `name` (string, required): Only alphabets and special characters like ',.- are allowed like ^[a-zA-Z]+(([',. -][a-zA-Z ])?[a-zA-Z]*)*$
- `gender` (string, required): Allows M, F, O, D, T, U as a input
- `yearOfBirth` (number, required): Year of birth must be 4 digit, ranging between 1900 and 2200

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1035 - Invalid HIP ID. May be returned either bare (`ABDM-1035`) or with a trailing ": " separator (`ABDM-1035: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900902 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Answer the care context discovery

`POST /api/hiecm/user-initiated-linking/v3/patient/care-context/on-discover`

Is invoked by the Hospital Management Information System (HMIS) or Laboratory Information Management System (LIMS) or HIP application to share the response of the /api/hiecm/user-initiated-linking/v3/patient/care-context/on-discover API. It facilitates the communication of discovered health records back to the patient or user. By using this API, the HMIS/LIMS application ensures that the patient’s health information is accurately and promptly shared, supporting efficient and transparent health information exchange. This process is crucial for maintaining the integrity and continuity of patient care, enabling patients to have comprehensive access to their health records.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/user-initiated-linking/v3/patient/care-context/on-discover \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "transactionId": "f901b782-bfdf-4224-9f8d-da2cadc20c0d",
  "patient": [
    {
      "referenceNumber": "<ABHA_ADDRESS>",
      "display": "12345",
      "careContexts": [
        {
          "referenceNumber": "abc123",
          "display": "12345"
        }
      ],
      "hiType": "Prescription",
      "count": 1
    }
  ],
  "matchedBy": [
    "MR"
  ],
  "response": {
    "requestId": "f29f0e59-8388-4698-9fe6-05db67aeac46"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `transactionId` (string, required): UUID from discover request callback to track the entire user link flow
- `patient` (object[], required)
- `patient.referenceNumber` (string, required): A patient identifier with which patient is registered in the facility/hospital.Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. ()/:\\\\]{0,255}$"
- `patient.display` (string, required): Display text for patient reference. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"
- `patient.careContexts` (object[], required): List of care contexts linked at the HIP end for the identified patient.
- `patient.careContexts.referenceNumber` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data).Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. ()/:\\\\]{0,255}$"
- `patient.careContexts.display` (string, required): Display text for care context reference. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"
- `patient.hiType` (string, required): The health information type One of: DiagnosticReport, DischargeSummary, HealthDocumentRecord, ImmunizationRecord, OPConsultation, Prescription, WellnessRecord, Invoice.
- `patient.count` (integer, required): The count should match the number of care contexts in the payload
- `matchedBy` (string[], required)
- `error` (object): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message. Allows alpha numeric character and special characters like ^[a-zA-Z0-9_\-@,. ":]{0,255}$
- `response` (object, required): The request id is from the /discover callback. Allows alpha numeric characters and special characters like "^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}"
- `response.requestId` (string, required): The request id that was passed

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1106 - Duplicate On discovery request. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required): The request id from discover call back .Allows alpha numeric characters and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"


---

# Link care context on init

`POST /api/hiecm/user-initiated-linking/v3/link/care-context/on-init`

Share the response of the /api/hiecm/user-initiated-linking/v3/link/care-context/on-init API. By using this API, the HIP communicates the outcome of the care context linking process, ensuring that the system accurately reflects the status of the operation. This process is essential for maintaining the integrity and synchronization of patient health records, supporting seamless and efficient health information exchange within the healthcare ecosystem.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/user-initiated-linking/v3/link/care-context/on-init \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "transactionId": "f901b782-bfdf-4224-9f8d-da2cadc20c0d",
  "link": {
    "referenceNumber": "d353b782-bfdf-4224-9f8d-da2cadc20c0d",
    "authenticationType": "DIRECT",
    "meta": {
      "communicationMedium": "MOBILE",
      "communicationHint": "OTP",
      "communicationExpiry": "2024-05-01T05:22:34.123Z"
    }
  },
  "response": {
    "requestId": "f29f0e59-8388-4698-9fe6-05db67aeac46"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `transactionId` (string, required): UUID from discover request callback to track the entire user link flow.
- `link` (object, required)
- `link.referenceNumber` (string, required): The link reference number. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. ()/:\\\\]{0,255}$"
- `link.authenticationType` (string, required): The type of authentication.Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$" One of: DIRECT, MEDIATED.
- `link.meta` (object, required)
- `link.meta.communicationMedium` (string, required): The communication medium. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$" One of: MOBILE, EMAIL.
- `link.meta.communicationHint` (string, required): The communication hint. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"
- `link.meta.communicationExpiry` (string, required): The communication expiry date. Should be UTC date in ISO format. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"
- `error` (object): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"
- `response` (object, required): The request id is from the link/init callback. Allows alpha numeric characters and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"
- `response.requestId` (string, required): The request id that was passed

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1107 - Duplicate On init request. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required): The request id from discover call back .Allows alpha numeric characters and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"


---

# Link care context on confirm

`POST /api/hiecm/user-initiated-linking/v3/link/care-context/on-confirm`

Share the response of the /api/hiecm/user-initiated-linking/v3/link/care-context/on-confirm API. By using this API, the HIP communicates the outcome of the care context confirmation process, ensuring that the system accurately reflects the status of the operation. This process is essential for maintaining the integrity and synchronization of patient health records, supporting seamless and efficient health information exchange within the healthcare ecosystem.

In case of success scenario, patient object is mandatory and error object is optional

In case of error scenario, error object is mandatory and patient object is optional

Response is mandatory in both scenarios

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/user-initiated-linking/v3/link/care-context/on-confirm \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "patient": [
    {
      "referenceNumber": "<ABHA_ADDRESS>",
      "display": "12345",
      "careContexts": [
        {
          "referenceNumber": "abc123",
          "display": "12345"
        }
      ],
      "hiType": "Prescription",
      "count": 1
    }
  ],
  "response": {
    "requestId": "f29f0e59-8388-4698-9fe6-05db67aeac46"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `patient` (object[], required)
- `patient.referenceNumber` (string, required): A patient identifier with which patient is registered in the facility/hospital.Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. ()/:\\\\]{0,255}$"
- `patient.display` (string, required): Display text for patient reference. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"
- `patient.careContexts` (object[], required): List of care contexts linked at the HIP end for the identified patient.
- `patient.careContexts.referenceNumber` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data).Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. ()/:\\\\]{0,255}$"
- `patient.careContexts.display` (string, required): Display text for care context reference. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"
- `patient.hiType` (string, required): The health information type One of: DiagnosticReport, DischargeSummary, HealthDocumentRecord, ImmunizationRecord, OPConsultation, Prescription, WellnessRecord, Invoice.
- `patient.count` (integer, required): The count should match the number of care contexts in the payload
- `error` (object): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message
- `response` (object, required): The request id is from the link/confirm callback. Allows alpha numeric characters and special characters like "^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}"
- `response.requestId` (string, required): The request id that was passed

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1108 - Notification DB service unavailable. May be returned either bare (`ABDM-1108`) or with a trailing ": " separator (`ABDM-1108: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)


---

# Receive the HIP token on generate token

`POST /api/v3/hip/token/on-generate-token`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
"This API endpoint serves as a callback for the /api/hiecm/v3/token/generate-token API which will by the HIE-CM, the HIE-CM will validate the request and if everything is correct, a link token will be generated and is provided in the call-back API, or If anything incorrect in the request which demographics details then it will give the error in the same call back API. It is used to handle the response from the token generation process, ensuring that the HIP can securely manage and use the generated link token. This callback mechanism is essential for maintaining the integrity and security of the token-based linking process, supporting seamless and efficient health information exchange within the healthcare ecosystem."

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hip/token/on-generate-token \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "abhaAddress": "<ABHA_ADDRESS>",
  "linkToken": "<TOKEN>",
  "response": {
    "requestId": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `abhaAddress` (string, required)
- `linkToken` (string)
- `response` (object, required)
- `response.requestId` (string, required): The requestId that was passed

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900902 - Missing Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors


---

# Link on carecontext

`POST /api/v3/link/on_carecontext`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This API endpoint serves as a callback for the /api/hiecm/hip/v3/link/carecontext API. It is used to communicate the outcome of the care context linking process. The response will vary based on the success or failure of the linking operation:

If the linking is successful, pass the successful message

If the linking is unsuccessful, pass the error message with the error code and message

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/link/on_carecontext \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "abhaAddress": "<ABHA_ADDRESS>",
  "status": "Successfully Linked care context",
  "response": {
    "requestId": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `abhaAddress` (string, required)
- `status` (string, required) One of: Successfully Linked care context, Failed to link care context, invalid   [invalid request].
- `response` (object, required)
- `response.requestId` (string, required): The requestId that was passed

## Responses

- `200`: OK
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare (`ABDM-1006`) or with a trailing ": " separator (`ABDM-1006: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900902 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `message` (string)


---

# Receive the links context on notify

`POST /api/v3/links/context/on-notify`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This API endpoint is a call back API for /api/hiecm/hip/v3/link/context/notify

If the notification to CM is successful, pass the successful message

If the notification to CMis unsuccessful, pass the error message with the error code and message

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/links/context/on-notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "acknowledgement": {
    "status": "SUCCESS"
  },
  "error": {
    "code": "ABDM-1006",
    "message": "No links found for the patient in the given HIP"
  },
  "response": {
    "requestId": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `acknowledgement` (object, required)
- `acknowledgement.status` (string, required) One of: SUCCESS, ERRORED.
- `error` (object): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare (`ABDM-1006`) or with a trailing ": " separator (`ABDM-1006: `); match on the code itself and tolerate the separator.
- `error.message` (string, required)
- `response` (object, required)
- `response.requestId` (string, required): The requestId that was passed

## Responses

- `200`: OK
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare (`ABDM-1006`) or with a trailing ": " separator (`ABDM-1006: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900902 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `message` (string)


---

# Receive the patients SMS on notify

`POST /api/v3/patients/sms/on-notify`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This API endpoint is a call back API for /api/hiecm/hip/v3/link/patient/links/sms/notify2

If the SMS trigger is successful, pass the successful message

If the SMS trigger is unsuccessful, pass the error message with the error code and message

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/patients/sms/on-notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "acknowledgement": {
    "status": "SUCCESS"
  },
  "error": {
    "code": "ABDM-1024",
    "message": "Dependent service unavailable"
  },
  "response": {
    "requestId": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `acknowledgement` (object, required)
- `acknowledgement.status` (string, required) One of: SUCCESS, ERRORED.
- `error` (object): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
- `error.message` (string, required)
- `response` (object, required)
- `response.requestId` (string, required): The requestId that was passed

## Responses

- `200`: OK
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare (`ABDM-1006`) or with a trailing ": " separator (`ABDM-1006: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900902 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `message` (string)


---

# Discover care contexts associated with a patient

`POST /api/v3/hip/patient/care-context/discover`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
The discover API endpoint facilitates the discovery of care contexts linked to a specific patient. When a request is made to this endpoint, it returns detailed information about the patient, including verified and unverified identifiers, ensuring accurate patient identification and continuity of care.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hip/patient/care-context/discover \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "transactionId": "f901b782-bfdf-4224-9f8d-da2cadc20c0d",
  "patient": {
    "id": "<ABHA_ADDRESS>",
    "verifiedIdentifiers": [
      {
        "type": "MR",
        "value": "+919876543210"
      }
    ],
    "unverifiedIdentifiers": [
      {
        "type": "MOBILE",
        "value": "+9198765*****"
      }
    ],
    "name": "<NAME>",
    "gender": "M",
    "yearOfBirth": 9999
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `transactionId` (string, required): UUID
- `patient` (object, required)
- `patient.id` (string, required): A patient identifier with which patient is registered in the facility/hospital
- `patient.verifiedIdentifiers` (object[], required)
- `patient.verifiedIdentifiers.type` (string, required) One of: MR, MOBILE, ABHA_NUMBER, ABHA_ADDRESS, EMAIL.
- `patient.verifiedIdentifiers.value` (string, required): Allows alphanumeric characters and special characters like "^(\\+)?[a-zA-Z0-9_\\-@,. ]{0,255}$".
- `patient.unverifiedIdentifiers` (object[]): Identifiers with which the HIP will search for the patient in its own records.
- `patient.unverifiedIdentifiers.type` (string, required) One of: MR, MOBILE, ABHA_NUMBER, ABHA_ADDRESS, EMAIL.
- `patient.unverifiedIdentifiers.value` (string, required): Allows alphanumeric characters and special characters like "^(\\+)?[a-zA-Z0-9_\\-@,. ]{0,255}$".
- `patient.name` (string, required)
- `patient.gender` (string, required) One of: M, F, O, D, T, U.
- `patient.yearOfBirth` (number, required)

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1103 - Duplicate Discovery request. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)


---

# Initiate the linking of care contexts for a patient

`POST /api/v3/hip/link/care-context/init`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
The init API endpoint facilitates the initial linking of care contexts to a patient’s ABHA address. When a request is made to this endpoint, it returns a response containing the transaction ID, ABHA address, patient details, and any errors encountered. This ensures that patient care contexts are accurately linked and managed within the healthcare system.

**Note:**
Incase of success, HIP will get the patient details in the callback.
In case of failure, HIP will get the error response in the callback.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hip/link/care-context/init \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "transactionId": "f901b782-bfdf-4224-9f8d-da2cadc20c0d",
  "abhaAddress": "<ABHA_ADDRESS>",
  "patient": [
    {
      "referenceNumber": "abc123",
      "display": "Test",
      "careContexts": [
        {
          "referenceNumber": "abc123",
          "display": "Blood Test"
        }
      ],
      "hiType": "Prescription",
      "count": 1
    }
  ],
  "error": {
    "code": "ABDM-1001",
    "message": "No data found"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `transactionId` (string, required)
- `abhaAddress` (string, required): A patient identifier with which patient is registered in the facility/hospital.Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\-@,. ()/:\\]{0,255}$"
- `patient` (object[], required)
- `patient.referenceNumber` (string, required): A patient identifier with which patient is registered in the facility/hospital. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\-@,. ()/:\\]{0,255}$"
- `patient.display` (string, required): The display text of patient.Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"
- `patient.careContexts` (object[], required): List of care contexts linked at the HIP end for the identified patient.
- `patient.careContexts.referenceNumber` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data).Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\-@,. ()/:\\]{0,255}$"
- `patient.careContexts.display` (string, required): The display of care context.Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"
- `patient.hiType` (string, required): The health information type One of: DiagnosticReport, DischargeSummary, HealthDocumentRecord, ImmunizationRecord, OPConsultation, Prescription, WellnessRecord, Invoice.
- `patient.count` (integer): The count should match the number of care contexts in the payload
- `error` (object): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message

## Responses

- `200`: Ok
  - `transactionId` (string)
  - `abhaAddress` (string)
  - `patient` (object[])
  - `patient.referenceNumber` (string): Reference number used while linking the health records of the patient.
  - `patient.careContexts` (object[]): List of care contexts linked at the HIP end for the identified patient.
  - `patient.careContexts.referenceNumber` (string): Reference number used while linking the health records of the patient.
  - `patient.hiType` (string) One of: DiagnosticReport, DischargeSummary, HealthDocumentRecord, ImmunizationRecord, OPConsultation, Prescription, WellnessRecord, Invoice.
  - `patient.count` (integer): Number of health records in the careContext object.
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1104 - Duplicate Init request. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required): The request id that was passed.Allows alpha numeric characters and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"

Example 200 response. The values are placeholders:

```json
{
  "transactionId": "c1ce50dc-d1f7-4a31-987a-c6bf6d08ad5a",
  "abhaAddress": "<ABHA_ADDRESS>",
  "patient": [
    {
      "referenceNumber": "<ABHA_ADDRESS>",
      "careContexts": [
        {
          "referenceNumber": "New test 1"
        }
      ],
      "hiType": "OPConsultation",
      "count": 1
    }
  ]
}
```


---

# Confirm the linking of care contexts for a patient

`POST /api/v3/hip/link/care-context/confirm`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
The confirm API endpoint facilitates the confirmation of care context linking for a patient. When a request is made to this endpoint, it verifies the linking process using a provided token and reference number. This ensures that the care contexts are accurately linked to the patient’s ABHA (Ayushman Bharat Health Account) address.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hip/link/care-context/confirm \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "confirmation": {
    "token": 123456,
    "linkRefNumber": "d353b782-bfdf-4224-9f8d-da2cadc20c0d"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `confirmation` (object, required)
- `confirmation.token` (integer, required): The token number. Must be 6 digit and contain only 0-9
- `confirmation.linkRefNumber` (string, required): The link reference number random uuid. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"

## Responses

- `200`: OK
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1105 - Duplicate Confirm request. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required): The request id that was passed.Allows alpha numeric characters and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"


---

# Receive the consent decision

`POST /api/v3/consent/request/hip/notify`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
Notification of consents to health information providers consent request granted, consent revoked, consent expired. Only the GRANTED, REVOKED and EXPIRED status notifications will be sent to HIP. If consent is granted, status=GRANTED, then consentDetail contains the consent artefact details and signature is available. If consent is revoked, then status=REVOKED, and consentId specifes which consent artefact is revoked. If the consent has expired, then status=EXPIRED, and consentId specifies which consent artefact has expired. Note, this is also responsibility of the HIP to keep track of consent expiry. Any data request on expired consent artefact must not be done.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/v3/consent/request/hip/notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "notification": {
    "status": "GRANTED",
    "consentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "consentDetail": {
      "schemaVersion": "v3",
      "consentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "createdAt": "2024-05-01T05:10:20.123Z",
      "patient": {
        "id": "<ABHA_ADDRESS>"
      },
      "careContexts": [
        {
          "patientReference": "batman@tmh",
          "careContextReference": "Episode1"
        }
      ],
      "purpose": {
        "text": "Care Management",
        "code": "CAREMGT",
        "refUri": "www.abc.com"
      },
      "hip": {
        "id": "cowin_hip_01",
        "name": "Cowin",
        "type": "HIP"
      },
      "hiu": {
        "id": "cowin_hiu_01",
        "name": "Cowin",
        "type": "HIU"
      },
      "consentManager": {
        "id": "abdm"
      },
      "requester": {
        "name": "<ABHA_ADDRESS>",
        "identifier": {
          "value": "REG1",
          "type": "MH1001",
          "system": "https://www.sample.com"
        }
      },
      "hiTypes": [
        "Prescription"
      ],
      "permission": {
        "accessMode": "VIEW",
        "dateRange": {
          "from": "2021-09-28T12:30:08.573Z",
          "to": "2021-09-28T12:30:08.573Z"
        },
        "dataEraseAt": "2021-09-28T12:30:08.573Z",
        "frequency": {
          "unit": "HOUR",
          "value": 1,
          "repeats": 0
        }
      }
    },
    "signature": "e8nY601CYDsC0FKoDjSp+7GeQ2s2R8oZncLCz5ce+pEuDOr5bZV0aaHjwJg4b9S9V+twjt4hbojx3fl7egrt8+0c+lfPTi5/bBUAQXCABTfFmtFU7jn65HlTt8kgkiONx26ZBhJ0wX3xjYI72PPtzYIiT5Q08YtDoILA62KceioV7lwuKssw7wC4ECbBAvRuXT121TmtrPhf+0myJATSnaajS06S6OthrKfZLNTUFf3pFiJzqouSTrjNblOX6DT2+JuO3rom1Szz/03c0HQG+wWASv+PO3J6uRs0UI4JvKmM/4tP+Z+/HPKM15K5U5K+4pqf6czKrbIDpkT/kP8bGg==",
    "grantAcknowledgement": false
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `notification` (object, required)
- `notification.status` (string, required) One of: GRANTED, EXPIRED, DENIED, REQUESTED, REVOKED.
- `notification.consentId` (string, required): Allows alpha numeric character and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$";
- `notification.consentDetail` (object, required)
- `notification.consentDetail.schemaVersion` (string, required)
- `notification.consentDetail.consentId` (string, required): Allows alpha numeric character and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$";
- `notification.consentDetail.createdAt` (string, required): Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `notification.consentDetail.patient` (object, required)
- `notification.consentDetail.patient.id` (string, required): The abha address of the patient. Allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.]+[a-zA-Z0-9]@(abdm|sbx)$
- `notification.consentDetail.careContexts` (object[], required): List of care contexts linked at the HIP end for the identified patient.
- `notification.consentDetail.careContexts.patientReference` (string, required): A patient identifier with which patient is registered in the facility/hospital. Allows alpha numeric and special characters like "^[a-zA-Z0-9_\\-@,().\"/: ]{0,255}$"
- `notification.consentDetail.careContexts.careContextReference` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data). Allows alpha numeric and special characters like  "^[a-zA-Z0-9_\\-@,().\"/:| ]{0,255}$"
- `notification.consentDetail.purpose` (object, required)
- `notification.consentDetail.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
- `notification.consentDetail.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
- `notification.consentDetail.purpose.refUri` (string, required): The reference URL. Should be a valid URL. Allows alpha numeric character and special characters like ^[a-zA-Z0-9_\\-@,. \":/]{0,255}$
- `notification.consentDetail.hip` (object, required): Identifier and name of the health information provider.
- `notification.consentDetail.hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `notification.consentDetail.hip.name` (string, required): The name of the health information provider. Allows alpha numeric and special characters like ^[a-zA-Z0-9_\\-@,. \":/]{0,255}$
- `notification.consentDetail.hip.type` (string): The type of the health information provider. Allows alpha numeric and special characters like ^[a-zA-Z0-9_\\-@,. \":/]{0,255}$
- `notification.consentDetail.hiu` (object, required)
- `notification.consentDetail.hiu.id` (string, required): The service ID of the health information user.  Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `notification.consentDetail.hiu.name` (string, required): The name of the health information user. Allows alpha numeric and special characters like ^[a-zA-Z]+[A-Za-z0-9_\\-@,().\\s\\xa0:/]+
- `notification.consentDetail.hiu.type` (string): The type of the health information user. Allows alpha numeric and special characters like ^[a-zA-Z0-9_\\-@,. \":/]{0,255}$
- `notification.consentDetail.consentManager` (object, required)
- `notification.consentDetail.consentManager.id` (string, required)
- `notification.consentDetail.requester` (object, required)
- `notification.consentDetail.requester.name` (string, required): The name of the requester
- `notification.consentDetail.requester.identifier` (object, required)
- `notification.consentDetail.hiTypes` (string[], required): Types of health information document.
- `notification.consentDetail.permission` (object, required)
- `notification.consentDetail.permission.accessMode` (string, required) One of: VIEW, STORE, STREAM, QUERY.
- `notification.consentDetail.permission.dateRange` (object, required)
- `notification.consentDetail.permission.dataEraseAt` (string, required): The date at which the consent expire. Should be UTC date time in ISO format.Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `notification.consentDetail.permission.frequency` (object, required)
- `notification.signature` (string, required)
- `notification.grantAcknowledgement` (boolean, required)

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Receive the health information data request to HIP

`POST /api/v3/hip/health-information/request`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
Callback API to provide Health information request of HIP. CM calls this API when it has validated the Health Information request given the consent ID.
 Either the hiRequest or error would need to be specified. If the health info request was valid, then the hiRequest.transactionId specifies the transaction context against which HIP would send over the data.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hip/health-information/request \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "transactionId": "49455d89-cb13-483d-ad71-7a57d5f669a8",
  "hiRequest": {
    "consent": {
      "id": "18235d89-cb13-479d-ad71-7a57d5f669a8"
    },
    "dateRange": {
      "from": "2022-10-06T15:10:00.587Z",
      "to": "2022-11-06T15:10:00.587Z"
    },
    "dataPushUrl": "https://live.ndhm.gov.in/api-hiu/data/notification",
    "keyMaterial": {
      "cryptoAlg": "ECDH",
      "curve": "curve25519",
      "dhPublicKey": {
        "expiry": "2022-12-28T13:18:20.742Z",
        "parameters": "Ephemeral public key",
        "keyValue": "BFN7KTdOT0jIAExG2A8Jg+01wMPWxptiGqwHRVvtiVEsUq2FR7P2UdqZxJyPJSeR6muai21iQhasNxnhh8I5M+g="
      },
      "nonce": "28236d89-cb13-479d-ad71-7a57d5f669a9"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `transactionId` (string, required)
- `hiRequest` (object, required)
- `hiRequest.consent` (object, required)
- `hiRequest.consent.id` (string, required): The consent artefact id for health information request. Allows alpha numeric character and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$"
- `hiRequest.dateRange` (object, required): Health information created between this date range is requested
- `hiRequest.dateRange.from` (string, required): Should be a UTC date time in ISO Format. Allows alpha numeric character and special characters like \\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$
- `hiRequest.dateRange.to` (string, required): Should be a UTC date time in ISO Format.Allows alpha numeric character and special characters like \\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$
- `hiRequest.dataPushUrl` (string, required): The URL to which the Health Information Provider has to send the health information data. Allows alpha numeric character and special characters like ^[a-zA-Z0-9_\\-@,. \":/]{0,255}$
- `hiRequest.keyMaterial` (object, required): The requester's half of the ECDH key agreement. The HIP derives the shared key from it and its own key pair, and encrypts every entry it pushes with AES-GCM.
- `hiRequest.keyMaterial.cryptoAlg` (string, required): The key agreement algorithm. Always ECDH.
- `hiRequest.keyMaterial.curve` (string, required): The curve the key pair is generated on. Always Curve25519.
- `hiRequest.keyMaterial.dhPublicKey` (object, required): The public half of the ephemeral key pair generated for this transaction.
- `hiRequest.keyMaterial.dhPublicKey.expiry` (string, required): When this key stops being valid, as an ISO 8601 timestamp.
- `hiRequest.keyMaterial.dhPublicKey.parameters` (string, required): The key parameters. Ephemeral public key.
- `hiRequest.keyMaterial.dhPublicKey.keyValue` (string, required): The public key, Base64 encoded, in X.509 SubjectPublicKeyInfo form.
- `hiRequest.keyMaterial.nonce` (string): 32 random bytes, Base64 encoded, generated for this transaction. The other side combines it with its own nonce to derive the AES-GCM key and initialisation vector.

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string, required): 404 - Runtime error. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `type` (string, required)
  - `message` (string, required)
  - `description` (string, required)


---

# Receive the transferred health information

`POST /health-information/transfer`

**NOTE:** This API is actually the callback URL that is passed as `dataPushUrl` in the data request API - `/api/v3/hip/health-information/request`. This API is directly called by HIP Data Bridge and is not mediated via CM, and hence not routed through the Gateway.

This API should be implemented at HIU side. It may be implemented by the Data Bridge representing the HIU.

Entry elements may be content or link, although for version 1, entry content is preferred.

Entry content (or even link reference content) must be encrypted by means of Elliptic-curve Diffie–Hellman Key Exchange, using the HIU key materials that are passed through the data request API - `/api/v3/hip/health-information/request`.

Media contains the mimetype of content, and for v1, it is "application/fhir+json".

Checksum is MD5 checksum of the data content, before encryption.

Please refer to the ABDM Sandbox Documentation for the format of FHIR bundle that is passed through content.

**Authorisation token is mandatory for this API.**

```bash
curl --request POST \
  --url {bridgeUrl}/health-information/transfer \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "pageNumber": 0,
  "pageCount": 1,
  "transactionId": "<TRANSACTION_ID>",
  "entries": [
    {
      "content": "Encrypted content of data packaged in FHIR bundle",
      "media": "application/fhir+json",
      "checksum": "string",
      "careContextReference": "1931-nd2"
    }
  ],
  "keyMaterial": {
    "cryptoAlg": "ECDH",
    "curve": "Curve25519",
    "dhPublicKey": {
      "expiry": "<EXPIRY>",
      "parameters": "Curve25519/32byte random key",
      "keyValue": "<KEY_VALUE>"
    },
    "nonce": "<NONCE>"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Body

- `pageNumber` (integer, required): Current page number.
- `pageCount` (integer, required): Total number of pages.
- `transactionId` (string, required): Transaction Id issued when data requested.
- `entries` (object[], required)
- `entries.content` (string, required): Encrypted content
- `entries.media` (string, required) One of: application/fhir+json.
- `entries.checksum` (string, required): Md5 checksum of the content before encryption
- `entries.careContextReference` (string, required): care context reference number.
- `keyMaterial` (object, required): Encryption and decryption key details.
- `keyMaterial.cryptoAlg` (string, required) One of: ECDH.
- `keyMaterial.curve` (string, required) One of: Curve25519.
- `keyMaterial.dhPublicKey` (object, required)
- `keyMaterial.dhPublicKey.expiry` (string, required)
- `keyMaterial.dhPublicKey.parameters` (string, required): Parameters of the encryption and decryption key. One of: Curve25519/32byte random key.
- `keyMaterial.dhPublicKey.keyValue` (string, required)
- `keyMaterial.nonce` (string, required)

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): 4500 - Unknown error. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors


---

# Acknowledge the consent notification

`POST /api/hiecm/consent/v3/request/hip/on-notify`

Notification of consents, in cases of consent approval, revocation and expiration. Notified by CM earlier via Gateway API - **/api/v3/consent/request/hip/notify**

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/request/hip/on-notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "acknowledgement": {
    "status": "OK",
    "consentId": "e3c74829-3f82-4f94-959e-e10f57bcd57b"
  },
  "response": {
    "requestId": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `acknowledgement` (object, required)
- `acknowledgement.status` (string, required): The status of the notification.  Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `acknowledgement.consentId` (string, required): The consent artefact id. Should be valid UUID. Allows alpha numeric character and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$";
- `error` (object): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message
- `response` (object, required): The request id is from the /consent/request/hip/notify callback
- `response.requestId` (string, required): The requestId that was passed. it must be in Alpha numeric and - in middle and Allows alpha numeric character and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Submit the health information data request acknowledgement from HIP

`POST /api/hiecm/data-flow/v3/health-information/hip/on-request`

Acknowledge the Health information request receipt. Either the hiRequest or error must be specified. hiRequest element returns the same transaction ID as before with a status indicating that the request is acknowledged.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/data-flow/v3/health-information/hip/on-request \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "hiRequest": {
    "transactionId": "18235d89-cb13-479d-ad71-7a57d5f669a8",
    "sessionStatus": "ACKNOWLEDGED"
  },
  "response": {
    "requestId": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `hiRequest` (object, required)
- `hiRequest.transactionId` (string, required): The UUID generated when the health information request was initiated.Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `hiRequest.sessionStatus` (string, required): The status of the health information request that was initiated.Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `response` (object, required): The request id from the /hip/health-information/request callback. Allows alpha numeric character and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"
- `response.requestId` (string, required): The requestId that was passed

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string, required): ABDM-1031 - Invalid request. May be returned either bare (`ABDM-1031`) or with a trailing ": " separator (`ABDM-1031: `); match on the code itself and tolerate the separator.
  - `message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string, required): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)
  - `description` (string, required)
- `403`: Access Denied
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Submit the notifications corresponding to events during data flow

`POST /api/hiecm/data-flow/v3/health-information/notify`

HIU and HIP during data transfer. HIP on the transfer of data would send sessionStatus - one of [TRANSFERRED, FAILED] HIP would also send hiStatus for each careContextReference - on of [DELIVERED, ERRORED] HIU on receipt of data would send sessionStatus - one of [RECEIVED, FAILED]. For example, FAILED when data was not sent or if invalid data was sent HIU would also send hiStatus for each careContextReference - one of [OK, ERRORED]

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/data-flow/v3/health-information/notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "notification": {
    "consentId": "18235d89-cb13-479d-ad71-7a57d5f669a8",
    "transactionId": "18235d89-cb13-479d-ad71-7a57d5f669a8",
    "doneAt": "2023-01-24T06:35:44.167Z",
    "notifier": {
      "type": "HIU",
      "id": "100005"
    },
    "statusNotification": {
      "sessionStatus": "RECEIVED",
      "hipId": "IN2810014366",
      "statusResponses": [
        {
          "careContextReference": "10004-20200001768-1",
          "hiStatus": "OK",
          "description": "Data received successfully"
        }
      ]
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `notification` (object, required)
- `notification.consentId` (string, required): The consent artefact id with which health information was requested.Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `notification.transactionId` (string, required): The UUID generated when the health information request was initiated.Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `notification.doneAt` (string, required): The date at which the transaction was initiated. Should be a UTC date time in ISO format. Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `notification.notifier` (object, required)
- `notification.notifier.type` (string, required): The Service ID.Allows alpha numeric characters and special characters like  "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$" One of: HIU, HIP.
- `notification.notifier.id` (string, required): The service ID of the notifier. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `notification.statusNotification` (object, required)
- `notification.statusNotification.sessionStatus` (string, required): The status of the health information request that was initiated. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `notification.statusNotification.hipId` (string, required): The service ID of the health information provider. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `notification.statusNotification.statusResponses` (object[], required)
- `notification.statusNotification.statusResponses.careContextReference` (string, required): The care context reference number.Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `notification.statusNotification.statusResponses.hiStatus` (string, required): The status of the health information transfer. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `notification.statusNotification.statusResponses.description` (string, required): The brief description of the status. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string, required): ABDM-1031 - Invalid request. May be returned either bare (`ABDM-1031`) or with a trailing ": " separator (`ABDM-1031: `); match on the code itself and tolerate the separator.
  - `message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string, required): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)
  - `description` (string, required)
- `403`: Access Denied
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# M2 Health Information Provider errors

Seeing a symptom rather than a code? Start at [Troubleshooting](/docs/hiecm/v3/troubleshooting/).

During ABDM integration, systems may encounter issues across discovery, linking, consent, encryption, and data exchange workflows. This section outlines common errors, their causes, and recommended resolutions to help ensure smooth implementation.

## Codes

| Code        | HTTP | Message                                                                                                                                                    | Returned by |
| ----------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `ABDM-1000` |      | Unable to connect the database                                                                                                                             |             |
| `ABDM-1001` |      | No data found                                                                                                                                              |             |
| `ABDM-1004` |      | SMS Gateway is unavailable                                                                                                                                 |             |
| `ABDM-1006` |      | Bad Request, invalid request Body                                                                                                                          |             |
| `ABDM-1007` |      | Connection failed due to timeout                                                                                                                           |             |
| `ABDM-1008` |      | SMS service currently disabled                                                                                                                             |             |
| `ABDM-1010` |      | Validation failed                                                                                                                                          |             |
| `ABDM-1011` |      | Gateway database unavailable                                                                                                                               |             |
| `ABDM-1012` |      | No records found against the ABHA Address                                                                                                                  |             |
| `ABDM-1013` |      | Invalid ABHA Number                                                                                                                                        |             |
| `ABDM-1015` |      | Invalid Response                                                                                                                                           |             |
| `ABDM-1016` |      | Invalid TimeStamp                                                                                                                                          |             |
| `ABDM-1017` |      | Invalid TransactionId                                                                                                                                      |             |
| `ABDM-1018` |      | Share Profile database unavailable                                                                                                                         |             |
| `ABDM-1019` |      | Dependent Service Unavailable                                                                                                                              |             |
| `ABDM-1020` |      | Unknown database                                                                                                                                           |             |
| `ABDM-1022` |      | Too many requests                                                                                                                                          |             |
| `ABDM-1023` |      | Invalid User                                                                                                                                               |             |
| `ABDM-1024` |      | Dependent service unavailable                                                                                                                              |             |
| `ABDM-1025` |      | Invalid ServiceId                                                                                                                                          |             |
| `ABDM-1026` |      | Invalid Link Token                                                                                                                                         |             |
| `ABDM-1027` |      | You are blocked. Please try again after 24 hours.                                                                                                          |             |
| `ABDM-1028` |      | HIP is unavailable                                                                                                                                         |             |
| `ABDM-1029` |      | Redis server is unavailable                                                                                                                                |             |
| `ABDM-1030` |      | Invalid request ID                                                                                                                                         |             |
| `ABDM-1031` |      | Invalid request                                                                                                                                            |             |
| `ABDM-1032` |      | Invalid header                                                                                                                                             |             |
| `ABDM-1033` |      | HIU is unavailable                                                                                                                                         |             |
| `ABDM-1034` |      | Notification service unavailable                                                                                                                           |             |
| `ABDM-1035` |      | Invalid HIP ID                                                                                                                                             |             |
| `ABDM-1036` |      | Data does not matched                                                                                                                                      |             |
| `ABDM-1037` |      | Counter and Care context count mismatch                                                                                                                    |             |
| `ABDM-1038` |      | ABHA address and Link token mismatch                                                                                                                       |             |
| `ABDM-1040` |      | Invalid HIU ID                                                                                                                                             |             |
| `ABDM-1041` |      | Invalid Acknowledgement                                                                                                                                    |             |
| `ABDM-1042` |      | Provider Mandatory                                                                                                                                         |             |
| `ABDM-1043` |      | ABHA Address does not match with KYC details.                                                                                                              |             |
| `ABDM-1044` |      | Broadcast Failed                                                                                                                                           |             |
| `ABDM-1045` |      | Database Access is restricted                                                                                                                              |             |
| `ABDM-1046` |      | Invalid Purpose                                                                                                                                            |             |
| `ABDM-1047` |      | Purpose does not exist                                                                                                                                     |             |
| `ABDM-1048` |      | Timeout                                                                                                                                                    |             |
| `ABDM-1049` |      | Invalid Profile Share Intent Keys                                                                                                                          |             |
| `ABDM-1050` |      | Invalid Profile Share Metadata Keys                                                                                                                        |             |
| `ABDM-1051` |      | Invalid ABHA Number or ABHA Address                                                                                                                        |             |
| `ABDM-1052` |      | Invalid TransactionId or response's requestId                                                                                                              |             |
| `ABDM-1401` |      | HIP is not available                                                                                                                                       |             |
| `ABDM-1061` |      | Consent artefact expired                                                                                                                                   |             |
| `ABDM-1062` |      | Consent Not granted                                                                                                                                        |             |
| `ABDM-1063` |      | Date Range given is invalid                                                                                                                                |             |
| `ABDM-1064` |      | request with this request id already exists                                                                                                                |             |
| `ABDM-1109` |      | ABHA DB service unavailable                                                                                                                                |             |
| `ABDM-1108` |      | Notification DB service unavailable                                                                                                                        |             |
| `ABDM-1201` |      | IDP Gateway is unavailable                                                                                                                                 |             |
| `ABDM-9999` |      | Unknown exception                                                                                                                                          |             |
| `ABDM-1006` |      | Invalid combinations of scopes                                                                                                                             |             |
| `ABDM-1056` |      | This care contexts has been already linked                                                                                                                 |             |
| `ABDM-1055` |      | Invalid HIP Id or PHR Id                                                                                                                                   |             |
| `ABDM-1056` |      | Invalid Link Reference Number                                                                                                                              |             |
| `ABDM-1057` |      | Invalid Care Contexts                                                                                                                                      |             |
| `ABDM-1059` |      | Invalid Care Contexts count                                                                                                                                |             |
| `ABDM-1060` |      | Invalid Patient Reference Number                                                                                                                           |             |
| `ABDM-1061` |      | Invalid Patient Display                                                                                                                                    |             |
| `ABDM-1062` |      | ABHA number mismatch with Link token                                                                                                                       |             |
| `ABDM-1063` |      | HIP Id mismatch with Link token                                                                                                                            |             |
| `ABDM-1064` |      | Request body was missing                                                                                                                                   |             |
| `ABDM-1065` |      | Invalid X Auth token                                                                                                                                       |             |
| `ABDM-1066` |      | Invalid JWT token                                                                                                                                          |             |
| `ABDM-1067` |      | Request body not required                                                                                                                                  |             |
| `ABDM-1170` |      | Invalid ABHA address                                                                                                                                       |             |
| `ABDM-1084` |      | ABHA address mismatch with X Auth token                                                                                                                    |             |
| `ABDM-1085` |      | ABHA number mismatch with X Auth token                                                                                                                     |             |
| `ABDM-1086` |      | Patient profile mismatch with X Auth token                                                                                                                 |             |
| `ABDM-1087` |      | Duplicate patient share request                                                                                                                            |             |
| `ABDM-1090` |      | Duplicate HIP link request                                                                                                                                 |             |
| `ABDM-1091` |      | Duplicate Get links request                                                                                                                                |             |
| `ABDM-1092` |      | Duplicate Link token request                                                                                                                               |             |
| `ABDM-1093` |      | Duplicate Bridge request                                                                                                                                   |             |
| `ABDM-1094` |      | Duplicate bridge patch request                                                                                                                             |             |
| `ABDM-1095` |      | Duplicate Bridge service request                                                                                                                           |             |
| `ABDM-1102` |      | Profile information cannot be null                                                                                                                         |             |
| `ABDM-1103` |      | Duplicate Discovery request                                                                                                                                |             |
| `ABDM-1104` |      | Duplicate Init request                                                                                                                                     |             |
| `ABDM-1105` |      | Duplicate Confirm request                                                                                                                                  |             |
| `ABDM-1106` |      | Duplicate On discovery request                                                                                                                             |             |
| `ABDM-1107` |      | Duplicate On init request                                                                                                                                  |             |
| `ABDM-1108` |      | Duplicate On confirm request                                                                                                                               |             |
| `ABDM-1109` |      | Invalid On discovery response                                                                                                                              |             |
| `ABDM-1110` |      | Invalid On init response                                                                                                                                   |             |
| `ABDM-1111` |      | Invalid On confirm response                                                                                                                                |             |
| `ABDM-1112` |      | Invalid or already expired consent artefact id                                                                                                             |             |
| `ABDM-1113` |      | Duplicate health information provider data flow response                                                                                                   |             |
| `ABDM-1149` |      | Intent type is not supported at HIP end                                                                                                                    |             |
| `ABDM-1150` |      | Bridge API version cannot be null                                                                                                                          |             |
| `ABDM-1402` |      | Acknowledgement is not received from HIP                                                                                                                   |             |
| `ABDM-9999` |      | HIP is unable to generate a token at this time. Please try again later.                                                                                    |             |
| `ABDM-9999` |      | HIP is unable to process at this time. Please try again later.                                                                                             |             |
| `ABDM-1030` |      | Request id not found                                                                                                                                       |             |
| `ABDM-2500` |      | No mapping found for                                                                                                                                       |             |
| `ABDM-2401` |      | The X Auth token is invalid.                                                                                                                               |             |
| `ABDM-2402` |      | Invalid Timestamp                                                                                                                                          |             |
| `ABDM-2404` |      | Invalid Request Id                                                                                                                                         |             |
| `ABDM-2429` |      | Too many requests found                                                                                                                                    |             |
| `ABDM-2501` |      | Payment status should be : SUCCESS,CANCELED,PENDING,FAIL,REFUND\_INITIATED,REFUND\_SUCCESS                                                                 |             |
| `ABDM-2500` |      | Authorization header is missing                                                                                                                            |             |
| `ABDM-2403` |      | Invalid X-CM-ID                                                                                                                                            |             |
| `ABDM-2406` |      | Invalid API sequence flow, please follow logical flow                                                                                                      |             |
| `ABDM-2406` |      | The status is invalid. Please follow the logical status flow or transition.                                                                                |             |
| `ABDM-9999` |      | User not found                                                                                                                                             |             |
| `ABDM-9999` |      | Cannot process the request at the moment, please try later.                                                                                                |             |
| `ABDM-9001` |      | No open order against ABHA. Please ensure a minimum of one open order                                                                                      |             |
| `ABDM-9002` |      | No registration found at <>. Contact counter support                                                                                                       |             |
| `ABDM-9003` |      | Hospital services temporarily unavailable. Please try again after some time.                                                                               |             |
| `ABDM-9004` |      | Services disrupted, please try again.                                                                                                                      |             |
| `ABDM-9005` |      | Bank server not responding. Please try again later                                                                                                         |             |
| `ABDM-9006` |      | Service details mismatch. Please ensure original service ID from HMIS                                                                                      |             |
| `ABDM-9007` |      | The Scan and Pay functionality is not enabled at this facility. Kindly contact the hospital administration.                                                |             |
| `ABDM-1006` |      | Invalid count, must be 2 digit and ranges between 1 to 20                                                                                                  |             |
| `ABDM-1407` |      | The ABHA Number associated with this ABHA Address is currently deactivated. Please reactivate it.                                                          |             |
| `ABDM-1006` |      | Invalid HIType, it must be in Prescription,DiagnosticReport,OPConsultation,DischargeSummary,ImmunizationRecord,HealthDocumentRecord,WellnessRecord,Invoice |             |

A row with no HTTP status and no call is one NHA lists for this module (Sandbox2.0 M2 and M3 API review v2, NHA, 21 September 2026) without saying which call returns it.

Every code above is recorded in the specification that owns it. The aggregated list across modules is at [error codes](/docs/hiecm/v3/reference/error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# M2 Health Information Provider: Create and link records

Link care contexts to a patient's ABHA address, answer discovery requests, and share encrypted health records with consent.

## Base URLs

| Environment | Base URL                   |
| ----------- | -------------------------- |
| Sandbox     | `https://dev.abdm.gov.in`  |
| Production  | `https://apis.abdm.gov.in` |

The full operation list is in the [M2 API reference](/reference/hiecm-m2).

New to this? Start with [M2 Health Information Provider](/docs/hiecm/v3/milestones/m2).


---

# Receive the consent request for patient HIU

`POST /api/v3/hiu/consent/request/on-init`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
Result of consent request creation for a patient. **consentRequest.id** represents the consentrequest ID created by CM. The result must contain either**consentRequest** or the**error** caused. Reasons for error may be

 Invalid references (e.g patient ID, HIU ID), purpose, hiTypes, ranges, persmission

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hiu/consent/request/on-init \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "consentRequest": {
    "id": "f29f0e59-8388-4698-9fe6-05db67aeac46"
  },
  "error": {
    "code": "ABDM-1001",
    "message": "unable to connect database"
  },
  "response": {
    "requestId": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `consentRequest` (object, required)
- `consentRequest.id` (string, required): The consent request id from a consent. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\-@,. ":/]{0,255}$"
- `error` (object, required): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message
- `response` (object, required)
- `response.requestId` (string, required): The requestId that was passed. Allows alpha numeric character and special characters like ^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Receive the consent status request

`POST /api/v3/hiu/consent/request/on-status`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This API endpoint is used to provide the result of a previously submitted consent request. The status of the request can be one of the following: REQUESTED, DENIED, or EXPIRED. By invoking this API, the Health Information User (HIU) receives the outcome of their consent request, ensuring that they are informed about the current status. This functionality is essential for maintaining transparency and enabling HIUs to take appropriate actions based on the consent status. The API supports secure and compliant health information exchange, facilitating efficient consent management within the healthcare ecosystem.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hiu/consent/request/on-status \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "consentRequest": {
    "id": "e5ec415f-c098-40f6-a0db-faa162fc5295",
    "status": "REQUESTED"
  },
  "error": {
    "code": "ABDM-1001",
    "message": "unable to connect database"
  },
  "response": {
    "requestId": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
  },
  "resp": null
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `consentRequest` (object, required)
- `consentRequest.id` (string, required): The consent request id from a consent. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\-@,. ":/]{0,255}$"
- `consentRequest.status` (string, required) One of: REQUESTED, DENIED, EXPIRED, REVOKED.
- `error` (object, required): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message
- `response` (object, required)
- `response.requestId` (string, required): The requestId that was passed.Allows alpha numeric character and special characters like ^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}
- `resp` (string, required)

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Notify HIU when consent is APPROVED, DENIED or REVOKED

`POST /api/v3/hiu/consent/request/notify`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
Health information user will get notified about the consent request granted or denied, consent revoked, consent expired.
For consent request grant, status=GRANTED, consentRequestId=, and consentArtefacts is an array of generated consent artefact Ids. For consent request expiry, status=EXPIRED, consentRequestId= For consent request denied, status=DENIED, consentRequestId= For consent revocation, status=REVOKED, consentArtefacts is an array of revoked consent artefact ids.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hiu/consent/request/notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "notification": {
    "consentRequestId": "e3c74829-3f82-4f94-959e-e10f57bcd57b",
    "status": "GRANTED",
    "reason": null,
    "consentArtefacts": [
      {
        "id": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
      }
    ]
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `notification` (object, required)
- `notification.consentRequestId` (string, required): The consent request id from a consent. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\-@,. ":/]{0,255}$"
- `notification.status` (string, required) One of: GRANTED, EXPIRED, DENIED, REQUESTED, REVOKED.
- `notification.reason` (string, required)
- `notification.consentArtefacts` (object[], required): List of consent artefact ids that were created.
- `notification.consentArtefacts.id` (string, required)

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Receive the provide fetched consent artefact details to HIU

`POST /api/v3/hiu/consent/on-fetch`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This API endpoint is part of the Ayushman Bharat Digital Mission (ABDM) Health Information Exchange - Consent Management (HIE-CM) system. It is called by the Consent Management (CM) system to fetch a consent artefact. By invoking this API, the CM system retrieves the detailed information of a specific consent artefact, ensuring that the consent data is accurately and securely accessed. This functionality is essential for maintaining the integrity and synchronization of consent records, supporting secure and compliant health information exchange within the healthcare ecosystem.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hiu/consent/on-fetch \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "consent": {
    "status": "GRANTED",
    "consentDetail": {
      "consentId": "e5ec415f-c098-40f6-a0db-faa162fc5295",
      "hip": {
        "id": "cowin_hip_01",
        "name": "Cowin",
        "type": "HIP"
      },
      "hiu": {
        "id": "cowin_hiu_01",
        "name": "Cowin",
        "type": "HIU"
      },
      "hiTypes": [
        "Prescription"
      ],
      "patient": {
        "id": "<ABHA_ADDRESS>"
      },
      "purpose": {
        "text": "Care Management",
        "code": "CAREMGT",
        "refUri": "www.abc.com"
      },
      "createdAt": "2021-09-28T12:30:08.573Z",
      "requester": {
        "name": "<ABHA_ADDRESS>",
        "identifier": {
          "value": "REG1",
          "type": "MH1001",
          "system": "https://www.sample.com"
        }
      },
      "permission": {
        "accessMode": "VIEW",
        "dateRange": {
          "from": "2021-09-28T12:30:08.573Z",
          "to": "2021-09-28T12:30:08.573Z"
        }
      },
      "dataEraseAt": "2021-09-28T12:30:08.573Z",
      "frequency": {
        "unit": "HOUR",
        "value": 1,
        "repeats": 0
      },
      "lastUpdated": "2021-09-28T12:30:08.573Z",
      "careContexts": [
        {
          "patientReference": "batman@tmh",
          "careContextReference": "Episode1"
        }
      ],
      "schemaVersion": "v3",
      "consentManager": {
        "id": "abdm"
      }
    },
    "signature": "Signature of CM as defined in W3C standards; Base64 encoded"
  },
  "error": null,
  "response": {
    "requestId": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
  },
  "resp": null
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `consent` (object, required)
- `consent.status` (string, required) One of: GRANTED, DENIED, EXPIRED, REVOKED.
- `consent.consentDetail` (object, required)
- `consent.consentDetail.consentId` (string, required): Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `consent.consentDetail.hip` (object): Identifier and name of the health information provider.
- `consent.consentDetail.hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `consent.consentDetail.hip.name` (string, required): The name of the health information provider. Allows alpha numeric and special characters like _\-@,():/
- `consent.consentDetail.hip.type` (string): The type of the health information provider. Allows alpha numeric and special characters like _\-@,. ":/
- `consent.consentDetail.hiu` (object, required)
- `consent.consentDetail.hiu.id` (string, required): The service ID of the health information user.  Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `consent.consentDetail.hiu.name` (string, required): The name of the health information user. Allows alpha numeric and special characters like _\-@,():/
- `consent.consentDetail.hiu.type` (string): The type of the health information user. Allows alpha numeric and special characters like _\-@,. ":/
- `consent.consentDetail.hiTypes` (string[], required): Types of health information document.
- `consent.consentDetail.patient` (object, required)
- `consent.consentDetail.patient.id` (string, required): The abha address of the patient. allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.]+[a-zA-Z0-9]@(abdm|sbx)$
- `consent.consentDetail.purpose` (object, required)
- `consent.consentDetail.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
- `consent.consentDetail.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
- `consent.consentDetail.purpose.refUri` (string, required): The reference URL. Should be a valid URL.Allows alpha numeric character and special characters like ^[a-zA-Z0-9_\\-@,. \":/]{0,255}$
- `consent.consentDetail.createdAt` (string, required)
- `consent.consentDetail.requester` (object, required)
- `consent.consentDetail.requester.name` (string, required): The name of the requester
- `consent.consentDetail.requester.identifier` (object, required)
- `consent.consentDetail.permission` (object, required)
- `consent.consentDetail.permission.accessMode` (string, required) One of: VIEW, STORE, STREAM, QUERY.
- `consent.consentDetail.permission.dateRange` (object, required)
- `consent.consentDetail.dataEraseAt` (string, required): The date at which the consent expire. Should be UTC date time in ISO format. Allows alpha numeric character and special characters like ^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$
- `consent.consentDetail.frequency` (object, required)
- `consent.consentDetail.frequency.unit` (string, required) One of: HOUR, DAY, WEEK, MONTH, YEAR.
- `consent.consentDetail.frequency.value` (number, required): The frequency unit value. Should be be a integer. Allows numeric character like ^[a-zA-Z0-9_\\-@,. \":/]{0,255}$
- `consent.consentDetail.frequency.repeats` (number, required): Should be be a integer.Allows numeric character like ^[a-zA-Z0-9_\\-@,. \":/]{0,255}$
- `consent.consentDetail.lastUpdated` (string, required): lastUpdated of the consent.  Should be UTC date time in ISO format. Allows alpha numeric character and special characters like ^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$
- `consent.consentDetail.careContexts` (object[], required): List of care contexts linked at the HIP end for the identified patient.
- `consent.consentDetail.careContexts.patientReference` (string, required): A patient identifier with which patient is registered in the facility/hospital. Allows alpha numeric character and special characters like ^[a-zA-Z0-9_\-@,. "':|()/]{0,255}$
- `consent.consentDetail.careContexts.careContextReference` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data). Allows alpha numeric character and special characters like ^[a-zA-Z0-9_\-@,. "':|()/]{0,255}$
- `consent.consentDetail.schemaVersion` (string, required)
- `consent.consentDetail.consentManager` (object, required)
- `consent.consentDetail.consentManager.id` (string, required)
- `consent.signature` (string, required)
- `error` (object, required): The error code and message, if any occurred.
- `response` (object, required)
- `response.requestId` (string, required): The requestId that was passed.Allows alpha numeric character and special characters like ^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}
- `resp` (string)

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Receive the health information data request acknowledgement to HIU

`POST /api/v3/hiu/health-information/on-request`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
Callback API for acknowledgment of Health information request of HIU. CM calls this API when it has validated the Health Information request given the consent ID.
 Either the hiRequest or error would need to be specified. If the health info request was valid, then the hiRequest.transactionId specifies the transaction context against which HIP would send over the data.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hiu/health-information/on-request \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "hiRequest": {
    "transactionId": "18235d89-cb13-479d-ad71-7a57d5f669a8",
    "sessionStatus": "REQUESTED"
  },
  "error": {
    "code": "ABDM-1001",
    "message": "unable to connect database"
  },
  "response": {
    "requestId": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `hiRequest` (object, required)
- `hiRequest.transactionId` (string, required): The UUID generated when the health information request was initiated.
- `hiRequest.sessionStatus` (string, required): The status of the health information request that was initiated.
- `error` (object): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message
- `response` (object, required)
- `response.requestId` (string, required): The requestId that was passed. Allows alpha numeric character and special characters like ^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): 404 - Runtime error. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `type` (string, required)
  - `message` (string, required)
  - `description` (string, required)


---

# Initiate the consent request

`POST /api/hiecm/consent/v3/request/init`

Create a consent request by a Health Information User (HIU) to access a patient’s health data. By invoking this API, the HIU initiates the process of obtaining the necessary permissions from the patient to retrieve their health information. This consent request is a critical component of the health information exchange framework, ensuring that patient data is accessed in a secure, authorised, and transparent manner. The API supports the establishment of trust and compliance with privacy regulations, facilitating seamless and ethical health information exchange.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/request/init \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "consent": {
    "purpose": {
      "text": "Care Management",
      "code": "CAREMGT",
      "refUri": "www.abc.com"
    },
    "patient": {
      "id": "<ABHA_ADDRESS>"
    },
    "hip": null,
    "hiu": {
      "id": "cowin_hiu_01"
    },
    "careContexts": [
      {
        "patientReference": "batman@tmh",
        "careContextReference": "Episode1"
      }
    ],
    "requester": {
      "name": "<ABHA_ADDRESS>",
      "identifier": {
        "value": "REG1",
        "type": "MH1001",
        "system": "https://www.sample.com"
      }
    },
    "hiTypes": [
      "Prescription"
    ],
    "permission": {
      "accessMode": "VIEW",
      "dateRange": {
        "from": "2021-09-28T12:30:08.573Z",
        "to": "2021-09-28T12:30:08.573Z"
      },
      "dataEraseAt": "2021-09-28T12:30:08.573Z",
      "frequency": {
        "unit": "HOUR",
        "value": 1,
        "repeats": 0
      }
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `consent` (object, required)
- `consent.purpose` (object, required)
- `consent.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
- `consent.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
- `consent.purpose.refUri` (string, required): The reference URL. Should be a valid URL. Allow alpha numeric characters and special charactes like  "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `consent.patient` (object, required)
- `consent.patient.id` (string, required): The abha address of the patient. It must start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx. Allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.\-!]+[a-zA-Z0-9]@(abdm|sbx)$
- `consent.hip` (object): Identifier and name of the health information provider.
- `consent.hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `consent.hip.name` (string): The name of the health information provider. Allows alpha numeric and special characters like "^[a-zA-Z]+[A-Za-z0-9_\\-@,().\\s\\xa0:/]+"
- `consent.hip.type` (string): The type of the health information provider. Allows alpha numeric and special characters like  "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `consent.hiu` (object, required)
- `consent.hiu.id` (string, required): The service ID of the health information user.  Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `consent.hiu.name` (string): The name of the health information user. Allows alpha numeric and special characters like "^[a-zA-Z]+[A-Za-z0-9_\\-@,().\\s\\xa0:/]+"
- `consent.hiu.type` (string): The type of the health information user. Allows alpha numeric and special characters like  "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `consent.careContexts` (object[]): List of care contexts linked at the HIP end for the identified patient.
- `consent.careContexts.patientReference` (string, required): A patient identifier with which patient is registered in the facility/hospital like abhaAddress @sbx. Allows alpha numeric and special characters like "^[a-zA-Z0-9_\\-@,().\"/: ]{0,255}$"
- `consent.careContexts.careContextReference` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data). Allows alpha numeric and special characters like  "^[a-zA-Z0-9_\\-@,().\"/:| ]{0,255}$"
- `consent.requester` (object, required)
- `consent.requester.name` (string, required): The name of the requester
- `consent.requester.identifier` (object, required)
- `consent.requester.identifier.value` (string, required): The type of the identification. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `consent.requester.identifier.type` (string, required): The identification value. Allows alpha numeric character and special characters like  "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `consent.requester.identifier.system` (string, required): Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `consent.hiTypes` (string[], required): Types of health information document.
- `consent.permission` (object, required)
- `consent.permission.accessMode` (string, required) One of: VIEW, STORE, STREAM, QUERY.
- `consent.permission.dateRange` (object, required)
- `consent.permission.dateRange.from` (string, required): Should be UTC date time in ISO format. Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `consent.permission.dateRange.to` (string, required): Should be UTC date time in ISO format. Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `consent.permission.dataEraseAt` (string, required): The date at which the consent expire. Should be UTC.  Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$" date time in ISO format
- `consent.permission.frequency` (object, required)
- `consent.permission.frequency.unit` (string, required) One of: HOUR, DAY, WEEK, MONTH, YEAR.
- `consent.permission.frequency.value` (number, required): The frequency unit value. Should be be a integer
- `consent.permission.frequency.repeats` (number, required): Should be be a integer

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Get consent request status

`POST /api/hiecm/consent/v3/request/status`

Retrieve the status of a previously initiated consent request. By invoking this API, users can check the current state of their consent request, whether it is pending, approved, denied, or expired. This functionality is essential for maintaining transparency and keeping users informed about the progress of their consent requests. The API supports efficient tracking and management of consent, ensuring that health information exchange processes are conducted in a secure and compliant manner.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/request/status \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "consentRequestId": "5f7a535d-a3fd-416b-b069-c97d021fbacd"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `consentRequestId` (string, required): The consent request id from a consent. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Acknowledge the consent notification

`POST /api/hiecm/consent/v3/request/hiu/on-notify`

Consent notifications, specifically for cases when consent is APPROVED, DENIED, or REVOKED or EXPIRED. Notified by CM earlier via Gateway API - **/api/v3/hiu/consent/request/notify**

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/request/hiu/on-notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "acknowledgement": [
    {
      "status": "OK",
      "consentId": "e3c74829-3f82-4f94-959e-e10f57bcd57b"
    }
  ],
  "error": {
    "code": "ABDM-1001",
    "message": "unable to connect database"
  },
  "response": {
    "requestId": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `acknowledgement` (object[], required)
- `acknowledgement.status` (string, required): The status of the notification. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `acknowledgement.consentId` (string, required): The consent artefact id. Should be valid UUID. Allows alpha numeric character and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$"
- `error` (object): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message
- `response` (object, required): The request id is from the /hiu/consent/request/notify callback
- `response.requestId` (string, required): The requestId that was passed. it must be in Alpha numeric and - in middle and Allows alpha numeric character and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Fetch the consent details

`POST /api/hiecm/consent/v3/fetch`

Fetch the details of a consent using the consent artefact ID. By invoking this API, HIUs can retrieve comprehensive information about a specific consent, including its status, scope, and any associated conditions. This functionality is essential for ensuring that HIUs have access to accurate and up-to-date consent information, supporting secure and compliant health information exchange. The API facilitates efficient management and verification of consents, enhancing the overall integrity of the consent management process.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/fetch \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "consentId": "5f7a535d-a3fd-416b-b069-c97d021fbacd"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `consentId` (string, required): The id of the consent artefact that needs to be fetched. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Submit the health information data request from HIU

`POST /api/hiecm/data-flow/v3/health-information/request`

Facilitates the exchange of health data between Health Information Providers (HIP) and Health Information Users (HIU) within the ABDM system. It ensures secure and efficient data transfer, enabling seamless communication and interoperability between different healthcare entities.
1. **X-HIU-ID** if the requester is HIU (SERVICE-ID).

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/data-flow/v3/health-information/request \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "hiRequest": {
    "consent": {
      "id": "18235d89-cb13-479d-ad71-7a57d5f669a8"
    },
    "dateRange": {
      "from": "2022-10-06T15:10:00.587Z",
      "to": "2022-11-06T15:10:00.587Z"
    },
    "dataPushUrl": "https://live.ndhm.gov.in/api-hiu/data/notification",
    "keyMaterial": {
      "cryptoAlg": "ECDH",
      "curve": "curve25519",
      "dhPublicKey": {
        "expiry": "2022-12-28T13:18:20.742Z",
        "parameters": "Ephemeral public key",
        "keyValue": "BFN7KTdOT0jIAExG2A8Jg+01wMPWxptiGqwHRVvtiVEsUq2FR7P2UdqZxJyPJSeR6muai21iQhasNxnhh8I5M+g="
      },
      "nonce": "28236d89-cb13-479d-ad71-7a57d5f669a9"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `hiRequest` (object, required)
- `hiRequest.consent` (object, required)
- `hiRequest.consent.id` (string, required): The consent artefact id for health information request. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `hiRequest.dateRange` (object, required): Health information created between this date range is requested
- `hiRequest.dateRange.from` (string, required): Should be a UTC date time in ISO Format.Allows alpha numeric character and special characters like ^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$
- `hiRequest.dateRange.to` (string, required): Should be a UTC date time in ISO Format.Allows alpha numeric character and special characters like ^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$
- `hiRequest.dataPushUrl` (string, required): The URL to which the Health Information Provider has to send the health information data. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":=?/&]{0,255}$"
- `hiRequest.keyMaterial` (object, required): The requester's half of the ECDH key agreement. The HIP derives the shared key from it and its own key pair, and encrypts every entry it pushes with AES-GCM.
- `hiRequest.keyMaterial.cryptoAlg` (string, required): The key agreement algorithm. Always ECDH.
- `hiRequest.keyMaterial.curve` (string, required): The curve the key pair is generated on. Always Curve25519.
- `hiRequest.keyMaterial.dhPublicKey` (object, required): The public half of the ephemeral key pair generated for this transaction.
- `hiRequest.keyMaterial.dhPublicKey.expiry` (string, required): When this key stops being valid, as an ISO 8601 timestamp.
- `hiRequest.keyMaterial.dhPublicKey.parameters` (string, required): The key parameters. Ephemeral public key.
- `hiRequest.keyMaterial.dhPublicKey.keyValue` (string, required): The public key, Base64 encoded, in X.509 SubjectPublicKeyInfo form.
- `hiRequest.keyMaterial.nonce` (string): 32 random bytes, Base64 encoded, generated for this transaction. The other side combines it with its own nonce to derive the AES-GCM key and initialisation vector.

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1015 - Invalid Response. May be returned either bare (`ABDM-1015`) or with a trailing ": " separator (`ABDM-1015: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string, required): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)
  - `description` (string, required)
- `403`: Access Denied
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Submit the notifications corresponding to events during data flow

`POST /api/hiecm/data-flow/v3/health-information/notify`

HIU and HIP during data transfer. HIP on the transfer of data would send sessionStatus - one of [TRANSFERRED, FAILED] HIP would also send hiStatus for each careContextReference - on of [DELIVERED, ERRORED] HIU on receipt of data would send sessionStatus - one of [RECEIVED, FAILED]. For example, FAILED when data was not sent or if invalid data was sent HIU would also send hiStatus for each careContextReference - one of [OK, ERRORED]

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/data-flow/v3/health-information/notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "notification": {
    "consentId": "18235d89-cb13-479d-ad71-7a57d5f669a8",
    "transactionId": "18235d89-cb13-479d-ad71-7a57d5f669a8",
    "doneAt": "2023-01-24T06:35:44.167Z",
    "notifier": {
      "type": "HIU",
      "id": "100005"
    },
    "statusNotification": {
      "sessionStatus": "RECEIVED",
      "hipId": "IN2810014366",
      "statusResponses": [
        {
          "careContextReference": "10004-20200001768-1",
          "hiStatus": "OK",
          "description": "Data received successfully"
        }
      ]
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `notification` (object, required)
- `notification.consentId` (string, required): The consent artefact id with which health information was requested.Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `notification.transactionId` (string, required): The UUID generated when the health information request was initiated.Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `notification.doneAt` (string, required): The date at which the transaction was initiated. Should be a UTC date time in ISO format. Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `notification.notifier` (object, required)
- `notification.notifier.type` (string, required): The Service ID.Allows alpha numeric characters and special characters like  "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$" One of: HIU, HIP.
- `notification.notifier.id` (string, required): The service ID of the notifier. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `notification.statusNotification` (object, required)
- `notification.statusNotification.sessionStatus` (string, required): The status of the health information request that was initiated. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `notification.statusNotification.hipId` (string, required): The service ID of the health information provider. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `notification.statusNotification.statusResponses` (object[], required)
- `notification.statusNotification.statusResponses.careContextReference` (string, required): The care context reference number.Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `notification.statusNotification.statusResponses.hiStatus` (string, required): The status of the health information transfer. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `notification.statusNotification.statusResponses.description` (string, required): The brief description of the status. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): ABDM-1031 - Invalid request. May be returned either bare (`ABDM-1031`) or with a trailing ": " separator (`ABDM-1031: `); match on the code itself and tolerate the separator.
  - `message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string, required): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)
  - `description` (string, required)
- `403`: Access Denied
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Get the current status of the health information request

`GET /api/hiecm/data-flow/v3/health-information/request/status/{transaction-id}`

Allow Health Information Users (HIU) and Health Information Providers (HIP) to retrieve the current status of a specific Health Information Request. By providing the unique transaction ID, users can query the system to obtain real-time updates on the processing state of their request. This functionality is crucial for ensuring transparency and efficient communication between stakeholders in the health information exchange ecosystem. The API supports various status checks, including pending, in-progress, completed, and failed states.

```bash
curl --request GET \
  --url https://dev.abdm.gov.in/api/hiecm/data-flow/v3/health-information/request/status/{transaction-id} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Path parameters

- `transaction-id` (string, required): The health information request transaction id

## Responses

- `200`: OK
  - `transactionId` (string, required)
  - `status` (string, required)
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string, required): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)
  - `description` (string, required)
- `403`: Access Denied
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "transactionId": "18235d89-cb13-479d-ad71-7a57d5f669a8",
  "status": "TRANSFERRED"
}
```


---

# M3 Health Information User errors

Seeing a symptom rather than a code? Start at [Troubleshooting](/docs/hiecm/v3/troubleshooting/).

The M3 Health Information User specification records no error code yet. That is a gap in the specification, not a promise that this module cannot fail.

Every code above is recorded in the specification that owns it. The aggregated list across modules is at [error codes](/docs/hiecm/v3/reference/error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# M3 Health Information User: Fetch data with consent

Request patient consent, track its status, and fetch the health records a granted consent artefact covers.

The full operation list is in the [M3 API reference](/reference/hiecm-m3).

New to this? Start with [M3 Health Information User](/docs/hiecm/v3/milestones/m3).


---

# Login via password

`POST /api/v1/auth/authPassword`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/api/v1/auth/authPassword \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "idType": "",
  "domainName": "",
  "hprId": "<HPR_ID>",
  "password": "XXXX@992"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `idType` (string)
- `domainName` (string)
- `hprId` (string)
- `password` (string)

## Responses

- `200`: OK
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "token": "<JWT TOKEN>",
  "expiresIn": 1733639805,
  "refreshToken": null,
  "refreshExpiresIn": 0
}
```


---

# Get public certificate

`GET /api/v1/auth/cert`

```bash
curl --request GET \
  --url "https://apihspsbx.abdm.gov.in/v4/int/api/v1/auth/cert?publicCertificateRequestDto=<PUBLICCERTIFICATEREQUESTDTO>" \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Query parameters

- `publicCertificateRequestDto` (object, required)

## Responses

- `200`: OK
- `404`: Not Found


---

# Verify Aadhaar OTP 1

`POST /api/v1/auth/confirmWithAadhaarOtp`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/api/v1/auth/confirmWithAadhaarOtp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "otp": "308709",
  "txnId": "de4ff682-fcc6-4bcf-a978-0dbb19a288b4"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `otp` (string)
- `txnId` (string)

## Responses

- `200`: OK
- `404`: Not Found


---

# Send via Aadhaar OTP

`POST /api/v1/auth/init`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/api/v1/auth/init \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "idType": "",
  "domainName": "",
  "authMethod": "AADHAAR_OTP",
  "hprId": "<HPR_ID>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `idType` (string)
- `domainName` (string)
- `authMethod` (string)
- `hprId` (string)

## Responses

- `200`: OK
  - `transactionId` (string)
  - `mobileNumber` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "transactionId": "227654a1-a627-48e3-a617-f6fa7595a512",
  "mobileNumber": "******1234"
}
```


---

# Send verify OTP

`POST /api/v2/auth/loginViaMobileSendOTP`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/api/v2/auth/loginViaMobileSendOTP \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "4c8c4b29-6d7e-4446-8f73-4574d6d14f09",
  "mobile": "97624XXXXX"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `mobile` (string)
- `txnId` (string)
- `otp` (string)
- `hpid` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `mobileLinkedHpIdDTO` (object[])
  - `mobileNumber` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "txnId": "28b4ce41-71df-48af-8b6c-13c30402816c",
  "mobileNumber": "******1234"
}
```


---

# Register professional

`POST /apis/v1/doctors/register-professional-new`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/doctors/register-professional-new \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hprToken": "<JWT TOKEN>",
  "practitioner": {
    "healthProfessionalType": "doctor",
    "profilePhoto": "<BASE64 ENCODED STRING>",
    "officialMobileCode": "",
    "officialMobile": "97624xxxxx",
    "officialMobileStatus": "",
    "officialEmail": "",
    "officialEmailStatus": "",
    "visibleProfilePicture": "0",
    "profileVisibleToPublic": "1",
    "personalInformation": {
      "salutation": "1",
      "firstName": "Ayushman",
      "middleName": "",
      "lastName": "Mission",
      "nationality": "356",
      "fatherName": "",
      "motherName": "",
      "spouseName": "",
      "gender": "M",
      "dateOfBirth": "<DOB>",
      "placeOfBirthState": "68",
      "district": "",
      "subDistrict": "",
      "city": "",
      "languagesSpoken": "1,2",
      "category": "C"
    },
    "addressAsPerKYC": "",
    "communicationAddress": {
      "isCommunicationAddressAsPerKYC": "false",
      "address": "",
      "name": "",
      "country": "",
      "state": "",
      "district": "",
      "subDistrict": "",
      "city": "",
      "pincode": ""
    },
    "contactInformation": {
      "publicMobileNumber": "",
      "publicMobileNumberCode": "",
      "publicMobileNumberStatus": "",
      "landLineNumber": "",
      "landLineNumberCode": "",
      "publicEmail": "",
      "publicEmailStatus": ""
    },
    "registrationAcademic": {
      "category": "1",
      "registrationData": [
        {
          "registeredWithCouncil": "47",
          "registrationNumber": "REG12032",
          "registrationDate": "2024-12-01",
          "registrationCertificate": {
            "fileType": "pdf",
            "data": "<BASE64 ENCODED STRING>"
          },
          "isPermanentOrRenewable": "Permanent",
          "renewableDueDate": "",
          "categoryId": "2",
          "isNameDifferentInCertificate": "false",
          "proofOfNameChangeCertificate": "",
          "qualifications": [
            {
              "nameOfDegreeOrDiplomaObtained": "4074",
              "country": "356",
              "state": "27",
              "college": "1022",
              "university": "6372",
              "yearOfAwardingDegreeDiploma": "2024",
              "monthOfAwardingDegreeDiploma": "February",
              "degreeCertificate": {
                "fileType": "pdf",
                "data": "<BASE64 ENCODED STRING>"
              },
              "isNameDifferentInCertificate": "false",
              "proofOfNameChangeCertificate": ""
            },
            {
              "nameOfDegreeOrDiplomaObtained": "Graduation",
              "country": "United States Of America",
              "state": "united",
              "college": "united School",
              "university": "united University",
              "yearOfAwardingDegreeDiploma": "2024",
              "monthOfAwardingDegreeDiploma": "February",
              "degreeCertificate": {
                "fileType": "pdf",
                "data": "<BASE64 ENCODED STRING>"
              },
              "isNameDifferentInCertificate": "true",
              "proofOfNameChangeCertificate": "<BASE64 ENCODED STRING>"
            }
          ]
        }
      ]
    },
    "currentWorkDetails": {
      "currentlyWorking": "0",
      "purposeOfWork": "Administrative",
      "chooseWorkStatus": "1",
      "reasonForNotWorking": "Retired",
      "certificateAttachment": "<BASE64 ENCODED STRING>",
      "facilityDeclarationData": {
        "facilityId": "IN2710000059",
        "facilityName": "",
        "facilityAddress": "",
        "facilityPincode": "",
        "state": "",
        "district": "",
        "facilityType": "",
        "facilityDepartment": "Surgery",
        "facilityDesignation": "MD",
        "ministry": {
          "ministry": "MinistryMOR ( Mo Railways )"
        }
      }
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `practitioner` (object)
- `practitioner.personalInformation` (object)
- `practitioner.communicationAddress` (object)
- `practitioner.contactInformation` (object)
- `practitioner.registrationAcademic` (object)
- `practitioner.specialities` (object[])
- `practitioner.currentWorkDetails` (object)
- `practitioner.apiClientId` (string)
- `practitioner.profilePhoto` (string)
- `practitioner.healthProfessionalType` (string)
- `practitioner.officialMobileCode` (string)
- `practitioner.officialMobile` (string)
- `practitioner.officialMobileStatus` (string)
- `practitioner.officialEmail` (string)
- `practitioner.officialEmailStatus` (string)
- `practitioner.visibleProfilePicture` (string)
- `practitioner.profileVisibleToPublic` (string)
- `practitioner.addressAsPerKYC` (string)
- `hprToken` (string)

## Responses

- `200`: OK
  - `referenceNumber` (string)
  - `status` (string)
  - `message` (string)
  - `error` (object)
  - `hprId` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "referenceNumber": "9a2d25fc-6897-4645-8e78-7f12a91b4ab4",
  "status": "true",
  "message": "Congratulations! Your profile has been submitted successfully for verification.",
  "error": null,
  "hprId": "<HPR_ID>"
}
```


---

# Update professional

`POST /apis/v1/doctors/update-professional-new`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/doctors/update-professional-new \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hprToken": "<JWT TOKEN>",
  "practitioner": {
    "healthProfessionalType": "doctor",
    "profilePhoto": "<BASE64 ENCODED STRING>",
    "officialMobileCode": "",
    "officialMobile": "97624xxxxx",
    "officialMobileStatus": "",
    "officialEmail": "",
    "officialEmailStatus": "",
    "visibleProfilePicture": "0",
    "profileVisibleToPublic": "1",
    "personalInformation": {
      "salutation": "1",
      "firstName": "Ayushman",
      "middleName": "",
      "lastName": "Mission",
      "nationality": "356",
      "fatherName": "",
      "motherName": "",
      "spouseName": "",
      "gender": "M",
      "dateOfBirth": "<DOB>",
      "placeOfBirthState": "68",
      "district": "",
      "subDistrict": "",
      "city": "",
      "languagesSpoken": "1,2",
      "category": "C"
    },
    "addressAsPerKYC": "",
    "communicationAddress": {
      "isCommunicationAddressAsPerKYC": "false",
      "address": "",
      "name": "",
      "country": "",
      "state": "",
      "district": "",
      "subDistrict": "",
      "city": "",
      "pincode": ""
    },
    "contactInformation": {
      "publicMobileNumber": "",
      "publicMobileNumberCode": "",
      "publicMobileNumberStatus": "",
      "landLineNumber": "",
      "landLineNumberCode": "",
      "publicEmail": "",
      "publicEmailStatus": ""
    },
    "registrationAcademic": {
      "category": "1",
      "registrationData": [
        {
          "registeredWithCouncil": "47",
          "registrationNumber": "REG12032",
          "registrationDate": "2024-12-01",
          "registrationCertificate": {
            "fileType": "pdf",
            "data": "<BASE64 ENCODED STRING>"
          },
          "isPermanentOrRenewable": "Permanent",
          "renewableDueDate": "",
          "categoryId": "2",
          "isNameDifferentInCertificate": "false",
          "proofOfNameChangeCertificate": "",
          "qualifications": [
            {
              "nameOfDegreeOrDiplomaObtained": "4074",
              "country": "356",
              "state": "27",
              "college": "1022",
              "university": "6372",
              "yearOfAwardingDegreeDiploma": "2024",
              "monthOfAwardingDegreeDiploma": "February",
              "degreeCertificate": {
                "fileType": "pdf",
                "data": "<BASE64 ENCODED STRING>"
              },
              "isNameDifferentInCertificate": "false",
              "proofOfNameChangeCertificate": ""
            },
            {
              "nameOfDegreeOrDiplomaObtained": "Graduation",
              "country": "United States Of America",
              "state": "united",
              "college": "united School",
              "university": "united University",
              "yearOfAwardingDegreeDiploma": "2024",
              "monthOfAwardingDegreeDiploma": "February",
              "degreeCertificate": {
                "fileType": "pdf",
                "data": "<BASE64 ENCODED STRING>"
              },
              "isNameDifferentInCertificate": "true",
              "proofOfNameChangeCertificate": "<BASE64 ENCODED STRING>"
            }
          ]
        }
      ]
    },
    "currentWorkDetails": {
      "currentlyWorking": "0",
      "purposeOfWork": "Administrative",
      "chooseWorkStatus": "1",
      "reasonForNotWorking": "Retired",
      "certificateAttachment": "<BASE64 ENCODED STRING>",
      "facilityDeclarationData": {
        "facilityId": "IN2710000059",
        "facilityName": "",
        "facilityAddress": "",
        "facilityPincode": "",
        "state": "",
        "district": "",
        "facilityType": "",
        "facilityDepartment": "Surgery",
        "facilityDesignation": "MD",
        "ministry": {
          "ministry": "MinistryMOR ( Mo Railways )"
        }
      }
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `practitioner` (object)
- `practitioner.personalInformation` (object)
- `practitioner.communicationAddress` (object)
- `practitioner.contactInformation` (object)
- `practitioner.registrationAcademic` (object)
- `practitioner.specialities` (object[])
- `practitioner.currentWorkDetails` (object)
- `practitioner.apiClientId` (string)
- `practitioner.profilePhoto` (string)
- `practitioner.healthProfessionalType` (string)
- `practitioner.officialMobileCode` (string)
- `practitioner.officialMobile` (string)
- `practitioner.officialMobileStatus` (string)
- `practitioner.officialEmail` (string)
- `practitioner.officialEmailStatus` (string)
- `practitioner.visibleProfilePicture` (string)
- `practitioner.profileVisibleToPublic` (string)
- `practitioner.addressAsPerKYC` (string)
- `hprToken` (string)

## Responses

- `200`: OK
  - `referenceNumber` (string)
  - `status` (string)
  - `message` (string)
  - `error` (object)
  - `hprId` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "referenceNumber": "5b17ca73-f069-4018-91a0-665df0117d43",
  "status": "true",
  "message": "Congratulations! Your profile has been submitted successfully for verification.",
  "error": null,
  "hprId": "<HPR_ID>"
}
```


---

# Fetch documents

`POST /apis/v1/doctors/fetch-documents-list`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/doctors/fetch-documents-list \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hprid": "<HPR_ID>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `hprid` (string)

## Responses

- `200`: OK
  - `documentList` (object)
  - `documentList.profileDetails` (object)
  - `documentList.registrationDetails` (object[])
  - `documentList.qualificationDetails` (object[])
  - `documentList.qualification` (object[])
  - `documentList.internationalDoctorQualificationDetails` (object[])
  - `message` (string)
  - `Message` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "documentList": {
    "profileDetails": {
      "profilePhoto": {
        "id": 30106,
        "data": "<BASE64_PHOTO>"
      },
      "proofOfWorkCertificate": {
        "id": 30106,
        "data": "JVBERi0xLjMK"
      }
    },
    "registrationDetails": [
      {
        "registrationCertificate": {
          "id": 21021,
          "systemOfMedicide": "modern_medicine",
          "data": "JVBERi0xLjMK"
        },
        "proofOfNameChangeRegCertificate": {
          "id": 21021,
          "systemOfMedicide": "modern_medicine",
          "data": "JVBERi0xLjMK"
        }
      }
    ],
    "qualificationDetails": [
      {
        "degreeCertificate": {
          "id": 9693,
          "courseName": "PhD Biostatistics",
          "qualificationYear": "2021",
          "data": "JVBERi0xLjMK"
        },
        "proofOfNameChangeQualCertificate": {
          "id": 9693,
          "courseName": "PhD Biostatistics",
          "qualificationYear": "2021",
          "data": "JVBERi0xLjMK"
        }
      }
    ],
    "qualification": null
  },
  "Message": "Data fetched successfully"
}
```


---

# Upload documents

`POST /apis/v1/uploads/upload-document`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/uploads/upload-document \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hpr_token": "<JWT TOKEN>",
  "document": [
    {
      "document_id": 20931,
      "document_type": "registrationCertificate",
      "fileType": "",
      "data": "JVBERi0xLjMK"
    }
  ]
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `hpr_token` (string)
- `document` (object[])
- `document.document_id` (integer)
- `document.document_type` (string)
- `document.fileType` (string)
- `document.data` (string)

## Responses

- `200`: OK
  - `profilePhoto` (object)
  - `degreeCertificate` (object)
  - `registrationCertificate` (object)
  - `registrationCertificate.status` (string)
  - `registrationCertificate.msg` (string)
  - `proofOfWorkCertificate` (object)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "profilePhoto": null,
  "degreeCertificate": null,
  "registrationCertificate": {
    "status": "pass",
    "msg": "Registration certificate updated"
  },
  "proofOfWorkCertificate": null
}
```


---

# Get professional info

`POST /apis/v1/doctors/fetch-professional-info`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/doctors/fetch-professional-info \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "practitioner": {
    "id": "<HPR_ID>",
    "name": "",
    "contactNumber": "976243XXXX",
    "state": "UTTAR PRADESH",
    "registrationNumber": ""
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `practitioner` (object)
- `practitioner.id` (string)
- `practitioner.name` (string)
- `practitioner.contactNumber` (string)
- `practitioner.state` (string)
- `practitioner.registrationNumber` (string)
- `practitioner.stateCouncilName` (string)

## Responses

- `200`: OK
  - `message` (string)
  - `practitioners` (array[])
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "practitioners": [
    [
      {
        "identifier": 38053,
        "active": false,
        "name": "Ayushman Bharat Mission",
        "gender": "Male",
        "salutation": "Mr",
        "communicationLanguage": " English ",
        "registrations": [
          {
            "identifier": 25989,
            "category": "Dentistry",
            "nuidnumber": null,
            "nuidvalidtill": null,
            "systemOfMedicide": null,
            "isRenewable": "false",
            "dueDate": null,
            "councilName": "Karnataka State Dental Council",
            "registeredAt": null,
            "registrationNumber": "REG12032",
            "registrationDate": "2024-12-01"
          }
        ],
        "qualifications": [
          {
            "identifier": 12835,
            "courseName": "Bds - Bachelor Of Dental Surgery",
            "collegeName": "A.j. Institute Of Dental Sciences, Mangalore",
            "universityName": "Rajiv Gandhi University Of Health Sciences (rguhs)",
            "qualificationYear": "2024",
            "qualificationMonth": ""
          }
        ],
        "hpr_id": "<HPR_ID>",
        "application_status": null,
        "is_council_verified": "true",
        "is_work_verified": null,
        "email": "",
        "mobileNumber": "******2125",
        "hpr_category": "doctor"
      }
    ]
  ],
  "message": "Data fetched successfully"
}
```


---

# Submit the retrieval health ID by Aadhaar

`POST /v1/forgot/hprId/aadhaar`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/forgot/hprId/aadhaar \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "otp": "<BASE64 ENCODED STRING>",
  "txnId": "4c115e27-a602-4320-b4cd-ee658539e2f0"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `txnId` (string)

## Responses

- `200`: OK
  - `hprId` (string)
  - `hprIdNumber` (string)
  - `token` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "hprId": "<EMAIL>",
  "hprIdNumber": "71-1********-0212",
  "token": "<JWT TOKEN>"
}
```


---

# Submit the retrieval health ID by mobile

`POST /v1/forgot/hprId/mobile`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/forgot/hprId/mobile \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "5f7a4a1e-59ba-4c0c-9e0c-8e6b3b6e2f11",
  "name": "<NAME>",
  "gender": "<GENDER>",
  "yearOfBirth": "<YEAR_OF_BIRTH>",
  "monthOfBirth": "<MONTH_OF_BIRTH>",
  "dayOfBirth": "<DAY_OF_BIRTH>",
  "firstName": "<FIRST_NAME>",
  "lastName": "<LAST_NAME>",
  "middleName": "<MIDDLE_NAME>",
  "otp": "<OTP>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `txnId` (string, required)
- `name` (string, required)
- `gender` (string, required)
- `yearOfBirth` (string, required)
- `monthOfBirth` (string)
- `dayOfBirth` (string)
- `firstName` (string, required)
- `lastName` (string)
- `middleName` (string)
- `otp` (string, required)

## Responses

- `200`: OK
- `404`: Not Found


---

# Generate mobile OTP

`POST /v1/forgot/hprId/mobile/generateOtp`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/forgot/hprId/mobile/generateOtp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "mobileNumber": "VPoaDCJBNyGhJiX+sAh9yRq1WXAfRXkgcE31/0U2DMkH/+nvpspAA4GEmkbideZhKsSLYnFA1lHPkBH7PS6Bg4jz0aSdDAoovnYgVftJ/suP4mzhhg1Hrf7zQFPriHiraNlsIzsDeLl3ckGejNiCmXhfhBBw==xxxxxxxxxxxxx"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `mobileNumber` (string)
- `email` (string)
- `type` (string)
- `hpid` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `msg` (string)
  - `mobileNumber` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "txnId": "132dd7dd-ca5a-4ec1-a36c-093c007bf794",
  "msg": "Please enter OTP sent on your mobile number ******2021",
  "mobileNumber": "******2021"
}
```


---

# Send OTP to contact

`POST /v1.5/facility/sendOtpToContact`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1.5/facility/sendOtpToContact \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "facilityId": "IN2810002702"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `facilityId` (string)

## Responses

- `200`: OK
  - `facilityId` (string)
  - `status` (string)
  - `message` (string)
  - `transactionId` (string)
  - `errorStatus` (object[])
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "facilityId": "IN0610089709",
  "status": "Success",
  "message": "Otp sent successfully! Please keep transaction id for future reference",
  "transactionId": "3cf3de44-94a4-4f77-b7f9-de6ec86785b3",
  "errorStatus": null
}
```


---

# Validate OTP

`POST /v1.5/facility/validateOtp`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1.5/facility/validateOtp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "facilityId": "IN2810002702",
  "sourceId": "AB-PMJAY",
  "otp": "885210",
  "source": "AB-PMJAY",
  "transactionId": "2ddfc7ec-9a9f-412c-8c50-c2be92da5781"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `facilityId` (string)
- `sourceId` (string)
- `otp` (string)
- `source` (string)
- `transactionId` (string)

## Responses

- `200`: OK
  - `facilityId` (string)
  - `status` (string)
  - `message` (string)
  - `errorStatus` (object[])
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "facilityId": "IN2810002702",
  "status": "success",
  "message": "OTP validated successfully!!! Hospital id linked to HFR",
  "errorStatus": null
}
```


---

# Get admin token

`POST /getManagementToken`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/getManagementToken \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "username": "<USERNAME>",
  "password": "<PASSWORD>",
  "resend": false
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `username` (string)
- `password` (string)
- `resend` (boolean)

## Responses

- `200`: OK
- `404`: Not Found


---

# Submit the healdthloginwithmobile

`POST /healdthloginwithmobile`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/healdthloginwithmobile \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "<TXN_ID>",
  "issueToken": "<ISSUE_TOKEN>",
  "token": "<TOKEN>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `txnId` (string)
- `issueToken` (string)
- `token` (string)

## Responses

- `200`: OK
- `404`: Not Found


---

# Update role and category

`POST /profile/updateRole`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/profile/updateRole \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "firstName": "Ayushman",
  "lastName": "Mission",
  "middleName": "Bharat",
  "hprId": "<EMAIL>",
  "password": "Abdm@143",
  "email": "<ABHA_ADDRESS>.com",
  "profilePhoto": "<BASE64 ENCODED STRING>",
  "stateCode": "7",
  "districtCode": "71",
  "subdistrictCode": "1",
  "villageCode": "<VILLAGE_CODE>",
  "townCode": "<TOWN_CODE>",
  "wardCode": "<WARD_CODE>",
  "pincode": 110001,
  "address": "9th Floor, Tower-l, Jeevan Bharati Building, Connaught Place, New Delhi - 110001",
  "yearOfBirth": "2021",
  "monthOfBirth": "8",
  "dayOfBirth": "15",
  "hpCategoryCode": "1",
  "hpSubCategoryCode": "1",
  "txnId": "5f7a4a1e-59ba-4c0c-9e0c-8e6b3b6e2f11",
  "role": "<ROLE>",
  "consentToDelete": false
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `firstName` (string): First Name of the user).
- `lastName` (string): Last name of the user
- `middleName` (string): Middle name of the user
- `hprId` (string): Healthcare Professional ID Alias.
- `password` (string): User Authentication password.
- `email` (string): Email Address of the user.
- `profilePhoto` (string): Profile photo of the user (Uploaded by the user).
- `stateCode` (string): State Code of the user (LGD).
- `districtCode` (string): District Code of the user (LGD).
- `subdistrictCode` (string): Sub District Code of the user (LGD).
- `villageCode` (string): Village Code of the user (LGD).
- `townCode` (string): Town Code of the user (LGD).
- `wardCode` (string): Ward Code of the user (LGD).
- `pincode` (integer): Pincode of the user.
- `address` (string): Address of the user.
- `yearOfBirth` (string): Year of birth of the user.
- `monthOfBirth` (string): Month of birth of the user.
- `dayOfBirth` (string): Day of birth of the user.
- `hpCategoryCode` (string)
- `hpSubCategoryCode` (string)
- `txnId` (string)
- `role` (string)
- `consentToDelete` (boolean)

## Responses

- `200`: OK
- `404`: Not Found


---

# Fetch professional facility

`POST /fetchProfessionalFacility`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/fetchProfessionalFacility \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "facilityId": "<FACILITY_ID>",
  "page": 0,
  "size": 0
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `facilityId` (string)
- `page` (integer)
- `size` (integer)

## Responses

- `200`: OK
- `404`: Not Found


---

# Create facility suggestion

`POST /hprFacilitySuggestions`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/hprFacilitySuggestions \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<NAME>",
  "address": "<ADDRESS>",
  "state": {
    "id": 0,
    "name": "<NAME>",
    "isoCode": "<ISO_CODE>",
    "status": false,
    "countryId": 0,
    "visibleStatus": false,
    "position": false,
    "councilLabel": "<COUNCIL_LABEL>",
    "systemOfMedicine": false
  },
  "district": {
    "id": 0,
    "stateId": 0,
    "districtName": "<DISTRICT_NAME>",
    "isoCode": "<ISO_CODE>",
    "status": false
  },
  "pincode": 0,
  "contactNo": 0,
  "email": "<EMAIL>",
  "contactName": "<CONTACT_NAME>",
  "status": "pending",
  "createdBy": 0,
  "updatedBy": 0,
  "facilityId": 0,
  "hprProfileId": 0,
  "facilityName": "<FACILITY_NAME>",
  "facilityOwnership": {
    "label": "<LABEL>",
    "value": "<VALUE>"
  },
  "systemMedicine": [
    {
      "id": "<ID>",
      "lastUpdateDate": "<LAST_UPDATE_DATE>",
      "dropOrder": 0,
      "creationDate": "<CREATION_DATE>",
      "activeYN": "<ACTIVE_YN>",
      "createdBy": "<CREATED_BY>",
      "lastUpdatedUser": "<LAST_UPDATED_USER>",
      "nhrrMedicineCode": "<NHRR_MEDICINE_CODE>",
      "value": "<VALUE>",
      "type": "<TYPE>"
    }
  ],
  "facilityType": {
    "id": "<ID>",
    "facilityType": "<FACILITY_TYPE>",
    "facilityTypeNdhm": "<FACILITY_TYPE_NDHM>",
    "opd": "<OPD>",
    "ipd": "<IPD>",
    "dayCare": "<DAY_CARE>",
    "other": "<OTHER>",
    "activeYN": "<ACTIVE_YN>",
    "createdBy": "<CREATED_BY>",
    "createdDate": "<CREATED_DATE>",
    "lastUpdatedUser": "<LAST_UPDATED_USER>",
    "lastUpdatedDate": "<LAST_UPDATED_DATE>",
    "linkToForm": "<LINK_TO_FORM>",
    "facilityCode": "<FACILITY_CODE>",
    "facilityCodeUfid": "<FACILITY_CODE_UFID>",
    "facilityOrder": 0
  },
  "department": "<DEPARTMENT>",
  "designation": "<DESIGNATION>",
  "ministry": {
    "ministry": "<MINISTRY>"
  },
  "psuName": "<PSU_NAME>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `name` (string)
- `address` (string)
- `state` (object)
- `state.id` (integer)
- `state.name` (string)
- `state.isoCode` (string)
- `state.status` (boolean)
- `state.countryId` (integer)
- `state.visibleStatus` (boolean)
- `state.position` (boolean)
- `state.councilLabel` (string)
- `state.systemOfMedicine` (boolean)
- `district` (object)
- `district.id` (integer)
- `district.stateId` (integer)
- `district.districtName` (string)
- `district.isoCode` (string)
- `district.status` (boolean)
- `pincode` (integer)
- `contactNo` (integer)
- `email` (string)
- `contactName` (string)
- `status` (string) One of: pending, approved, rejected.
- `createdBy` (integer)
- `updatedBy` (integer)
- `facilityId` (integer)
- `hprProfileId` (integer)
- `facilityName` (string)
- `facilityOwnership` (object)
- `facilityOwnership.label` (string)
- `facilityOwnership.value` (string)
- `systemMedicine` (object[])
- `systemMedicine.id` (string)
- `systemMedicine.lastUpdateDate` (string)
- `systemMedicine.dropOrder` (integer)
- `systemMedicine.creationDate` (string)
- `systemMedicine.activeYN` (string)
- `systemMedicine.createdBy` (string)
- `systemMedicine.lastUpdatedUser` (string)
- `systemMedicine.nhrrMedicineCode` (string)
- `systemMedicine.value` (string)
- `systemMedicine.type` (string)
- `facilityType` (object)
- `facilityType.id` (object)
- `facilityType.facilityType` (string)
- `facilityType.facilityTypeNdhm` (string)
- `facilityType.opd` (string)
- `facilityType.ipd` (string)
- `facilityType.dayCare` (string)
- `facilityType.other` (string)
- `facilityType.activeYN` (string)
- `facilityType.createdBy` (string)
- `facilityType.createdDate` (string)
- `facilityType.lastUpdatedUser` (string)
- `facilityType.lastUpdatedDate` (string)
- `facilityType.linkToForm` (string)
- `facilityType.facilityCode` (string)
- `facilityType.facilityCodeUfid` (string)
- `facilityType.facilityOrder` (integer)
- `department` (string)
- `designation` (string)
- `ministry` (object)
- `ministry.ministry` (string)
- `psuName` (string)

## Responses

- `200`: OK
- `404`: Not Found


---

# Submit the facility add and update

`POST /v1/bridges/MutipleHRPAddUpdateServices`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/bridges/MutipleHRPAddUpdateServices \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "facilityId": "IN0610090166",
  "facilityName": "Singla Eye Center",
  "HRP": [
    {
      "bridgeId": "SBX_00XXXX",
      "hipName": "Singla Eye Center",
      "type": "HIP",
      "active": true
    }
  ]
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `facilityId` (string, required)
- `facilityName` (string, required)
- `HRP` (object[])
- `HRP.bridgeId` (string, required)
- `HRP.hipName` (string, required)
- `HRP.type` (string, required)
- `HRP.active` (boolean, required)

## Responses

- `200`: OK
- `404`: Not Found


---

# Get filtered address post

`POST /search/address/filter/deduplicate`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/search/address/filter/deduplicate \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Jethana",
  "address": "<ADDRESS>",
  "district": "511",
  "subDistrict": "5271",
  "village": "",
  "geolocation": "",
  "facilityId": "69765"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `name` (string)
- `address` (string)
- `district` (string)
- `subDistrict` (string)
- `village` (string)
- `geolocation` (string)
- `facilityId` (string)

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
"array"
```


---

# Submit the v15Basic facility information

`POST /v1.5/facility/basic-information`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1.5/facility/basic-information \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'x-hprid-auth: <X_HPRID_AUTH>' \
  --header 'Content-Type: application/json' \
  --data '{
  "trackingId": "",
  "facilityInformation": {
    "facilityName": "Sahyadri Hospital",
    "facilityAddressDetails": {
      "country": "India",
      "stateLGDCode": "24",
      "districtLGDCode": "438",
      "subDistrictLGDCode": "6512",
      "facilityRegion": "U",
      "villageCityTownLGDCode": "",
      "addressLine1": "townhall, Pune",
      "addressLine2": "Pune",
      "pincode": "<PINCODE>",
      "latitude": "23.068570",
      "longitude": "23.068570"
    },
    "facilityContactInformation": {
      "facilityEmailId": "<ABHA_ADDRESS>.com",
      "facilityContactNumber": "976243xxxx",
      "websiteLink": "nha.abdm.gov.in",
      "facilityLandlineNumber": "",
      "facilityStdCode": ""
    },
    "ownershipCode": "G",
    "ownershipSubTypeCode": "C",
    "ownershipSubTypeCode2": "MOHF",
    "systemOfMedicineCode": "M,D,UN",
    "typeOfServiceCode": "IPD,OPD",
    "facilityTypeCode": "5",
    "specialityTypeCode": "SINGLE",
    "facilityUploads": {
      "facilityBoardPhoto": {
        "name": "",
        "value": ""
      },
      "facilityBuildingPhoto": {
        "name": "",
        "value": ""
      }
    },
    "facilitySubType": "47",
    "facilityOperationalStatus": "F",
    "timingsOfFacility": [
      {
        "workingDays": "MON",
        "openingHours": "9:00 AM - 6:00 PM"
      },
      {
        "workingDays": "TUE",
        "openingHours": "9:00 AM - 4:00 PM"
      },
      {
        "workingDays": "WED",
        "openingHours": "9:00 AM - 6:00 PM"
      }
    ],
    "abdmCompliantSoftware": [
      {
        "existingSoftwares": [
          ""
        ],
        "anyOther": ""
      }
    ]
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Headers

- `x-hprid-auth` (string, required): The HPR token of the signed-in professional, from the HPR login.

## Body

- `facilityInformation` (object)
- `facilityInformation.facilityName` (string)
- `facilityInformation.facilityAddressDetails` (object)
- `facilityInformation.facilityContactInformation` (object)
- `facilityInformation.ownershipCode` (string)
- `facilityInformation.ownershipSubTypeCode` (string)
- `facilityInformation.ownershipSubTypeCode2` (string)
- `facilityInformation.typeOfServiceCode` (string)
- `facilityInformation.systemOfMedicineCode` (string)
- `facilityInformation.facilityTypeCode` (string)
- `facilityInformation.specialityTypeCode` (string)
- `facilityInformation.facilityUploads` (object)
- `facilityInformation.facilityAddressProof` (object[])
- `facilityInformation.facilitySubType` (string)
- `facilityInformation.workingInPsu` (boolean)
- `facilityInformation.facPsuName` (string)
- `facilityInformation.facilityOperationalStatus` (string)
- `facilityInformation.timingsOfFacility` (object[])
- `facilityInformation.abdmCompliantSoftware` (object[])
- `trackingId` (string)

## Responses

- `200`: OK
  - `trackingId` (string)
  - `status` (string)
  - `message` (string)
  - `errorStatus` (object[])
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "trackingId": "76803",
  "status": "success",
  "message": "Facility is saved successfully",
  "errorStatus": null
}
```


---

# Submit the v15Facility additional information

`POST /v1.5/facility/additional-information`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1.5/facility/additional-information \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "trackingId": "80266",
  "linkedProgramIds": {
    "nhrrId": "1234",
    "nin": "1234",
    "abpmjayId": "1234",
    "rohiniId": "1234",
    "echsId": "1234",
    "cghsId": "1234",
    "ceaRegistration": "1234",
    "stateInsuranceSchemeId": "1234"
  },
  "generalInformation": {
    "hasDialysisCenter": "YALL",
    "hasPharmacy": "YALL",
    "hasBloodBank": "YALL",
    "hasCathLab": "YALL",
    "hasDiagnosticLab": "YALL",
    "hasImagingCenter": "YALL",
    "servicesByImagingCenter": [
      {
        "service": "S36",
        "count": 7
      },
      {
        "service": "S16",
        "count": 5
      },
      {
        "service": "S23",
        "count": 3
      }
    ]
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `trackingId` (string, required)
- `linkedProgramIds` (object)
- `linkedProgramIds.nhrrId` (string)
- `linkedProgramIds.nin` (string)
- `linkedProgramIds.abpmjayId` (string)
- `linkedProgramIds.rohiniId` (string)
- `linkedProgramIds.echsId` (string)
- `linkedProgramIds.cghsId` (string)
- `linkedProgramIds.ceaRegistration` (string)
- `linkedProgramIds.stateInsuranceSchemeId` (string)
- `generalInformation` (object)
- `generalInformation.hasDialysisCenter` (string)
- `generalInformation.hasPharmacy` (string)
- `generalInformation.hasBloodBank` (string)
- `generalInformation.hasCathLab` (string)
- `generalInformation.hasDiagnosticLab` (string)
- `generalInformation.hasImagingCenter` (string)
- `generalInformation.servicesByImagingCenter` (object[])

## Responses

- `200`: OK
  - `trackingId` (string)
  - `status` (string)
  - `message` (string)
  - `errorStatus` (object[])
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "trackingId": "76803",
  "status": "Created",
  "message": "Facility details have been saved successfully. Please login at https://nhpr.abdm.gov.in/ and submit your facility details for approval.",
  "errorStatus": null
}
```


---

# Submit the v15Facility detailed information

`POST /v1.5/facility/detailed-information`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1.5/facility/detailed-information \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "trackingId": "80266",
  "specialities": [
    {
      "systemOfMedicineCode": "M",
      "isSpecializationAvalaible": "Y",
      "specialities": [
        "S29",
        "S30",
        "S31"
      ]
    },
    {
      "systemOfMedicineCode": "D",
      "isSpecializationAvalaible": "Y",
      "specialities": [
        "S50",
        "S51",
        "S46"
      ]
    },
    {
      "systemOfMedicineCode": "UN",
      "isSpecializationAvalaible": "Y",
      "specialities": [
        "S68",
        "S168",
        "S100"
      ]
    }
  ],
  "medicalInfrastructure": {
    "countIPDBedsWithoutOxygen": 2,
    "countIPDBedsWithOxygen": 3,
    "countICUBedsWithVentilators": 4,
    "countICUBedsWithoutVentilators": 1,
    "countHDUBedsWithVentilators": 5,
    "countHDUBedsWithoutVentilators": 6,
    "totalNumberOfVentilators": 7,
    "countDayCareBedsWithoutOxygen": 8,
    "countDayCareBedsWithOxygen": 9,
    "countDentalChairs": 1,
    "totalNumberOfBeds": 4
  },
  "pharmacyDetails": {
    "isJanAushadhiKendra": "Y",
    "janAushadhiKendraId": "jan-id",
    "drugLicenseNumber": "test1234",
    "pharmacyGstinNumber": "testg1234",
    "pharmacistRegistrationNumber": "reg1234"
  },
  "bloodBankDetails": {
    "isFacilityRegisteredInERaktkosh": "N",
    "eRaktoshId": "Y",
    "bloodBankLicenseNumber": "345-test-regno",
    "bloodStorageCenters": "Y",
    "storageCentersCount": 7,
    "bloodCollectedPerAnnum": "5",
    "bloodRequiredPerAnnum": "6"
  },
  "imagingServices": [
    {
      "service": "S136",
      "count": 77
    },
    {
      "service": "S139",
      "count": 99
    },
    {
      "service": "S138",
      "count": 76
    }
  ],
  "diagnosticServices": [
    ""
  ]
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `trackingId` (string)
- `specialities` (object[])
- `specialities.systemOfMedicineCode` (string)
- `specialities.isSpecializationAvalaible` (string)
- `specialities.specialities` (string[])
- `medicalInfrastructure` (object)
- `medicalInfrastructure.countLevel1IcuBedWithOutVentilators` (integer)
- `medicalInfrastructure.countIPDBedsWithoutOxygen` (integer)
- `medicalInfrastructure.countIPDBedsWithOxygen` (integer)
- `medicalInfrastructure.countICUBedsWithVentilators` (integer)
- `medicalInfrastructure.countICUBedsWithoutVentilators` (integer)
- `medicalInfrastructure.countHDUBedsWithVentilators` (integer)
- `medicalInfrastructure.countHDUBedsWithoutVentilators` (integer)
- `medicalInfrastructure.totalNumberOfVentilators` (integer)
- `medicalInfrastructure.countDayCareBedsWithoutOxygen` (integer)
- `medicalInfrastructure.countDayCareBedsWithOxygen` (integer)
- `medicalInfrastructure.countDentalChairs` (integer)
- `medicalInfrastructure.totalNumberOfBeds` (integer)
- `medicalInfrastructure.hasIcuBeds` (string)
- `medicalInfrastructure.countLevel1IcuBedWithVentilators` (integer)
- `medicalInfrastructure.CountLevel1IcuBedWithOutVentilators` (integer)
- `medicalInfrastructure.countLevel2IcuBeds` (integer)
- `medicalInfrastructure.countLevel3IcuBeds` (integer)
- `medicalInfrastructure.isIcuContactSameAsManager` (string)
- `medicalInfrastructure.cmoMoIcuControlMobile` (string)
- `pharmacyDetails` (object)
- `pharmacyDetails.isJanAushadhiKendra` (string)
- `pharmacyDetails.janAushadhiKendraId` (string)
- `pharmacyDetails.drugLicenseNumber` (string)
- `pharmacyDetails.pharmacyGstinNumber` (string)
- `pharmacyDetails.pharmacistRegistrationNumber` (string)
- `bloodBankDetails` (object)
- `bloodBankDetails.isFacilityRegisteredInERaktkosh` (string)
- `bloodBankDetails.eRaktoshId` (string)
- `bloodBankDetails.bloodBankLicenseNumber` (string)
- `bloodBankDetails.bloodStorageCenters` (string)
- `bloodBankDetails.storageCentersCount` (integer)
- `bloodBankDetails.bloodCollectedPerAnnum` (string)
- `bloodBankDetails.bloodRequiredPerAnnum` (string)
- `imagingServices` (object[])
- `imagingServices.service` (string)
- `imagingServices.count` (integer)
- `diagnosticServices` (string[])

## Responses

- `200`: OK
  - `trackingId` (string)
  - `status` (string)
  - `message` (string)
  - `errorStatus` (object[])
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "trackingId": "76803",
  "status": "Saved",
  "message": "Facility details have been saved successfully. Please login at \" + hfrUrl\n\" and submit your facility details for approval.",
  "errorStatus": null
}
```


---

# Submit the v15Submit facility details

`POST /v1.5/facility/submit-facility`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1.5/facility/submit-facility \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'x-hprid-auth: <X_HPRID_AUTH>' \
  --header 'x-hprid-auth-verifier: <X_HPRID_AUTH_VERIFIER>' \
  --header 'Content-Type: application/json' \
  --data '{
  "trackingId": "80266",
  "sourceOfInformation": "HRP_SUB_1",
  "sourceUniqueID": "1234",
  "facilitySuperUser": "STATE_SUPER_1"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Headers

- `x-hprid-auth` (string, required): The HPR token of the signed-in professional, from the HPR login.
- `x-hprid-auth-verifier` (string): The HPR token of the professional verifying the facility submission.

## Body

- `trackingId` (string, required)
- `sourceOfInformation` (string)
- `sourceUniqueID` (string)
- `facilitySuperUser` (string)

## Responses

- `200`: OK
- `404`: Not Found


---

# Change password

`POST /password/change/byPassword`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/password/change/byPassword \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "newPassword": "<BASE64 ENCODED STRING>",
  "oldPassword": "<BASE64 ENCODED STRING>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `oldPassword` (string)
- `newPassword` (string)
- `txnId` (string)
- `hprID` (string)
- `otp` (string)

## Responses

- `200`: OK
  - `message` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "message": "Password has been changed successfully!"
}
```


---

# Recover password via Aadhaar

`POST /password/recover/byAadhaar`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/password/recover/byAadhaar \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hprId": "<HPR_ID>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `hprId` (string, required)
- `categories` (object)

## Responses

- `200`: OK
  - `txnId` (string): Based on UUID
  - `mobileNumber` (string)
  - `msg` (string)
  - `verified` (boolean)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "txnId": "9b78fdfb-3ba4-4707-8913-63c7c5e3a743",
  "mobileNumber": "******8063",
  "msg": "",
  "verified": false
}
```


---

# Generate mobile OTP 1

`POST /password/recover/byMobile/sendMobileOTP`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/password/recover/byMobile/sendMobileOTP \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hprId": "amol.xxxxxx"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `hprId` (string, required)
- `categories` (object)

## Responses

- `200`: OK
  - `txnId` (string)
  - `msg` (string)
  - `mobileNumber` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "txnId": "7ebad8aa-127b-492f-bd0e-56da716bd39e",
  "msg": "Please enter OTP sent on your mobile number ******2021",
  "otp": 0,
  "mobileNumber": "******2021"
}
```


---

# Verify mobile OTP 1

`POST /password/recover/byMobile/verifyMobileOTP`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/password/recover/byMobile/verifyMobileOTP \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "7ebad8aa-127b-492f-bd0e-56da716bd39e",
  "otp": "<BASE64 ENCODED STRING>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `oldPassword` (string)
- `newPassword` (string)
- `txnId` (string)
- `hprID` (string)
- `otp` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `msg` (string)
  - `mobileNumber` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "verified": true,
  "txnId": "7ebad8aa-127b-492f-bd0e-56da716bd39e"
}
```


---

# Recover password confirm by Aadhaar

`POST /password/recover/confirmByAadhaar`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/password/recover/confirmByAadhaar \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "otp": "<BASE64 ENCODED STRING>",
  "txnId": "9b78fdfb-3ba4-4707-8913-63c7c5e3a743"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `newPassword` (string): Encrypted new Password.
- `otp` (string): Encrypted OTP.
- `txnId` (string, required)

## Responses

- `200`: OK
  - `verified` (boolean)
  - `txnId` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "verified": true,
  "txnId": "9b78fdfb-3ba4-4707-8913-63c7c5e3a743"
}
```


---

# Reset password and session

`POST /password/reset/password`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/password/reset/password \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "newPassword": "<NEW_PASSWORD>",
  "otp": "<OTP>",
  "txnId": "5f7a4a1e-59ba-4c0c-9e0c-8e6b3b6e2f11"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `newPassword` (string): Encrypted new Password.
- `otp` (string): Encrypted OTP.
- `txnId` (string, required)

## Responses

- `200`: OK
- `404`: Not Found


---

# Reset password

`POST /password/resetPassword`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/password/resetPassword \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "9b78fdfb-3ba4-4707-8913-63c7c5e3a743",
  "newPassword": "<BASE64 ENCODED STRING>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `newPassword` (string): Encrypted new Password.
- `otp` (string): Encrypted OTP.
- `txnId` (string, required)

## Responses

- `200`: OK
  - `message` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "message": "Password has been changed successfully!"
}
```


---

# Get account png card

`GET /v1/account/getIdCard`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/account/getIdCard \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-Token: <X_TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Headers

- `X-Token` (string): The HPR token of the signed-in professional, from the HPR login.

## Responses

- `200`: OK
  - `pdf` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "pdf": "JVBERi0xLjMK"
}
```


---

# Get user profile by JWT

`GET /v1/account/information`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/account/information \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Query parameters

- `masked` (boolean)

## Responses

- `200`: OK
  - `hprIdNumber` (string)
  - `hprId` (string)
  - `mobile` (string)
  - `firstName` (string)
  - `middleName` (string)
  - `lastName` (string)
  - `name` (string)
  - `yearOfBirth` (string)
  - `dayOfBirth` (string)
  - `monthOfBirth` (string)
  - `gender` (string)
  - `email` (string)
  - `profilePhoto` (string)
  - `stateCode` (string)
  - `districtCode` (string)
  - `subDistrictCode` (string)
  - `villageCode` (string)
  - `townCode` (string)
  - `wardCode` (string)
  - `pincode` (string)
  - `address` (string)
  - `kycPhoto` (string)
  - `stateName` (string)
  - `districtName` (string)
  - `subdistrictName` (string)
  - `villageName` (string)
  - `townName` (string)
  - `wardName` (string)
  - `authMethods` (string[])
  - `kycVerified` (boolean)
  - `verificationStatus` (string)
  - `categoryId` (integer)
  - `categoryName` (string)
  - `categorySubId` (integer)
  - `categorySubName` (string)
  - `emailVerified` (boolean)
  - `role` (integer)
  - `new` (boolean)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "hprIdNumber": "<HPR_ID>",
  "hprId": "<EMAIL>",
  "mobile": "******2125",
  "firstName": "Ayushman",
  "middleName": "Bharat",
  "lastName": "Mission",
  "name": "Ayushman Bharat Mission",
  "yearOfBirth": "<DOB>",
  "dayOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "gender": "M",
  "email": "<ABHA_ADDRESS>.com",
  "profilePhoto": "<BASE64 ENCODED STRING>",
  "stateCode": "27",
  "districtCode": "490",
  "subDistrictCode": null,
  "villageCode": null,
  "townCode": null,
  "wardCode": null,
  "pincode": "<PINCODE>",
  "address": "9th Floor, Tower-l, Jeevan Bharati Building, Connaught Place, New Delhi - 110001",
  "kycPhoto": "<BASE64 ENCODED STRING>",
  "stateName": "MAHARASHTRA",
  "districtName": "<ADDRESS>",
  "subdistrictName": null,
  "villageName": null,
  "townName": "<ADDRESS>",
  "wardName": null,
  "authMethods": [
    "MOBILE_OTP",
    "DEMOGRAPHICS",
    "... 1 more of the same shape"
  ],
  "kycVerified": true,
  "verificationStatus": "true",
  "categoryId": 1,
  "categoryName": "DOCTOR",
  "categorySubId": 3,
  "categorySubName": "AYURVEDA",
  "emailVerified": false,
  "new": false
}
```


---

# Generate Aadhaar OTPFor re KYC

`POST /v1/account/reKYC/generateAadhaarOTP`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/account/reKYC/generateAadhaarOTP \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Responses

- `200`: OK
- `404`: Not Found


---

# Verify Aadhaar OTP

`POST /v1/account/reKYC/verifyAadhaarOTP`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/account/reKYC/verifyAadhaarOTP \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "authType": "AADHAAR_OTP",
  "hprId": "<HPR_ID>",
  "password": "<PASSWORD>",
  "aadhaar": "<AADHAAR>",
  "mobileNumber": "<MOBILE_NUMBER>",
  "txnId": "5f7a4a1e-59ba-4c0c-9e0c-8e6b3b6e2f11",
  "otp": "<OTP>",
  "resend": false,
  "aadhaarVerifyOtpRequestDto": {
    "aadhaarNumber": "<AADHAAR_NUMBER>",
    "otp": "<OTP>",
    "faceAuthPid": "<FACE_AUTH_PID>",
    "aadhaarLogType": "<AADHAAR_LOG_TYPE>",
    "transactionId": "<TRANSACTION_ID>",
    "txnId": "<TXN_ID>"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `authType` (string) One of: AADHAAR_OTP, USERNAME_PASSWORD, MOBILE_OTP.
- `hprId` (string)
- `password` (string)
- `aadhaar` (string)
- `mobileNumber` (string)
- `txnId` (string)
- `otp` (string)
- `resend` (boolean)
- `aadhaarVerifyOtpRequestDto` (object)
- `aadhaarVerifyOtpRequestDto.aadhaarNumber` (string)
- `aadhaarVerifyOtpRequestDto.otp` (string)
- `aadhaarVerifyOtpRequestDto.faceAuthPid` (string)
- `aadhaarVerifyOtpRequestDto.aadhaarLogType` (string)
- `aadhaarVerifyOtpRequestDto.transactionId` (string)
- `aadhaarVerifyOtpRequestDto.txnId` (string)

## Responses

- `200`: OK
- `404`: Not Found


---

# Verify Aadhaar OTPGet details

`POST /v1/account/reKYC/verifyAadhaarOTPGetDetails`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/account/reKYC/verifyAadhaarOTPGetDetails \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "authType": "AADHAAR_OTP",
  "hprId": "<HPR_ID>",
  "password": "<PASSWORD>",
  "aadhaar": "<AADHAAR>",
  "mobileNumber": "<MOBILE_NUMBER>",
  "txnId": "5f7a4a1e-59ba-4c0c-9e0c-8e6b3b6e2f11",
  "otp": "<OTP>",
  "resend": false,
  "aadhaarVerifyOtpRequestDto": {
    "aadhaarNumber": "<AADHAAR_NUMBER>",
    "otp": "<OTP>",
    "faceAuthPid": "<FACE_AUTH_PID>",
    "aadhaarLogType": "<AADHAAR_LOG_TYPE>",
    "transactionId": "<TRANSACTION_ID>",
    "txnId": "<TXN_ID>"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `authType` (string) One of: AADHAAR_OTP, USERNAME_PASSWORD, MOBILE_OTP.
- `hprId` (string)
- `password` (string)
- `aadhaar` (string)
- `mobileNumber` (string)
- `txnId` (string)
- `otp` (string)
- `resend` (boolean)
- `aadhaarVerifyOtpRequestDto` (object)
- `aadhaarVerifyOtpRequestDto.aadhaarNumber` (string)
- `aadhaarVerifyOtpRequestDto.otp` (string)
- `aadhaarVerifyOtpRequestDto.faceAuthPid` (string)
- `aadhaarVerifyOtpRequestDto.aadhaarLogType` (string)
- `aadhaarVerifyOtpRequestDto.transactionId` (string)
- `aadhaarVerifyOtpRequestDto.txnId` (string)

## Responses

- `200`: OK
- `404`: Not Found


---

# Get user details

`GET /v1/account/user-details/{hprId}`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/account/user-details/{hprId} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Path parameters

- `hprId` (string, required)

## Responses

- `200`: OK
- `404`: Not Found


---

# Logout

`GET /v4/auth/logout`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/v4/auth/logout \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Responses

- `200`: OK
- `404`: Not Found


---

# Generate Aadhaar link

`POST /aadhaar/generateLink`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/aadhaar/generateLink \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "scopes": [
    "nhpr-register"
  ],
  "source": "NHPR"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `scopes` (string[])
- `source` (string)

## Responses

- `200`: OK
  - `status` (string)
  - `txnId` (string)
  - `url` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "txnId": "de4ff682-fcc6-4bcf-a978-0dbb19a288b4",
  "mobileNumber": "******1234"
}
```


---

# Submit the is Aadhaar authenticated

`POST /aadhaar/isAuthenticated`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/aadhaar/isAuthenticated \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "259813b1-a339-4482-8df5-16ee45b8dcf2"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `txnId` (string)

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
true
```


---

# Verify OTP

`POST /v2/registration/aadhaar/verifyOTP`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v2/registration/aadhaar/verifyOTP \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "de4ff682-fcc6-4bcf-a978-0dbb19a288b4"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `txnId` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `mobileNumber` (string)
  - `photo` (string)
  - `gender` (string)
  - `name` (string)
  - `email` (string)
  - `pincode` (string)
  - `birthdate` (string)
  - `careOf` (string)
  - `house` (string)
  - `street` (string)
  - `landmark` (string)
  - `locality` (string)
  - `villageTownCity` (string)
  - `subDist` (string)
  - `district` (string)
  - `state` (string)
  - `postOffice` (string)
  - `address` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "txnId": "951b4258-2ac7-432c-8dbf-6ed990757b88",
  "mobileNumber": null,
  "photo": "<BASE64 ENCODED STRING>",
  "gender": "M",
  "name": "Ayushman Bharat Mission",
  "email": null,
  "pincode": "<PINCODE>",
  "birthdate": "<DOB>",
  "careOf": "<NAME>",
  "house": "<ADDRESS>",
  "street": "<ADDRESS>",
  "landmark": null,
  "locality": "<ADDRESS>",
  "villageTownCity": "Sahibabad",
  "subDist": null,
  "district": "Ghaziabad",
  "state": "Uttar Pradesh",
  "postOffice": "Sahibabad",
  "address": "9th Floor, Tower-l, Jeevan Bharati Building, Connaught Place, New Delhi - 110001"
}
```


---

# Submit the demographic auth via mobile

`POST /v2/registration/aadhaar/demographicAuthViaMobile`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v2/registration/aadhaar/demographicAuthViaMobile \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "de4ff682-fcc6-4bcf-a978-0dbb19a288b4",
  "mobileNumber": "JrHfDROoEcsYJ41g2wdkicsI7mT1ATCP347iqwBhWbfaEIgZ03/WHAYvDHRG2WXl4HBNuP2orD+3O75pN0xFhOz4oLXrePAxKTLK8uG5jdeAiGE2lKwOrShq9/gg+BckrQcDYjpMUePRuDau4mqLHa8FdSCQ8npGPY9KCpD2hZkscWNqZR68gRo/EwpY4u32kDzv5i1K/s+A7FNVwXqZS5AK2BadEhG5drSRk7P83eFxJZUlwtsvDK6iipOsM4VtMXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `txnId` (string)
- `mobileNumber` (string)

## Responses

- `200`: OK
  - `verified` (boolean)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "verified": true,
  "errorCode": null,
  "reason": null,
  "uidaiToken": null
}
```


---

# Submit the account exist

`POST /v1/registration/aadhaar/checkHpIdAccountExist`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/registration/aadhaar/checkHpIdAccountExist \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "de4ff682-fcc6-4bcf-a978-0dbb19a288b4"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `txnId` (string)
- `preverifiedCheck` (boolean)

## Responses

- `200`: OK
  - `token` (string)
  - `hprIdNumber` (string)
  - `categoryId` (integer)
  - `categoryName` (string)
  - `subCategoryId` (integer)
  - `categorySubName` (string)
  - `txnId` (string)
  - `name` (string)
  - `gender` (string)
  - `yearOfBirth` (string)
  - `monthOfBirth` (string)
  - `dayOfBirth` (string)
  - `firstName` (string)
  - `middleName` (string)
  - `lastName` (string)
  - `stateCode` (string)
  - `districtCode` (string)
  - `stateName` (string)
  - `districtName` (string)
  - `address` (string)
  - `pincode` (string)
  - `profilePhoto` (string)
  - `mobile` (string)
  - `hprId` (string)
  - `new` (boolean)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "token": "<JWT TOKEN>",
  "hprIdNumber": "<HPR_ID>",
  "categoryId": 100,
  "subCategoryId": 85,
  "txnId": "79dbf65d-affa-4249-8935-3d01676d8b82",
  "name": "Ayushman Bharat Mission",
  "gender": "M",
  "yearOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "dayOfBirth": "<DOB>",
  "firstName": "Ayushman",
  "middleName": "",
  "lastName": "Mission",
  "stateCode": "9",
  "districtCode": "145",
  "stateName": "Uttar Pradesh",
  "districtName": "<ADDRESS>",
  "address": "9th Floor, Tower-l, Jeevan Bharati Building, Connaught Place, New Delhi - 110001",
  "pincode": "<PINCODE>",
  "profilePhoto": "<BASE64 ENCODED STRING>",
  "mobile": null,
  "hprId": "<EMAIL>",
  "new": false
}
```


---

# Get suggesstion

`POST /v1/registration/aadhaar/hpid/suggestion`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/registration/aadhaar/hpid/suggestion \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "a825f76b-0696-40f3-864c-5a3a5b389a83"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `txnId` (string, required): Based on UUID

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
[
  "anujsharma"
]
```


---

# Generate mobile OTP

`POST /v1/registration/aadhaar/generateMobileOTP`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/registration/aadhaar/generateMobileOTP \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "mobile": "981065XXXX",
  "txnId": "de4ff682-fcc6-4bcf-a978-0dbb19a288b4"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `mobile` (string)
- `txnId` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `mobileNumber` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "txnId": "951b4258-2ac7-432c-8dbf-6ed990757b88",
  "mobileNumber": null
}
```


---

# Verify mobile OTP

`POST /v1/registration/aadhaar/verifyMobileOTP`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/registration/aadhaar/verifyMobileOTP \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "otp": "<BASE64 ENCODED STRING>",
  "txnId": "de4ff682-fcc6-4bcf-a978-0dbb19a288b4"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `otp` (string)
- `txnId` (string)

## Responses

- `200`: OK
- `404`: Not Found


---

# Create HPR ID V2

`POST /v2/registration/aadhaar/createHprIdWithPreVerified`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v2/registration/aadhaar/createHprIdWithPreVerified \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "idType": "hpr_id",
  "domainName": "@hpr.abdm",
  "email": "<ABHA_ADDRESS>.com",
  "firstName": "Ayushman",
  "middleName": "Bharat",
  "lastName": "Mission",
  "password": "Ayushman@143",
  "profilePhoto": "<BASE64 ENCODED STRING>",
  "txnId": "c3b0c27d-e19d-4244-b8bb-3fa19285054a",
  "hprId": "<EMAIL>",
  "sourceType": "DRIVING_LICENSE",
  "hpCategoryCode": 1,
  "hpSubCategoryCode": 1,
  "clientId": "V4",
  "stateCode": "<STATE_CODE>",
  "districtCode": "<DISTRICT_CODE>",
  "council": false,
  "role": 0
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `idType` (string)
- `domainName` (string)
- `email` (string, required): Email Address of the user.
- `firstName` (string): First Name of the user).
- `middleName` (string): Middle name of the user
- `lastName` (string): Last name of the user
- `password` (string): Passwords for authentication
- `profilePhoto` (string): Profile photo of the user (Uploaded by the user).
- `txnId` (string, required): Transaction ID
- `hprId` (string): Healthcare Professional ID Alias.
- `sourceType` (string) One of: DRIVING_LICENSE, AADHAAR.
- `hpCategoryCode` (integer)
- `hpSubCategoryCode` (integer)
- `clientId` (string)
- `stateCode` (string)
- `districtCode` (string)
- `council` (boolean)
- `role` (integer)

## Responses

- `200`: OK
- `404`: Not Found


---

# Get facility and infrastructure within radius with filter

`POST /FacilityManagement/v1.5/facility/bygeoLocation/searchFacilityAndInfrastructureWithinRadiusWithFilter`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/FacilityManagement/v1.5/facility/bygeoLocation/searchFacilityAndInfrastructureWithinRadiusWithFilter \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "centerLat": "<CENTER_LAT>",
  "centerLon": "<CENTER_LON>",
  "radiusInKm": "<RADIUS_IN_KM>",
  "speciality": "<SPECIALITY>",
  "facilityOwnership": "<FACILITY_OWNERSHIP>",
  "abdmSoftware": "<ABDM_SOFTWARE>",
  "hospitalSpecialityType": "<HOSPITAL_SPECIALITY_TYPE>",
  "facilityName": "<FACILITY_NAME>",
  "facilityStatus": "<FACILITY_STATUS>",
  "som": "<SOM>",
  "gender": "<GENDER>",
  "doctorName": "<DOCTOR_NAME>",
  "doctorSystemOfMedicine": "<DOCTOR_SYSTEM_OF_MEDICINE>",
  "languages": "<LANGUAGES>",
  "isIcuBedsAvailable": "<IS_ICU_BEDS_AVAILABLE>",
  "size": "<SIZE>",
  "from": "<FROM>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `centerLat` (string)
- `centerLon` (string)
- `radiusInKm` (string)
- `speciality` (string)
- `facilityOwnership` (string)
- `abdmSoftware` (string)
- `hospitalSpecialityType` (string)
- `facilityName` (string)
- `facilityStatus` (string)
- `som` (string)
- `gender` (string)
- `doctorName` (string)
- `doctorSystemOfMedicine` (string)
- `languages` (string)
- `isIcuBedsAvailable` (string)
- `size` (string)
- `from` (string)

## Responses

- `200`: OK
- `404`: Not Found


---

# Search facility

`POST /FacilityManagement/v1.5/facility/search`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/FacilityManagement/v1.5/facility/search \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "ownershipCode": "P",
  "subDistrictLGDCode": "",
  "pincode": "",
  "facilityName": "hospital",
  "facilityId": "",
  "page": 1,
  "resultsPerPage": 10,
  "stateLGDCode": "27",
  "districtLGDCode": ""
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `ownershipCode` (string)
- `subDistrictLGDCode` (string)
- `pincode` (string)
- `facilityName` (string)
- `facilityId` (string)
- `page` (integer)
- `resultsPerPage` (integer)
- `stateLGDCode` (string)
- `districtLGDCode` (string)

## Responses

- `200`: OK
  - `facilities` (object[])
  - `message` (string)
  - `totalFacilities` (integer)
  - `numberOfPages` (integer)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "facilities": [
    {
      "ownership": "GOVERNMENT",
      "systemOfMedicineCode": "P,M",
      "systemOfMedicine": "Physiotherapy,Modern Medicine(Allopathy)",
      "facilityType": "Hospital",
      "stateName": "Bihar",
      "stateLGDCode": "10",
      "districtName": "<ADDRESS>",
      "districtLGDCode": "212",
      "subDistrictName": "<ADDRESS>",
      "subDistrictLGDCode": "1400",
      "villageCityTownName": null,
      "villageCityTownLGDCode": null,
      "address": "<ADDRESS>",
      "pincode": "<PINCODE>",
      "latitude": "25.635802000000098",
      "longitude": "85.10391099999993",
      "facilityId": "",
      "facilityName": "Asian City Hospital",
      "facilityStatus": "Submitted",
      "ownershipCode": "G",
      "facilityTypeCode": "H"
    }
  ],
  "message": "Request processed successfully",
  "totalFacilities": 1,
  "numberOfPages": 1
}
```


---

# Get the exists by HPR ID

`GET /v1/search/existsByHprId/{hprId}`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/search/existsByHprId/{hprId} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Path parameters

- `hprId` (string, required)

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
true
```


---

# Search user by HPR ID

`GET /v1/search/searchByHprId/{hprId}`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/search/searchByHprId/{hprId} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Path parameters

- `hprId` (string, required)

## Responses

- `200`: OK
  - `hprIdNumber` (string)
  - `name` (string)
  - `authMethods` (string[])
  - `hprId` (string)
  - `categoryId` (string)
  - `subCategoryId` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "hprIdNumber": "<HPR_ID>",
  "name": "Ayushman Bharat Mission",
  "authMethods": [
    "PASSWORD",
    "MOBILE_OTP",
    "... 1 more of the same shape"
  ],
  "hprId": "<EMAIL>",
  "categoryId": "1",
  "subCategoryId": "1"
}
```


---

# Search user by mobile no

`GET /v1/search/searchByMobile/{mobile}`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/search/searchByMobile/{mobile} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Path parameters

- `mobile` (string, required)

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
[
  {
    "hprIdNumber": "<HPR_ID>",
    "name": "Ayushman Bharat Mission",
    "authMethods": [
      "PASSWORD",
      "MOBILE_OTP",
      "... 1 more of the same shape"
    ],
    "hprId": "<EMAIL>",
    "categoryId": "1",
    "subCategoryId": "1"
  }
]
```


---

# Fetch HPID categories

`GET /hpid/get/categories`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/hpid/get/categories \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Query parameters

- `role` (integer)

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
[
  {
    "code": 1,
    "name": "Doctor",
    "subCategories": [
      {
        "code": "220",
        "name": "Yoga and Naturopathy"
      },
      {
        "code": "1",
        "name": "Modern Medicine"
      },
      "... 1 more of the same shape"
    ]
  },
  {
    "code": 2,
    "name": "Nurse",
    "subCategories": [
      {
        "code": "9",
        "name": "Registered Nurse and Registered Midwife (RN & RM)"
      },
      {
        "code": "10",
        "name": "Registered Lady Health Visitor (RLHV)"
      },
      "... 1 more of the same shape"
    ]
  },
  "... 1 more of the same shape"
]
```


---

# Fetch HPID sub categories from category

`GET /hpid/get/subCategories`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/hpid/get/subCategories \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Query parameters

- `categoryCode` (string)
- `role` (integer)

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
[
  {
    "code": "220",
    "name": "Yoga and Naturopathy"
  },
  {
    "code": "1",
    "name": "Modern Medicine"
  },
  "... 1 more of the same shape"
]
```


---

# Get PSU details by ministry

`GET /getPsuDetailsByMinistry`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/getPsuDetailsByMinistry \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Query parameters

- `ministry` (string)

## Responses

- `200`: OK
- `404`: Not Found


---

# Get all facility sub type by facility type

`POST /v1.5/facility/fetch-facility-Sub-type`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1.5/facility/fetch-facility-Sub-type \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "facilityTypeCode": "2"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `facilityTypeCode` (string, required)

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "type": "FACILITY-SUB-TYPE",
  "data": [
    {
      "code": "29",
      "value": "Any Other"
    },
    {
      "code": "1",
      "value": "Block Primary Health Centre"
    },
    "... 1 more of the same shape"
  ]
}
```


---

# Get all facility type by ownership and sys of med

`POST /v1.5/facility/fetch-facility-type`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1.5/facility/fetch-facility-type \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "ownershipCode": "G",
  "systemOfMedicineCode": "M"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `ownershipCode` (string, required)
- `systemOfMedicineCode` (string, required)

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "type": "FACILITY-TYPE",
  "data": [
    {
      "code": "9",
      "value": "Blood Bank"
    },
    {
      "code": "74",
      "value": "Imaging Center"
    },
    "... 1 more of the same shape"
  ]
}
```


---

# Get master data

`GET /v1.5/facility/get-master-data`

```bash
curl --request GET \
  --url "https://apihspsbx.abdm.gov.in/v4/int/v1.5/facility/get-master-data?type=<TYPE>" \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Query parameters

- `type` (string, required)

## Responses

- `200`: OK
  - `type` (string)
  - `data` (object[])
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "type": "MEDICINE",
  "data": [
    {
      "code": "H",
      "value": "Homeopathy"
    },
    {
      "code": "UN",
      "value": "Unani"
    },
    "... 1 more of the same shape"
  ]
}
```


---

# Get all master types

`GET /v1.5/facility/get-master-types`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1.5/facility/get-master-types \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Responses

- `200`: OK
  - `masterTypes` (object[])
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "masterTypes": [
    {
      "type": "MEDICINE",
      "desc": "System Of Medicine"
    },
    {
      "type": "OWNER",
      "desc": "Ownership Of Facility"
    },
    "... 1 more of the same shape"
  ]
}
```


---

# Get all sub types by owner ship type and sub type

`POST /v1.5/facility/get-owner-subtype`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1.5/facility/get-owner-subtype \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "ownershipCode": "P",
  "ownerSubtypeCode": "NP"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `ownershipCode` (string, required)
- `ownerSubtypeCode` (string, required)

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "type": "CENTRAL-GOVERNMENT",
  "data": [
    {
      "code": "MOHF",
      "value": "Mo Health and Family Welfare"
    },
    {
      "code": "MOR",
      "value": "Mo Railways"
    },
    "... 1 more of the same shape"
  ]
}
```


---

# Get all specialities by system of medicine code

`POST /v1.5/facility/get-specialities`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1.5/facility/get-specialities \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "systemOfMedicineCode": "D"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `systemOfMedicineCode` (string, required)

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "type": "SPECIALITIES",
  "data": [
    {
      "code": "D-S44",
      "value": "OralMedicine and Radiology"
    },
    {
      "code": "D-S46",
      "value": "Oral& Maxillofacial Surgery"
    },
    "... 1 more of the same shape"
  ]
}
```


---

# Get all district by state ID

`GET /v1.5/facility/lgd/districts`

```bash
curl --request GET \
  --url "https://apihspsbx.abdm.gov.in/v4/int/v1.5/facility/lgd/districts?stateCode=<STATECODE>" \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Query parameters

- `stateCode` (string, required)

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
[
  {
    "code": "1",
    "name": "Anantnag"
  },
  {
    "code": "623",
    "name": "Bandipora"
  },
  "... 1 more of the same shape"
]
```


---

# Get all states by LGD

`GET /v1.5/facility/lgd/states`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1.5/facility/lgd/states \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
[
  {
    "code": "35",
    "name": "Andaman And Nicobar Islands",
    "districts": [
      {
        "code": "603",
        "name": "Nicobars"
      },
      {
        "code": "632",
        "name": "North And Middle Andaman"
      },
      "... 1 more of the same shape"
    ]
  },
  {
    "code": "28",
    "name": "Andhra Pradesh",
    "districts": [
      {
        "code": "745",
        "name": "<NAME>"
      },
      {
        "code": "744",
        "name": "Anakapalli"
      },
      "... 1 more of the same shape"
    ]
  },
  "... 1 more of the same shape"
]
```


---

# Get all sub district by district code

`GET /v1.5/facility/lgd/subdistricts`

```bash
curl --request GET \
  --url "https://apihspsbx.abdm.gov.in/v4/int/v1.5/facility/lgd/subdistricts?districtCode=<DISTRICTCODE>" \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Query parameters

- `districtCode` (string, required)

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
[
  {
    "code": "6752",
    "name": "Assar"
  },
  {
    "code": "65",
    "name": "Bhaderwah"
  },
  "... 1 more of the same shape"
]
```


---

# Get all affiliated board

`GET /apis/v1/masters/affiliated-board`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/affiliated-board \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
[
  {
    "id": 1,
    "name": "Central Board Of Secondary Education (CBSE)",
    "status": true,
    "visibleStatus": true,
    "stateId": null,
    "courseId": null,
    "councilBoard": false,
    "nationalBoard": true
  },
  {
    "id": 2,
    "name": "Council for the Indian School Certificate Examination (CISCE)",
    "status": true,
    "visibleStatus": true,
    "stateId": null,
    "courseId": null,
    "councilBoard": false,
    "nationalBoard": true
  },
  "... 1 more of the same shape"
]
```


---

# Get affiliated board by state ID

`GET /apis/v1/masters/affiliated-board/states/{id}`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/affiliated-board/states/{id} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Path parameters

- `id` (integer, required)

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
[
  {
    "id": 38,
    "name": "Maharashtra  State Board of Secondary  and Higher Secondary  Education,   Pune",
    "status": true,
    "visibleStatus": true,
    "stateId": 20,
    "courseId": null,
    "councilBoard": false,
    "nationalBoard": false
  },
  {
    "id": 821,
    "name": "MAHARASHTRA NURSING COUNCIL, MUMBAI",
    "status": true,
    "visibleStatus": true,
    "stateId": 20,
    "courseId": null,
    "councilBoard": true,
    "nationalBoard": false
  },
  "... 1 more of the same shape"
]
```


---

# Get affiliated board by ID

`GET /apis/v1/masters/affiliated-board/{id}`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/affiliated-board/{id} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Path parameters

- `id` (integer, required)

## Responses

- `200`: OK
- `404`: Not Found


---

# Get college by state

`GET /apis/v1/masters/colleges/{id}`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/colleges/{id} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Path parameters

- `id` (integer, required)

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
[
  {
    "id": 21,
    "name": "Dayanand Medical College And Hospital",
    "status": true,
    "visibleStatus": true,
    "createdAt": "2023-08-17T16:58:31.000Z",
    "systemOfMedicineId": 1,
    "stateId": 27,
    "courseId": null,
    "stateName": "Maharashtra",
    "systemOfMedicineName": null,
    "deleted": false
  },
  {
    "id": 22,
    "name": "Gian Sagar Medical College And Hospital",
    "status": true,
    "visibleStatus": true,
    "createdAt": "2023-08-17T16:58:31.000Z",
    "systemOfMedicineId": 1,
    "stateId": 27,
    "courseId": null,
    "stateName": "Maharashtra",
    "systemOfMedicineName": null,
    "deleted": false
  },
  "... 1 more of the same shape"
]
```


---

# Get college by state and medicine ID

`GET /apis/v1/masters/colleges/{stateId}/{medicineId}`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/colleges/{stateId}/{medicineId} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Path parameters

- `stateId` (integer, required)
- `medicineId` (string, required)

## Responses

- `200`: OK
- `404`: Not Found


---

# Get all countries

`GET /apis/v1/masters/countries`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/countries \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Responses

- `200`: OK
- `404`: Not Found


---

# Get countries by ID

`GET /apis/v1/masters/countries/{id}`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/countries/{id} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Path parameters

- `id` (integer, required)

## Responses

- `200`: OK
- `404`: Not Found


---

# List courses

`POST /apis/v1/masters/courses`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/courses \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "systemOfMedicine": "Registered Auxiliary Nurse Midwife(RANM)",
  "hprType": "nurse",
  "qualificationCount": 0
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `id` (integer)
- `name` (string)
- `systemOfMedicineId` (integer)
- `visibleStatus` (boolean)
- `status` (boolean)
- `sortOrder` (boolean)
- `courseCategory` (string) One of: basic, additional.
- `systemOfMedicine` (string)
- `hprType` (string) One of: doctor, nurse, facility_manager, asha, paharmacist, anganwadi, administrator, paramedical, pharmacist.
- `qualificationCount` (integer)
- `international` (boolean)
- `createdBy` (integer)
- `acronym` (string)
- `priority` (string)

## Responses

- `200`: OK
- `404`: Not Found


---

# Get all districts

`GET /apis/v1/masters/district`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/district \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Responses

- `200`: OK
- `404`: Not Found


---

# Get districts by state

`GET /apis/v1/masters/district/{id}`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/district/{id} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Path parameters

- `id` (integer, required)

## Responses

- `200`: OK
- `404`: Not Found


---

# List government health programmes

`GET /apis/v1/masters/languages`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/languages \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Responses

- `200`: OK
- `404`: Not Found


---

# Get pi languages by ID

`GET /apis/v1/masters/languages/{id}`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/languages/{id} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Path parameters

- `id` (integer, required)

## Responses

- `200`: OK
- `404`: Not Found


---

# Get all medical council

`GET /apis/v1/masters/medical-councils`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/medical-councils \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Responses

- `200`: OK
- `404`: Not Found


---

# Get medical council by system of medicine name

`GET /apis/v1/masters/medical-councils/name`

```bash
curl --request GET \
  --url "https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/medical-councils/name?medicineName=<MEDICINENAME>" \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Query parameters

- `medicineName` (string, required)

## Responses

- `200`: OK
- `404`: Not Found


---

# Get all nurse councils

`GET /apis/v1/masters/nurse-councils`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/nurse-councils \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
[
  {
    "id": 1,
    "name": "Andhra Pradesh  Nurses Midwives And Health Visitors Council, Vijayawada",
    "status": true,
    "visibleStatus": true,
    "position": 0,
    "stateId": 2
  },
  {
    "id": 2,
    "name": "Arunachal Pradesh Nursing Council",
    "status": true,
    "visibleStatus": true,
    "position": 0,
    "stateId": 3
  },
  "... 1 more of the same shape"
]
```


---

# Get all states

`GET /apis/v1/masters/states`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/states \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Responses

- `200`: OK
- `404`: Not Found


---

# Get status

`GET /apis/v1/masters/states/{id}`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/states/{id} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Path parameters

- `id` (integer, required)

## Responses

- `200`: OK
- `404`: Not Found


---

# Get all sub districts

`GET /apis/v1/masters/sub-districts`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/sub-districts \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Responses

- `200`: OK
- `404`: Not Found


---

# Get all sub districts 1

`GET /apis/v1/masters/sub-districts/{id}`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/sub-districts/{id} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Path parameters

- `id` (integer, required)

## Responses

- `200`: OK
- `404`: Not Found


---

# Get all medical system

`GET /apis/v1/masters/system-of-medicines`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/system-of-medicines \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Responses

- `200`: OK
- `404`: Not Found


---

# List all university

`GET /apis/v1/masters/universites`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/universites \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Responses

- `200`: OK
- `404`: Not Found


---

# Get university by college

`GET /apis/v1/masters/universites/{id}`

```bash
curl --request GET \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/masters/universites/{id} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Path parameters

- `id` (integer, required)

## Responses

- `200`: OK
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
[
  {
    "id": 6046,
    "name": "Baba Farid University Of Health Sciences,faridkot",
    "status": true,
    "visibleStatus": true,
    "collegeId": 27,
    "collegeName": null,
    "deleted": false,
    "college": null
  }
]
```


---

# Get facilities created by HPR ID

`POST /getFacilityCreatedByHprId`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/getFacilityCreatedByHprId \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hprId": "<HPR_ID>",
  "source": "<SOURCE>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Query parameters

- `page` (integer)
- `size` (integer)

## Body

- `hprId` (string)
- `source` (string)

## Responses

- `200`: OK
- `404`: Not Found


---

# Get facilities declared by HPR ID

`POST /getFacilityDeclaredByHprId`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/getFacilityDeclaredByHprId \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hprId": "<HPR_ID>",
  "source": "<SOURCE>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `hprId` (string)
- `source` (string)

## Responses

- `200`: OK
- `404`: Not Found


---

# Update status

`PUT /hprWorkDetails/status`

```bash
curl --request PUT \
  --url https://apihspsbx.abdm.gov.in/v4/int/hprWorkDetails/status \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "<STATUS>",
  "facilityId": "<FACILITY_ID>",
  "professionalHprId": "<PROFESSIONAL_HPR_ID>",
  "managerHprId": "<MANAGER_HPR_ID>",
  "isHpr": false
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `status` (string)
- `facilityId` (string)
- `professionalHprId` (string)
- `managerHprId` (string)
- `isHpr` (boolean)

## Responses

- `200`: OK
- `404`: Not Found


---

# Link delink existing facility

`POST /relinkOrDelinkProfessionalFromFacility`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/relinkOrDelinkProfessionalFromFacility \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hprId": "<HPR_ID>",
  "facilityId": "<FACILITY_ID>",
  "action": "<ACTION>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `hprId` (string)
- `facilityId` (string)
- `action` (string)

## Responses

- `200`: OK
- `404`: Not Found


---

# Generate mobile OTP 2

`POST /apis/v1/doctors/generate-mobile-otp`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/doctors/generate-mobile-otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hpr_token": "<JWT TOKEN>",
  "officialMobile": "<BASE64 ENCODED STRING>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `hpr_token` (string, required)
- `officialMobile` (string, required)

## Responses

- `200`: OK
  - `status` (string)
  - `txnId` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "status": "success",
  "txnId": "3a9e7f08-39ea-42fc-b3bc-b81a3cc68ab5"
}
```


---

# Send verification email

`POST /apis/v1/doctors/generate-verification-email`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/doctors/generate-verification-email \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "emailAddress": "<ABHA_ADDRESS>.com",
  "otp_type": ""
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `emailAddress` (string)
- `otp_type` (string)

## Responses

- `200`: OK
  - `msg` (string)
  - `status` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "msg": "Mail sent successfully",
  "status": "success",
  "otpLimitExp": null,
  "expTime": null
}
```


---

# Submit the regenerate mobile OTP

`POST /apis/v1/doctors/regenerate-mobile-otp`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/doctors/regenerate-mobile-otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hpr_token": "<JWT TOKEN>",
  "officialMobile": "PFiI0AQJkAKIdLL6ytdJLKFObqXab9rwTvOEPHflksQBkMzIIb8HMDYUzZfN3AUdefedSbb+B4sPwi72lsaaNRkpXygWRF0GWntEwD/WL80JbXaW9DJkwPpDEzQpMYKKT17iCTp7pQer8337NZofO1D1aYiDfEnA9E1HMTyPCGFjvmbcL32hNqGsgpHKYNh4rHXCo4RwP5UQKWDYI1jLZqbWLp0a9GQu9nC1hyP5IR5LRCASzvhiRfrRk+Y660xuDSCvOKb+uUPcN3ZFA==xxxxxxxx"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `hpr_token` (string, required)
- `officialMobile` (string, required)

## Responses

- `200`: OK
- `404`: Not Found


---

# Resend verification email

`POST /apis/v1/doctors/resent-verify-email`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/doctors/resent-verify-email \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "emailAddress": "<ABHA_ADDRESS>.com",
  "otp_type": ""
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `emailAddress` (string)
- `otp_type` (string)

## Responses

- `200`: OK
  - `msg` (string)
  - `status` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "emailAddress": "<ABHA_ADDRESS>.com",
  "otp_type": ""
}
```


---

# Verify email OTP

`POST /apis/v1/doctors/verify-email-otp`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/doctors/verify-email-otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hpr_token": "<JWT TOKEN>",
  "hpr_id": "<HPR_ID>",
  "officialEmail": "<ABHA_ADDRESS>.com",
  "emailOtp": 515999
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `hpr_token` (string)
- `hpr_id` (string)
- `officialEmail` (string)
- `emailOtp` (integer)

## Responses

- `200`: OK
  - `status` (string)
  - `msg` (string)
- `404`: Not Found

Example 200 response. The values are placeholders:

```json
{
  "status": "fail",
  "msg": "Email Verification Failed"
}
```


---

# Verify mobile OTP

`POST /apis/v1/doctors/verify-mobile-otp`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/apis/v1/doctors/verify-mobile-otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hpr_token": "<JWT TOKEN>",
  "txnId": "dd392164-0f4a-4894-8d64-1fce027ee033",
  "otp": "<BASE64 ENCODED STRING>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `txnId` (string)
- `otp` (string)

## Responses

- `200`: OK
- `404`: Not Found


---

# Send OTP if doctor verified

`POST /v1/sendOtpIfDoctorVerified`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/sendOtpIfDoctorVerified \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hprId": "<HPR_ID>",
  "mobileNumber": "<MOBILE_NUMBER>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `hprId` (string)
- `mobileNumber` (string)

## Responses

- `200`: OK
- `404`: Not Found


---

# Verify doctor verification OTP

`POST /v1/verifyDoctorVerificationOtp`

```bash
curl --request POST \
  --url https://apihspsbx.abdm.gov.in/v4/int/v1/verifyDoctorVerificationOtp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "<TXN_ID>",
  "otp": "<OTP>"
}'
```

## Authorization

- `Authorization` (bearer token, required): M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## Body

- `txnId` (string)
- `otp` (string)

## Responses

- `200`: OK
- `404`: Not Found


---

# Milestone 4 (M4): Register Healthcare Professionals and Facilities

Register a healthcare professional on the HPR, onboard a facility to the HFR, and link the facility to its bridges.

## Base URLs

| Purpose           | Environment | Base URL                                |
| ----------------- | ----------- | --------------------------------------- |
| HPR and HFR calls | Sandbox     | `https://apihspsbx.abdm.gov.in/v4/int/` |

The full operation list is in the [M4 API reference](/reference/hiecm-m4).

New to this? Start with [M4 Registry Integration](/docs/hiecm/v3/milestones/m4).


---

# Get the PHR certificate

`GET /abha/api/v3/phr/app/login/public/certificate`

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/public/certificate \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Responses

- `default`: The specification does not describe this body. Send the call with Try it to see what comes back.


---

# Generate access token

`POST /api/hiecm/gateway/v3/sessions`

Generate an access token. When invoked, it facilitates the authentication process by providing a secure token that can be used to access various services and resources within the system. This functionality is essential for ensuring secure and authorised access, enabling users to interact with protected endpoints and perform operations that require authentication. By using this API, users can obtain the necessary tokens to maintain secure sessions and access the system’s features effectively.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/gateway/v3/sessions \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "clientId": "SBX_0000",
  "clientSecret": "0******-***-***-***-a****",
  "grantType": "client_credentials"
}'
```

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `clientId` (string, required): The client ID issued to the integrator by ABDM at registration.
- `clientSecret` (string, required): The client secret issued to the integrator by ABDM along with the client ID.
- `grantType` (string, required): The method used by the client to obtain an access token, e.g. client_credentials. One of: client_credentials.

## Responses

- `202`: Accepted
  - `accessToken` (string)
  - `expiresIn` (integer)
  - `refreshExpiresIn` (integer)
  - `refreshToken` (string)
  - `tokenType` (string)
- `204`: No Content
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `400`: Bad Request
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1015 - Invalid Response. May be returned either bare (`ABDM-1015`) or with a trailing ": " separator (`ABDM-1015: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
- `500`: Internal Server Error
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 202 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "accessToken": "<TOKEN>",
  "expiresIn": 1200,
  "refreshExpiresIn": 1800,
  "refreshToken": "<TOKEN>",
  "tokenType": "bearer"
}
```


---

# Request enrolment OTP

`POST /abha/api/v3/phr/app/enrollment/request/otp`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via Mobile › OTP Request - Mobile
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › OTP Request - ABHA OTP
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-Aadhaar OTP › OTP Request - AADHAR OTP

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/enrollment/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-verify"
  ],
  "loginHint": "abha-number",
  "loginId": "{{encryptedData}}",
  "otpSystem": "aadhaar"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `loginHint` (string, required)
- `loginId` (string, required)
- `otpSystem` (string, required)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "1bda575d-02pd-40be-77e6-1e3efca52a82",
  "message": "OTP is sent to Mobile number ending with ******2425"
}
```


---

# Verify the enrolment OTP

`POST /abha/api/v3/phr/app/enrollment/verify`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via Mobile › OTP Verify - Mobile
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › OTP Verify - ABHA OTP
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-Aadhaar OTP › OTP Verify - AADHAR OTP

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/enrollment/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
      "otpValue": "{{encryptedData}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `authData` (object, required)
- `authData.authMethods` (string[])
- `authData.otp` (object)
- `authData.otp.txnId` (string)
- `authData.otp.otpValue` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.mobile` (string)
  - `accounts.firstName` (string)
  - `accounts.middleName` (string)
  - `accounts.lastName` (string)
  - `accounts.name` (string)
  - `accounts.yearOfBirth` (string)
  - `accounts.dayOfBirth` (string)
  - `accounts.monthOfBirth` (string)
  - `accounts.gender` (string)
  - `accounts.email` (object)
  - `accounts.profilePhoto` (string)
  - `accounts.status` (string)
  - `accounts.stateCode` (string)
  - `accounts.districtCode` (string)
  - `accounts.subDistrictCode` (object)
  - `accounts.villageCode` (object)
  - `accounts.townCode` (object)
  - `accounts.wardCode` (object)
  - `accounts.pincode` (string)
  - `accounts.address` (string)
  - `accounts.kycPhoto` (string)
  - `accounts.stateName` (string)
  - `accounts.districtName` (string)
  - `accounts.subdistrictName` (string)
  - `accounts.villageName` (object)
  - `accounts.townName` (string)
  - `accounts.wardName` (object)
  - `accounts.authMethods` (string[])
  - `accounts.tags` (object)
  - `accounts.kycVerified` (boolean)
  - `accounts.verificationStatus` (string)
  - `accounts.verificationType` (string)
  - `accounts.emailVerified` (object)
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "1cba575d-02cd-40be-90e6-1e2edca88a88",
  "message": "OTP Verified Successfully",
  "authResult": "success",
  "users": [
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "abhaNumber": "XX-XXXX-XXXX-1234",
      "status": "ACTIVE",
      "kycStatus": "VERIFIED"
    }
  ],
  "tokens": {
    "token": "<JWT TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<JWT TOKEN>",
    "refreshExpiresIn": 1296000
  }
}
```


---

# Suggest an ABHA address

`POST /abha/api/v3/phr/app/enrollment/suggestion`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via Mobile › Suggestion API
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › Suggestion API
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-Aadhaar OTP › Suggestion API

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/enrollment/suggestion \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "7f45052a-ac63-48de-92db-c5d8d3d0c92a",
  "firstName": "John",
  "lastName": "Doe",
  "dayOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "yearOfBirth": "<DOB>",
  "email": ""
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `txnId` (string, required)
- `firstName` (string, required)
- `lastName` (string, required)
- `dayOfBirth` (string, required)
- `monthOfBirth` (string, required)
- `yearOfBirth` (string, required)
- `email` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `abhaAddressList` (string[])
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "4765527e-898b-4a62-91ec-be041fbf60f8",
  "abhaAddressList": [
    "<ABHA_ADDRESS>",
    "<ABHA_ADDRESS>",
    "... 1 more of the same shape"
  ]
}
```


---

# Check whether the ABHA address exists

`GET /abha/api/v3/phr/app/enrollment/isExists`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via Mobile › isExists API
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › isExists API Copy
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-Aadhaar OTP › isExists API

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/enrollment/isExists \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Query parameters

- `abhaAddress` (string)

## Responses

- `200`: OK
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
false
```


---

# Enrol ABHA address

`POST /abha/api/v3/phr/app/enrollment/enrol`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via Mobile › Enrol ABHA Address
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › Enrol ABHA Address
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-Aadhaar OTP › Enrol ABHA Address

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/enrollment/enrol \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "phrDetails": {
    "firstName": "John",
    "middleName": "",
    "lastName": "Doe",
    "dayOfBirth": "<DOB>",
    "monthOfBirth": "<DOB>",
    "yearOfBirth": "<DOB>",
    "gender": "M",
    "email": "",
    "mobile": "<ENCRYPTED_MOBILE>",
    "address": "<ADDRESS>",
    "stateName": "Maharashtra",
    "stateCode": "27",
    "districtName": "<ADDRESS>",
    "districtCode": "123",
    "pinCode": "<PINCODE>",
    "abhaAddress": "<ABHA_ADDRESS>",
    "password": "<ENCRYPTED_PASSWORD>"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `txnId` (string, required)
- `phrDetails` (object, required)
- `phrDetails.mobile` (string)
- `phrDetails.firstName` (string)
- `phrDetails.middleName` (string)
- `phrDetails.lastName` (string)
- `phrDetails.yearOfBirth` (string)
- `phrDetails.dayOfBirth` (string)
- `phrDetails.monthOfBirth` (string)
- `phrDetails.gender` (string)
- `phrDetails.email` (string)
- `phrDetails.profilePhoto` (string)
- `phrDetails.address` (string)
- `phrDetails.stateName` (string)
- `phrDetails.stateCode` (string)
- `phrDetails.districtName` (string)
- `phrDetails.districtCode` (string)
- `phrDetails.pinCode` (string)
- `phrDetails.abhaAddress` (string)
- `phrDetails.password` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
  - `phrDetails` (object)
  - `phrDetails.firstName` (string)
  - `phrDetails.middleName` (string)
  - `phrDetails.lastName` (string)
  - `phrDetails.fullName` (string)
  - `phrDetails.dayOfBirth` (string)
  - `phrDetails.monthOfBirth` (string)
  - `phrDetails.yearOfBirth` (string)
  - `phrDetails.dateOfBirth` (string)
  - `phrDetails.gender` (string)
  - `phrDetails.email` (string)
  - `phrDetails.mobile` (string)
  - `phrDetails.address` (string)
  - `phrDetails.stateName` (string)
  - `phrDetails.districtName` (string)
  - `phrDetails.pinCode` (string)
  - `phrDetails.abhaAddress` (string[])
  - `phrDetails.stateCode` (string)
  - `phrDetails.districtCode` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
  - `code` (string)
  - `message` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "6907ebb5-ff71-47f9-8052-6dd5554df5df",
  "message": "ABHA Address Created Successfully",
  "phrDetails": {
    "firstName": "John",
    "middleName": "",
    "lastName": "Doe",
    "fullName": "John Doe",
    "dayOfBirth": "<DOB>",
    "monthOfBirth": "<DOB>",
    "yearOfBirth": "<DOB>",
    "dateOfBirth": "<DOB>",
    "gender": "M",
    "email": "<EMAIL>",
    "mobile": "******1234",
    "address": "<ADDRESS>",
    "stateName": "Maharashtra",
    "districtName": "<ADDRESS>",
    "pinCode": "<PINCODE>",
    "abhaAddress": [
      "<ABHA_ADDRESS>",
      "<ABHA_ADDRESS>",
      "... 1 more of the same shape"
    ],
    "stateCode": "27",
    "districtCode": "123"
  },
  "tokens": {
    "token": "<JWT TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<JWT TOKEN>",
    "refreshExpiresIn": 1296000
  }
}
```


---

# Request enrolment OTP

`POST /abha/api/v3/phr/app/enrollment/request/otp`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via Mobile › OTP Request - Mobile
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › OTP Request - ABHA OTP
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-Aadhaar OTP › OTP Request - AADHAR OTP

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/enrollment/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "mobile-verify"
  ],
  "loginHint": "abha-number",
  "loginId": "{{encryptedData}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `loginHint` (string, required)
- `loginId` (string, required)
- `otpSystem` (string, required)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "1bda575d-02pd-40be-77e6-1e3efca52a82",
  "message": "OTP is sent to Mobile number ending with ******2425"
}
```


---

# Verify the enrolment OTP

`POST /abha/api/v3/phr/app/enrollment/verify`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via Mobile › OTP Verify - Mobile
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › OTP Verify - ABHA OTP
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-Aadhaar OTP › OTP Verify - AADHAR OTP

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/enrollment/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
      "otpValue": "{{encryptedData}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `authData` (object, required)
- `authData.authMethods` (string[])
- `authData.otp` (object)
- `authData.otp.txnId` (string)
- `authData.otp.otpValue` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.mobile` (string)
  - `accounts.firstName` (string)
  - `accounts.middleName` (string)
  - `accounts.lastName` (string)
  - `accounts.name` (string)
  - `accounts.yearOfBirth` (string)
  - `accounts.dayOfBirth` (string)
  - `accounts.monthOfBirth` (string)
  - `accounts.gender` (string)
  - `accounts.email` (object)
  - `accounts.profilePhoto` (string)
  - `accounts.status` (string)
  - `accounts.stateCode` (string)
  - `accounts.districtCode` (string)
  - `accounts.subDistrictCode` (object)
  - `accounts.villageCode` (object)
  - `accounts.townCode` (object)
  - `accounts.wardCode` (object)
  - `accounts.pincode` (string)
  - `accounts.address` (string)
  - `accounts.kycPhoto` (string)
  - `accounts.stateName` (string)
  - `accounts.districtName` (string)
  - `accounts.subdistrictName` (string)
  - `accounts.villageName` (object)
  - `accounts.townName` (string)
  - `accounts.wardName` (object)
  - `accounts.authMethods` (string[])
  - `accounts.tags` (object)
  - `accounts.kycVerified` (boolean)
  - `accounts.verificationStatus` (string)
  - `accounts.verificationType` (string)
  - `accounts.emailVerified` (object)
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "1cba575d-02cd-40be-90e6-1e2edca88a88",
  "message": "OTP Verified Successfully",
  "authResult": "success",
  "users": [
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "abhaNumber": "XX-XXXX-XXXX-1234",
      "status": "ACTIVE",
      "kycStatus": "VERIFIED"
    }
  ],
  "tokens": {
    "token": "<JWT TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<JWT TOKEN>",
    "refreshExpiresIn": 1296000
  }
}
```


---

# Suggest an ABHA address

`POST /abha/api/v3/phr/app/enrollment/suggestion`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via Mobile › Suggestion API
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › Suggestion API
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-Aadhaar OTP › Suggestion API

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/enrollment/suggestion \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "firstName": "John",
  "lastName": "Doe",
  "dayOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "yearOfBirth": "<DOB>",
  "email": ""
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `txnId` (string, required)
- `firstName` (string, required)
- `lastName` (string, required)
- `dayOfBirth` (string, required)
- `monthOfBirth` (string, required)
- `yearOfBirth` (string, required)
- `email` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `abhaAddressList` (string[])
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "4765527e-898b-4a62-91ec-be041fbf60f8",
  "abhaAddressList": [
    "<ABHA_ADDRESS>",
    "<ABHA_ADDRESS>",
    "... 1 more of the same shape"
  ]
}
```


---

# Check whether the ABHA address exists

`GET /abha/api/v3/phr/app/enrollment/isExists`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via Mobile › isExists API
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › isExists API Copy
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-Aadhaar OTP › isExists API

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/enrollment/isExists \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Query parameters

- `abhaAddress` (string)

## Responses

- `200`: OK
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
false
```


---

# Enrol ABHA address

`POST /abha/api/v3/phr/app/enrollment/enrol`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via Mobile › Enrol ABHA Address
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › Enrol ABHA Address
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-Aadhaar OTP › Enrol ABHA Address

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/enrollment/enrol \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "phrDetails": {
    "firstName": "John",
    "middleName": "",
    "lastName": "Doe",
    "dayOfBirth": "<DOB>",
    "monthOfBirth": "<DOB>",
    "yearOfBirth": "<DOB>",
    "gender": "M",
    "email": "",
    "mobile": "<ENCRYPTED_MOBILE>",
    "address": "<ADDRESS>",
    "stateName": "Maharashtra",
    "stateCode": "27",
    "districtName": "<ADDRESS>",
    "districtCode": "123",
    "pinCode": "<PINCODE>",
    "abhaAddress": "<ABHA_ADDRESS>",
    "password": "<ENCRYPTED_PASSWORD>"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `txnId` (string, required)
- `phrDetails` (object, required)
- `phrDetails.mobile` (string)
- `phrDetails.firstName` (string)
- `phrDetails.middleName` (string)
- `phrDetails.lastName` (string)
- `phrDetails.yearOfBirth` (string)
- `phrDetails.dayOfBirth` (string)
- `phrDetails.monthOfBirth` (string)
- `phrDetails.gender` (string)
- `phrDetails.email` (string)
- `phrDetails.profilePhoto` (string)
- `phrDetails.address` (string)
- `phrDetails.stateName` (string)
- `phrDetails.stateCode` (string)
- `phrDetails.districtName` (string)
- `phrDetails.districtCode` (string)
- `phrDetails.pinCode` (string)
- `phrDetails.abhaAddress` (string)
- `phrDetails.password` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
  - `phrDetails` (object)
  - `phrDetails.firstName` (string)
  - `phrDetails.middleName` (string)
  - `phrDetails.lastName` (string)
  - `phrDetails.fullName` (string)
  - `phrDetails.dayOfBirth` (string)
  - `phrDetails.monthOfBirth` (string)
  - `phrDetails.yearOfBirth` (string)
  - `phrDetails.dateOfBirth` (string)
  - `phrDetails.gender` (string)
  - `phrDetails.email` (string)
  - `phrDetails.mobile` (string)
  - `phrDetails.address` (string)
  - `phrDetails.stateName` (string)
  - `phrDetails.districtName` (string)
  - `phrDetails.pinCode` (string)
  - `phrDetails.abhaAddress` (string[])
  - `phrDetails.stateCode` (string)
  - `phrDetails.districtCode` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
  - `code` (string)
  - `message` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "6907ebb5-ff71-47f9-8052-6dd5554df5df",
  "message": "ABHA Address Created Successfully",
  "phrDetails": {
    "firstName": "John",
    "middleName": "",
    "lastName": "Doe",
    "fullName": "John Doe",
    "dayOfBirth": "<DOB>",
    "monthOfBirth": "<DOB>",
    "yearOfBirth": "<DOB>",
    "dateOfBirth": "<DOB>",
    "gender": "M",
    "email": "<EMAIL>",
    "mobile": "******1234",
    "address": "<ADDRESS>",
    "stateName": "Maharashtra",
    "districtName": "<ADDRESS>",
    "pinCode": "<PINCODE>",
    "abhaAddress": [
      "<ABHA_ADDRESS>",
      "<ABHA_ADDRESS>",
      "... 1 more of the same shape"
    ],
    "stateCode": "27",
    "districtCode": "123"
  },
  "tokens": {
    "token": "<JWT TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<JWT TOKEN>",
    "refreshExpiresIn": 1296000
  }
}
```


---

# Request enrolment OTP

`POST /abha/api/v3/phr/app/enrollment/request/otp`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via Mobile › OTP Request - Mobile
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › OTP Request - ABHA OTP
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-Aadhaar OTP › OTP Request - AADHAR OTP

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/enrollment/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-address-enroll",
    "mobile-verify"
  ],
  "loginHint": "mobile-number",
  "loginId": "{{encryptedData}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `loginHint` (string, required)
- `loginId` (string, required)
- `otpSystem` (string, required)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "1bda575d-02pd-40be-77e6-1e3efca52a82",
  "message": "OTP is sent to Mobile number ending with ******2425"
}
```


---

# Verify the enrolment OTP

`POST /abha/api/v3/phr/app/enrollment/verify`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via Mobile › OTP Verify - Mobile
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › OTP Verify - ABHA OTP
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-Aadhaar OTP › OTP Verify - AADHAR OTP

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/enrollment/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-address-enroll",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
      "otpValue": "{{encryptedData}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `authData` (object, required)
- `authData.authMethods` (string[])
- `authData.otp` (object)
- `authData.otp.txnId` (string)
- `authData.otp.otpValue` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.mobile` (string)
  - `accounts.firstName` (string)
  - `accounts.middleName` (string)
  - `accounts.lastName` (string)
  - `accounts.name` (string)
  - `accounts.yearOfBirth` (string)
  - `accounts.dayOfBirth` (string)
  - `accounts.monthOfBirth` (string)
  - `accounts.gender` (string)
  - `accounts.email` (object)
  - `accounts.profilePhoto` (string)
  - `accounts.status` (string)
  - `accounts.stateCode` (string)
  - `accounts.districtCode` (string)
  - `accounts.subDistrictCode` (object)
  - `accounts.villageCode` (object)
  - `accounts.townCode` (object)
  - `accounts.wardCode` (object)
  - `accounts.pincode` (string)
  - `accounts.address` (string)
  - `accounts.kycPhoto` (string)
  - `accounts.stateName` (string)
  - `accounts.districtName` (string)
  - `accounts.subdistrictName` (string)
  - `accounts.villageName` (object)
  - `accounts.townName` (string)
  - `accounts.wardName` (object)
  - `accounts.authMethods` (string[])
  - `accounts.tags` (object)
  - `accounts.kycVerified` (boolean)
  - `accounts.verificationStatus` (string)
  - `accounts.verificationType` (string)
  - `accounts.emailVerified` (object)
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "1cba575d-02cd-40be-90e6-1e2edca88a88",
  "message": "OTP Verified Successfully",
  "authResult": "success",
  "users": [
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "abhaNumber": "XX-XXXX-XXXX-1234",
      "status": "ACTIVE",
      "kycStatus": "VERIFIED"
    }
  ],
  "tokens": {
    "token": "<JWT TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<JWT TOKEN>",
    "refreshExpiresIn": 1296000
  }
}
```


---

# Suggest an ABHA address

`POST /abha/api/v3/phr/app/enrollment/suggestion`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via Mobile › Suggestion API
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › Suggestion API
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-Aadhaar OTP › Suggestion API

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/enrollment/suggestion \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "ee10d1c7-e25f-40e0-a3a1-df4c1dda02211",
  "firstName": "John",
  "lastName": "Doe",
  "dayOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "yearOfBirth": "<DOB>",
  "email": ""
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `txnId` (string, required)
- `firstName` (string, required)
- `lastName` (string, required)
- `dayOfBirth` (string, required)
- `monthOfBirth` (string, required)
- `yearOfBirth` (string, required)
- `email` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `abhaAddressList` (string[])
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "4765527e-898b-4a62-91ec-be041fbf60f8",
  "abhaAddressList": [
    "<ABHA_ADDRESS>",
    "<ABHA_ADDRESS>",
    "... 1 more of the same shape"
  ]
}
```


---

# Check whether the ABHA address exists

`GET /abha/api/v3/phr/app/enrollment/isExists`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via Mobile › isExists API
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › isExists API Copy
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-Aadhaar OTP › isExists API

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/enrollment/isExists \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Query parameters

- `abhaAddress` (string)

## Responses

- `200`: OK
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
false
```


---

# Enrol ABHA address

`POST /abha/api/v3/phr/app/enrollment/enrol`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via Mobile › Enrol ABHA Address
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › Enrol ABHA Address
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-Aadhaar OTP › Enrol ABHA Address

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/enrollment/enrol \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "27d444b7-2a3d-46d8-bf67-e5590b6c46b6",
  "phrDetails": {
    "mobile": "<ENCRYPTED_MOBILE>",
    "firstName": "John",
    "middleName": "",
    "lastName": "Doe",
    "yearOfBirth": "<DOB>",
    "dayOfBirth": "",
    "monthOfBirth": "<DOB>",
    "gender": "M",
    "email": "",
    "profilePhoto": "",
    "address": "<ADDRESS>",
    "stateName": "Maharashtra",
    "stateCode": "27",
    "districtName": "<ADDRESS>",
    "districtCode": "123",
    "pinCode": "<PINCODE>",
    "abhaAddress": "<ABHA_ADDRESS>",
    "password": "<ENCRYPTED_PASSWORD>"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `txnId` (string, required)
- `phrDetails` (object, required)
- `phrDetails.mobile` (string)
- `phrDetails.firstName` (string)
- `phrDetails.middleName` (string)
- `phrDetails.lastName` (string)
- `phrDetails.yearOfBirth` (string)
- `phrDetails.dayOfBirth` (string)
- `phrDetails.monthOfBirth` (string)
- `phrDetails.gender` (string)
- `phrDetails.email` (string)
- `phrDetails.profilePhoto` (string)
- `phrDetails.address` (string)
- `phrDetails.stateName` (string)
- `phrDetails.stateCode` (string)
- `phrDetails.districtName` (string)
- `phrDetails.districtCode` (string)
- `phrDetails.pinCode` (string)
- `phrDetails.abhaAddress` (string)
- `phrDetails.password` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
  - `phrDetails` (object)
  - `phrDetails.firstName` (string)
  - `phrDetails.middleName` (string)
  - `phrDetails.lastName` (string)
  - `phrDetails.fullName` (string)
  - `phrDetails.dayOfBirth` (string)
  - `phrDetails.monthOfBirth` (string)
  - `phrDetails.yearOfBirth` (string)
  - `phrDetails.dateOfBirth` (string)
  - `phrDetails.gender` (string)
  - `phrDetails.email` (string)
  - `phrDetails.mobile` (string)
  - `phrDetails.address` (string)
  - `phrDetails.stateName` (string)
  - `phrDetails.districtName` (string)
  - `phrDetails.pinCode` (string)
  - `phrDetails.abhaAddress` (string[])
  - `phrDetails.stateCode` (string)
  - `phrDetails.districtCode` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
  - `code` (string)
  - `message` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "6907ebb5-ff71-47f9-8052-6dd5554df5df",
  "message": "ABHA Address Created Successfully",
  "phrDetails": {
    "firstName": "John",
    "middleName": "",
    "lastName": "Doe",
    "fullName": "John Doe",
    "dayOfBirth": "<DOB>",
    "monthOfBirth": "<DOB>",
    "yearOfBirth": "<DOB>",
    "dateOfBirth": "<DOB>",
    "gender": "M",
    "email": "<EMAIL>",
    "mobile": "******1234",
    "address": "<ADDRESS>",
    "stateName": "Maharashtra",
    "districtName": "<ADDRESS>",
    "pinCode": "<PINCODE>",
    "abhaAddress": [
      "<ABHA_ADDRESS>",
      "<ABHA_ADDRESS>",
      "... 1 more of the same shape"
    ],
    "stateCode": "27",
    "districtCode": "123"
  },
  "tokens": {
    "token": "<JWT TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<JWT TOKEN>",
    "refreshExpiresIn": 1296000
  }
}
```


---

# Send Aadhaar OTP for ABHA enrolment

`POST /abha/api/v3/enrollment/request/otp`

Starts ABHA creation with Aadhaar OTP. UIDAI sends an OTP to the mobile number linked with the Aadhaar number. Use the `txnId` from the response in *Create ABHA - verify Aadhaar OTP*.

**Endpoint:** `POST /abha/api/v3/enrollment/request/otp`

**Flow:** **Create ABHA - Aadhaar OTP** - step 1 of 8
- Previous: none (first call of this flow)
- Next: *Create ABHA - verify Aadhaar OTP*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `txnId` | string | no | Transaction ID returned by the previous step of this flow. |
| `scope` | `["ABHA-enrol"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"Aadhaar"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"Aadhaar"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

> **Note:** `txnId` is optional here. Leave it empty on the first call, or send a previous `txnId` to resend the OTP.

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "{{txnId}}",
  "scope": [
    "abha-enrol"
  ],
  "loginHint": "aadhaar",
  "loginId": "{{encrypted aadhaar number}}",
  "otpSystem": "aadhaar"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `txnId` (string): Transaction ID returned by the previous step of this flow.
- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: aadhaar.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: aadhaar.

## Responses

- `200`: Success: ABHA enrolment via Aadhaar-positive flow; ABHA Creation via Aadhaar OTP-REQUEST OTP FOR AADHAAR AUTHENTICATION
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): ABHA enrolment via Aadhaar-Invalid scope; ABHA enrolment via Aadhaar-Invalid LoginId; ABHA enrolment via Aadhaar-Invalid Login Hint; ABHA Creation via Aadhaar OTP-Invalid scope; ABHA Creation via Aadhaar OTP-Invalid Login Hint
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): ABHA enrolment via Aadhaar-Invalid access token; ABHA Creation via Aadhaar OTP-Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
  "message": "OTP sent to Aadhaar registered mobile number ending with ******0903"
}
```


---

# Create ABHA - verify Aadhaar OTP

`POST /abha/api/v3/enrollment/enrol/byAadhaar`

Verifies the Aadhaar OTP and creates the ABHA number, or returns the existing ABHA if one is already linked to the Aadhaar. The response contains the ABHA profile, `tokens.token` (user X-token) and a refresh token. `mobile` is the number to link with the ABHA. If it is not the Aadhaar-linked mobile, verify it next with *After ABHA creation - send OTP to verify mobile (optional)*.

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/byAadhaar`

**Flow:** **Create ABHA - Aadhaar OTP** - step 2 of 8
- Previous: *Send Aadhaar OTP for ABHA enrolment*
- Next: *After ABHA creation - send OTP to verify mobile (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |
| REQUEST-ID | yes | Unique UUID for every request. |
| Benefit-Name | no | **Applicable for user who is enrolling via Benefit Program.** |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |
| `authData.otp.mobile` | string | no | Mobile number to be linked with the ABHA (plain, 10 digits). |
| `consent` | object | yes | Consent captured from the user for ABHA enrolment. |
| `consent.code` | string | yes | Consent code. Use `ABHA-enrollment`. |
| `consent.version` | string | yes | Consent version. Use `1.4`. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/byAadhaar \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'BENEFIT_NAME: {{Benefit Name}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted otp}}",
      "mobile": "{{mobile number}}"
    }
  },
  "consent": {
    "code": "abha-enrollment",
    "version": "1.4"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `BENEFIT_NAME` (string): **Applicable for user who is enrolling via Benefit Program.**

## Body

- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.
- `authData.otp.mobile` (string): Mobile number to be linked with the ABHA (plain, 10 digits).
- `consent` (object, required): Consent captured from the user for ABHA enrolment.
- `consent.code` (string, required): Consent code. Use `abha-enrollment`.
- `consent.version` (string, required): Consent version. Use `1.4`.

## Responses

- `200`: Success: Create ABHA by verifying OTP - Positive flow
  - `message` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `ABHAProfile` (object)
  - `ABHAProfile.firstName` (string)
  - `ABHAProfile.middleName` (string)
  - `ABHAProfile.lastName` (string)
  - `ABHAProfile.dob` (string)
  - `ABHAProfile.gender` (string)
  - `ABHAProfile.mobile` (string)
  - `ABHAProfile.phrAddress` (string[])
  - `ABHAProfile.districtCode` (string)
  - `ABHAProfile.stateCode` (string)
  - `ABHAProfile.abhaType` (string)
  - `ABHAProfile.stateName` (string)
  - `ABHAProfile.districtName` (string)
  - `ABHAProfile.ABHANumber` (string)
  - `ABHAProfile.abhaStatus` (string)
  - `isNew` (boolean)
- `400`: Bad Request (request validation failed): Create ABHA by verifying OTP-Invalid Transaction Id; Create ABHA by verifying OTP-Invalid authMethod; Create ABHA by verifying OTP-Invalid Mobile Number
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Benefit Name (generic)
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `message` (string)
  - `timestamp` (string)
- `422`: Unprocessable Entity (business rule or UIDAI failure): Create ABHA by verifying OTP- Invalid OTP value
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "message": "This account already exist",
  "txnId": "b89ec10d-71fa-4280-83b3-1fedad66b5f5",
  "tokens": {
    "token": "<TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<TOKEN>",
    "refreshExpiresIn": 1296000
  },
  "ABHAProfile": {
    "firstName": "Username",
    "middleName": "<NAME>",
    "lastName": "<NAME>",
    "dob": "<DOB>",
    "gender": "M",
    "photo": "<BASE64_PHOTO>",
    "mobile": "******0903",
    "phrAddress": [
      "<ABHA_ADDRESS>"
    ],
    "address": "<ADDRESS>",
    "districtCode": "478",
    "stateCode": "27",
    "pinCode": "<PINCODE>",
    "abhaType": "STANDARD",
    "stateName": "MAHARASHTRA",
    "districtName": "<ADDRESS>",
    "ABHANumber": "<ABHA_NUMBER>",
    "abhaStatus": "ACTIVE"
  },
  "isNew": false
}
```


---

# After ABHA creation - send OTP to verify mobile (optional)

`POST /abha/api/v3/enrollment/request/otp`

Optional, called after the ABHA is created. Needed only when the `mobile` sent in the create-ABHA call is **not** the Aadhaar-linked mobile. ABDM sends an OTP to that mobile number so it can be linked to the ABHA. Send the `txnId` from the ABHA creation response.

**Endpoint:** `POST /abha/api/v3/enrollment/request/otp`

**Flow:** **Create ABHA - Aadhaar OTP** - step 3 of 8
- Previous: *Create ABHA - verify Aadhaar OTP*
- Next: *After ABHA creation - verify mobile OTP (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `scope` | `["ABHA-enrol", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `loginHint` | `"mobile"` | yes | Type of identifier sent in `loginId`. |
| `loginId` | string | yes | Identifier value, RSA-encrypted with the ABHA public certificate. |
| `otpSystem` | `"ABDM"` | yes | System that generates and delivers the OTP (`Aadhaar` = UIDAI, `ABDM` = ABDM). |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "{{txnId}}",
  "scope": [
    "abha-enrol",
    "mobile-verify"
  ],
  "loginHint": "mobile",
  "loginId": "{{encrypted mobileNumber}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `loginHint` (string, required): Type of identifier sent in `loginId`. One of: mobile.
- `loginId` (string, required): Identifier value, RSA-encrypted with the ABHA public certificate.
- `otpSystem` (string, required): System that generates and delivers the OTP (`aadhaar` = UIDAI, `abdm` = ABDM). One of: abdm.

## Responses

- `200`: Success: Mobile Update - Send OTP- positive flow
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request (request validation failed): Mobile Update - Send OTP-Invalid Scope; Mobile Update - Send OTP-Invalid LoginId; Mobile Update - Send OTP-Invalid Login Hint
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `scope` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Mobile Update - Send OTP-Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "37d8d312-35a0-41e7-a6e4-107h6b18a5fa",
  "message": "OTP sent to mobile number ending with ******0903"
}
```


---

# After ABHA creation - verify mobile OTP (optional)

`POST /abha/api/v3/enrollment/auth/byAbdm`

Verifies the OTP sent by *After ABHA creation - send OTP to verify mobile (optional)* and links the mobile number to the newly created ABHA.

**Endpoint:** `POST /abha/api/v3/enrollment/auth/byAbdm`

**Flow:** **Create ABHA - Aadhaar OTP** - step 4 of 8
- Previous: *After ABHA creation - send OTP to verify mobile (optional)*
- Next: *After ABHA creation - send OTP to verify email (optional)*

**Headers** (plus `Authorization: Bearer <gateway token>`):

| Header | Required | Description |
|---|---|---|
| REQUEST-ID | yes | Unique UUID for every request. |
| TIMESTAMP | yes | Current UTC timestamp in ISO-8601 format. |

**Request body for this use case:**

| Field | Value / Type | Required | Description |
|---|---|---|---|
| `scope` | `["ABHA-enrol", "mobile-verify"]` | yes | Scope that selects this use case. Send exactly the values listed for this API. |
| `authData` | object | yes | Authentication payload for this use case. |
| `authData.authMethods` | `["OTP"]` | yes | Authentication method used in this step. |
| `authData.otp` | object | yes | OTP authentication block. |
| `authData.otp.txnId` | string | yes | Transaction ID returned by the previous step of this flow. |
| `authData.otp.otpValue` | string | yes | OTP received by the user, RSA-encrypted. |

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/auth/byAbdm \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-enrol",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "{{txnId}}",
      "otpValue": "{{encrypted otp}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `scope` (string[], required): Scope that selects this use case. Send exactly the values listed for this API.
- `authData` (object, required): Authentication payload for this use case.
- `authData.authMethods` (string[], required): Authentication method used in this step.
- `authData.otp` (object, required): OTP authentication block.
- `authData.otp.txnId` (string, required): Transaction ID returned by the previous step of this flow.
- `authData.otp.otpValue` (string, required): OTP received by the user, RSA-encrypted.

## Responses

- `200`: Success: Mobile Update - Verify OTP-positive flow; Mobile Update - Verify OTP-OTP EXPIRED
  - `txnId` (string)
  - `authResult` (string)
  - `message` (string)
  - `accounts` (object[])
- `400`: Bad Request (request validation failed): Mobile Update - Verify OTP; Invalid Transaction Id; Invalid Scope; Invalid AuthMethod
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid access token
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error: Mobile Update - Verify OTP-Invalid access token
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "authResult": "success",
  "message": "Mobile number is now successfully linked to your Account",
  "accounts": [
    {
      "ABHANumber": "<ABHA_NUMBER>"
    }
  ]
}
```


---

# Submit the email verification link

`POST /abha/api/v3/profile/account/request/emailVerificationLink`

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/request/emailVerificationLink \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-token: Bearer <JWT TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-profile",
    "email-link-verify"
  ],
  "loginHint": "email",
  "loginId": "{{encrypted email}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.
- `X-token` (string, required): The user token from a login or enrolment response, sent with a `Bearer ` prefix. It acts for that ABHA holder.

## Body

- `scope` (string[])
- `loginHint` (string)
- `loginId` (string)
- `otpSystem` (string)

## Responses

- `default`: The specification does not describe this body. Send the call with Try it to see what comes back.


---

# After ABHA creation - get ABHA address suggestions

`GET /abha/api/v3/enrollment/enrol/suggestion`

**Endpoint:** `GET /abha/api/v3/enrollment/enrol/suggestion`

**Flow:** **Create ABHA - Aadhaar OTP** - step 7 of 8
- Previous: *After ABHA creation - verify email OTP (optional)*
- Next: *After ABHA creation - create ABHA address*

---

This API endpoint is used to provide suggestions for ABHA addresses based on the user’s personal information. It helps users find suitable ABHA addresses by generating a list of suggestions. This is particularly useful during the ABHA enrolment process to ensure that users can choose an appropriate and unique ABHA address.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/suggestion \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'TRANSACTION_ID: {{txnId}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `TRANSACTION_ID` (string, required): Transaction ID from the ABHA creation response.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it refers to the successful operation of the Suggestion API, suggestions for ABHA addresses based on the user’s personal information.
  - `txnId` (string)
  - `abhaAddressList` (string[])
- `400`: The 400 response code indicates a bad request. In this context, it refers to various errors encountered during the operation of the Suggestion API. **Types of Suggestion API Errors:** **Abha Address - Invalid Transaction Id:** This error occurs when the transaction ID provided in the request is invalid. The transaction ID is essential for tracking the request and ensuring that the correct information is processed.. **Abha Address - Invalid Preferred Flag:** This error occurs when the preferred flag provided in the request is invalid. The preferred flag indicates the user’s preference for the suggested ABHA address.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `txnId` (string)
  - `timestamp` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, This error occurs when the transaction ID provided in the request is invalid. The transaction ID is essential for tracking the request and ensuring that the correct information is processed. An invalid transaction ID means the server cannot verify the request, leading to a failure in generating ABHA address suggestions.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "abhaAddressList": [
    "<ABHA_ADDRESS>",
    "<ABHA_ADDRESS>",
    "... 11 more of the same shape"
  ]
}
```


---

# After ABHA creation - create ABHA address

`POST /abha/api/v3/enrollment/enrol/abha-address`

**Endpoint:** `POST /abha/api/v3/enrollment/enrol/abha-address`

**Flow:** **Create ABHA - Aadhaar OTP** - step 8 of 8
- Previous: *After ABHA creation - get ABHA address suggestions*
- Next: none (last call of this flow)

---

This API endpoint is used to enrol a new ABHA address. It allows users to create a unique ABHA address that can be used for accessing and managing their health records. The endpoint ensures that the provided ABHA address is unique and valid..

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/enrollment/enrol/abha-address \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "{{txnId}}",
  "abhaAddress": "{{ABHA Address}}",
  "preferred": 1
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Body

- `txnId` (string, required): The transaction ID returned by the previous call in this flow.
- `abhaAddress` (string, required): The ABHA address chosen for the account, without the @ suffix.
- `preferred` (integer, required): 1 to make this the preferred ABHA address of the account, 0 otherwise.

## Responses

- `200`: The 200 response code indicates a successful request. In this context, it refers to the successful operation of the Enroll ABHA Address API.
  - `txnId` (string)
  - `abhaAddress` (string)
  - `preferred` (integer)
- `400`: The 400 response code indicates a bad request. In this context, it refers to various errors encountered during the operation of the Suggestion API. **Types of Suggestion API Errors:** **Invalid Preferred Flag:** This error occurs when the transaction ID provided in the request is invalid. The transaction ID is essential for tracking the request and ensuring that the correct information is processed. An invalid transaction ID means the server cannot verify the request, leading to a failure in enrolling the ABHA address. . **Invalid Transaction Id:** This error occurs when the preferred flag provided in the request is invalid. The preferred flag indicates the user’s preference for the suggested ABHA address. An invalid preferred flag means the server cannot process the user’s preference correctly, leading to a failure in enrolling the ABHA address.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `preferred` (string)
  - `timestamp` (string)
- `401`: The 401 response code indicates an unauthorized request. In this context, it refers to the lack of proper authentication during the operation of the Invalid Credentials.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: **Internal Server Error** An Internal Server Error (500) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "23acf181-339d-4771-b532-5c5df4a28d19",
  "healthIdNumber": "<ABHA_NUMBER>",
  "preferredAbhaAddress": "<ABHA_ADDRESS>"
}
```


---

# Get ABHA profile

`GET /abha/api/v3/profile/account`

**Endpoint:** `GET /abha/api/v3/profile/account`

**Flow:** **ABHA Card & Profile** - independent API; call the one that fits your identifier / modality.

---

This API endpoint is used to manage ABHA (Ayushman Bharat Health Account) profiles. It allows users to fetch the user profile, ensuring that their details are accurate and up-to-date. This is essential for maintaining the integrity and security of the user’s health records.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: The account information was successfully retrieved or updated.
  - `ABHANumber` (string)
  - `preferredAbhaAddress` (string)
  - `mobile` (string)
  - `firstName` (string)
  - `middleName` (string)
  - `lastName` (string)
  - `name` (string)
  - `yearOfBirth` (string)
  - `dayOfBirth` (string)
  - `monthOfBirth` (string)
  - `gender` (string)
  - `profilePhoto` (string)
  - `status` (string)
  - `stateCode` (string)
  - `districtCode` (string)
  - `pincode` (string)
  - `address` (string)
  - `kycPhoto` (string)
  - `stateName` (string)
  - `districtName` (string)
  - `subdistrictName` (string)
  - `authMethods` (string[])
  - `tags` (object)
  - `kycVerified` (boolean)
  - `verificationStatus` (string)
  - `verificationType` (string)
  - `localizedDetails` (object)
  - `localizedDetails.name` (string)
  - `localizedDetails.stateName` (string)
  - `localizedDetails.districtName` (string)
  - `localizedDetails.villageName` (string)
  - `localizedDetails.townName` (string)
  - `localizedDetails.gender` (string)
  - `localizedDetails.localizedLabels` (object)
  - `localizedDetails.localizedLabels.name` (string)
  - `localizedDetails.localizedLabels.abhaNumber` (string)
  - `localizedDetails.localizedLabels.abhaAddress` (string)
  - `localizedDetails.localizedLabels.gender` (string)
  - `localizedDetails.localizedLabels.dob` (string)
  - `localizedDetails.localizedLabels.mobile` (string)
  - `createdDate` (string)
- `400`: Indicates various errors encountered during the account management process, such as invalid identifiers or missing parameters.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `message` (string)
  - `timestamp` (string)
- `401`: The request was unauthorized. This can occur due to invalid credentials or token.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors

Example 200 response. The values are placeholders:

```json
{
  "ABHANumber": "<ABHA_NUMBER>",
  "preferredAbhaAddress": "<ABHA_ADDRESS>",
  "mobile": "******0903",
  "firstName": "Username",
  "middleName": "<NAME>",
  "lastName": "<NAME>",
  "name": "<NAME>",
  "yearOfBirth": "<DOB>",
  "dayOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "gender": "M",
  "profilePhoto": "<BASE64_PHOTO>",
  "status": "ACTIVE",
  "stateCode": "27",
  "districtCode": "478",
  "pincode": "<PINCODE>",
  "address": "<ADDRESS>",
  "kycPhoto": "<BASE64_PHOTO>",
  "stateName": "MAHARASHTRA",
  "districtName": "<ADDRESS>",
  "subdistrictName": "<ADDRESS>",
  "authMethods": [
    "MOBILE_OTP",
    "AADHAAR_BIO",
    "... 3 more of the same shape"
  ],
  "tags": {},
  "kycVerified": true,
  "verificationStatus": "VERIFIED",
  "verificationType": "AADHAAR",
  "localizedDetails": {
    "name": "<NAME>",
    "stateName": "महाराष्ट्र",
    "districtName": "<ADDRESS>",
    "villageName": "<ADDRESS>",
    "townName": "<ADDRESS>",
    "gender": "पुरुष",
    "localizedLabels": {
      "name": "नाव",
      "abhaNumber": "आभा क्रमांक",
      "abhaAddress": "आभा पत्ता",
      "gender": "लिंग",
      "dob": "जन्मतारीख",
      "mobile": "मोबाईल"
    }
  },
  "createdDate": "07-05-2024"
}
```


---

# Retrieve ABHA card image

`GET /abha/api/v3/profile/account/abha-card`

**Endpoint:** `GET /abha/api/v3/profile/account/abha-card`

**Flow:** **ABHA Card & Profile** - independent API; call the one that fits your identifier / modality.

---

This API endpoint is used to retrieve the ABHA card image. It requires valid credentials and headers for authentication.

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/profile/account/abha-card \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer {{X-token}}' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): User token (`Bearer <token>`) received after ABHA creation / login.
- `REQUEST-ID` (string, required): Unique UUID for every request.
- `TIMESTAMP` (string, required): Current UTC timestamp in ISO-8601 format.

## Responses

- `200`: Successfully retrieved ABHA card image.
- `400`: Invalid X-token.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors
  - `message` (string)
  - `timestamp` (string)
- `401`: Unauthorized.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `500`: Internal Server Error.
  See Error codes for this module: /docs/hiecm/v3/api/m1/errors


---

# Login request OTP

`POST /abha/api/v3/phr/app/login/request/otp`

Flows:
- P1-Registration-login › P1 - PHR Login › P1 - Login via Mobile Number › OTP Request - Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Mobile OTP › OTP Request - ABHAADDRES Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-Aadhaar OTP › OTP Request - AADHAR OTP
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-ABHA OTP › OTP Request - ABHA OTP
- P1-Registration-login › P1 - PHR Login › P1 - Login via Aadhaar- OTP › new OTP Request- Aadhaar

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-verify",
    "aadhaar-otp-verify"
  ],
  "loginHint": "aadhaar",
  "loginId": "<ENCRYPTED_LOGIN_ID>",
  "otpSystem": "aadhaar"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `loginHint` (string, required)
- `loginId` (string, required)
- `otpSystem` (string, required)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "b81a963d-4b97-48b4-9f9f-acf9f13afab7",
  "message": "OTP is sent to Mobile number ending with ******2425"
}
```


---

# Login PHR verify

`POST /abha/api/v3/phr/app/login/verify`

Flows:
- P1-Registration-login › P1 - PHR Login › P1 - Login via Mobile Number › Login OTP Verify - Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Mobile OTP › Login OTP Verify - ABHAADDRES Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-Aadhaar OTP › Login OTP Verify - AADHAR
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-ABHA OTP › Login OTP Verify - ABHA
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Password › Login Verify - Password
- P1-Registration-login › P1 - PHR Login › P1 - Login via Aadhaar- OTP › new OTP verify- Aadhaar

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-verify",
    "aadhaar-otp-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "c51ad4d8-ae92-4509-8fb9-b91dea948492",
      "otpValue": "<ENCRYPTED_OTP_VALUE>"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `authData` (object, required)
- `authData.authMethods` (string[])
- `authData.otp` (object)
- `authData.otp.txnId` (string)
- `authData.otp.otpValue` (string)
- `authData.password` (object)
- `authData.password.abhaAddress` (string)
- `authData.password.password` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `tokens.switchProfileEnabled` (boolean)
  - `accounts` (object[])
  - `accounts.mobile` (string)
  - `accounts.firstName` (string)
  - `accounts.middleName` (string)
  - `accounts.lastName` (string)
  - `accounts.name` (string)
  - `accounts.yearOfBirth` (string)
  - `accounts.dayOfBirth` (string)
  - `accounts.monthOfBirth` (string)
  - `accounts.gender` (string)
  - `accounts.email` (object)
  - `accounts.profilePhoto` (string)
  - `accounts.status` (string)
  - `accounts.stateCode` (string)
  - `accounts.districtCode` (string)
  - `accounts.subDistrictCode` (object)
  - `accounts.villageCode` (object)
  - `accounts.townCode` (object)
  - `accounts.wardCode` (object)
  - `accounts.pincode` (string)
  - `accounts.address` (string)
  - `accounts.kycPhoto` (string)
  - `accounts.stateName` (string)
  - `accounts.districtName` (string)
  - `accounts.subdistrictName` (string)
  - `accounts.villageName` (object)
  - `accounts.townName` (string)
  - `accounts.wardName` (object)
  - `accounts.authMethods` (string[])
  - `accounts.tags` (object)
  - `accounts.kycVerified` (boolean)
  - `accounts.verificationStatus` (string)
  - `accounts.verificationType` (string)
  - `accounts.emailVerified` (object)
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `preferredAbhaAddress` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "b81a963d-4b97-48b4-9f9f-acf9f13afab7",
  "message": "OTP verified successfully",
  "authResult": "success",
  "users": [
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "abhaNumber": "<ABHA_NUMBER>",
      "status": "ACTIVE",
      "kycStatus": "VERIFIED"
    },
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "abhaNumber": "<ABHA_NUMBER>",
      "status": "ACTIVE",
      "kycStatus": "PENDING"
    },
    "... 1 more of the same shape"
  ],
  "tokens": {
    "token": "<JWT TOKEN>",
    "expiresIn": 1800,
    "refreshToken": null,
    "refreshExpiresIn": null
  }
}
```


---

# Verify User, verify user

`POST /abha/api/v3/phr/app/login/verify/user`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › Verify User
- P1-Registration-login › P1 - PHR Login › P1 - Login via Mobile Number › Verify - User
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-Aadhaar OTP › Verify - User
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-ABHA OTP › Verify - User
- P1-Registration-login › P1 - PHR Login › P1 - Login via Aadhaar- OTP › Verify - User

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/verify/user \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'T-token: Bearer <JWT TOKEN>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "abhaAddress": "<ABHA_ADDRESS>",
  "txnId": "c51ad4d8-ae92-4509-8fb9-b91dea948492"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `T-token` (string, required): The transaction token from the preceding login step, sent with a `Bearer ` prefix. It is valid only for that login.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `abhaAddress` (string, required)
- `txnId` (string, required)

## Responses

- `200`: OK
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
  - `code` (string)
  - `message` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors

Example 200 response. The values are placeholders:

```json
{
  "token": "<JWT TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<JWT TOKEN>",
  "refreshExpiresIn": 1296000
}
```


---

# Login request OTP

`POST /abha/api/v3/phr/app/login/request/otp`

Flows:
- P1-Registration-login › P1 - PHR Login › P1 - Login via Mobile Number › OTP Request - Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Mobile OTP › OTP Request - ABHAADDRES Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-Aadhaar OTP › OTP Request - AADHAR OTP
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-ABHA OTP › OTP Request - ABHA OTP
- P1-Registration-login › P1 - PHR Login › P1 - Login via Aadhaar- OTP › new OTP Request- Aadhaar

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-address-login",
    "mobile-verify"
  ],
  "loginHint": "abha-address",
  "loginId": "{{encryptedData}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `loginHint` (string, required)
- `loginId` (string, required)
- `otpSystem` (string, required)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "b81a963d-4b97-48b4-9f9f-acf9f13afab7",
  "message": "OTP is sent to Mobile number ending with ******2425"
}
```


---

# Login PHR verify

`POST /abha/api/v3/phr/app/login/verify`

Flows:
- P1-Registration-login › P1 - PHR Login › P1 - Login via Mobile Number › Login OTP Verify - Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Mobile OTP › Login OTP Verify - ABHAADDRES Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-Aadhaar OTP › Login OTP Verify - AADHAR
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-ABHA OTP › Login OTP Verify - ABHA
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Password › Login Verify - Password
- P1-Registration-login › P1 - PHR Login › P1 - Login via Aadhaar- OTP › new OTP verify- Aadhaar

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-address-login",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
      "otpValue": "{{encryptedData}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `authData` (object, required)
- `authData.authMethods` (string[])
- `authData.otp` (object)
- `authData.otp.txnId` (string)
- `authData.otp.otpValue` (string)
- `authData.password` (object)
- `authData.password.abhaAddress` (string)
- `authData.password.password` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `tokens.switchProfileEnabled` (boolean)
  - `accounts` (object[])
  - `accounts.mobile` (string)
  - `accounts.firstName` (string)
  - `accounts.middleName` (string)
  - `accounts.lastName` (string)
  - `accounts.name` (string)
  - `accounts.yearOfBirth` (string)
  - `accounts.dayOfBirth` (string)
  - `accounts.monthOfBirth` (string)
  - `accounts.gender` (string)
  - `accounts.email` (object)
  - `accounts.profilePhoto` (string)
  - `accounts.status` (string)
  - `accounts.stateCode` (string)
  - `accounts.districtCode` (string)
  - `accounts.subDistrictCode` (object)
  - `accounts.villageCode` (object)
  - `accounts.townCode` (object)
  - `accounts.wardCode` (object)
  - `accounts.pincode` (string)
  - `accounts.address` (string)
  - `accounts.kycPhoto` (string)
  - `accounts.stateName` (string)
  - `accounts.districtName` (string)
  - `accounts.subdistrictName` (string)
  - `accounts.villageName` (object)
  - `accounts.townName` (string)
  - `accounts.wardName` (object)
  - `accounts.authMethods` (string[])
  - `accounts.tags` (object)
  - `accounts.kycVerified` (boolean)
  - `accounts.verificationStatus` (string)
  - `accounts.verificationType` (string)
  - `accounts.emailVerified` (object)
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `preferredAbhaAddress` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "b81a963d-4b97-48b4-9f9f-acf9f13afab7",
  "message": "OTP verified successfully",
  "authResult": "success",
  "users": [
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "abhaNumber": "<ABHA_NUMBER>",
      "status": "ACTIVE",
      "kycStatus": "VERIFIED"
    },
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "abhaNumber": "<ABHA_NUMBER>",
      "status": "ACTIVE",
      "kycStatus": "PENDING"
    },
    "... 1 more of the same shape"
  ],
  "tokens": {
    "token": "<JWT TOKEN>",
    "expiresIn": 1800,
    "refreshToken": null,
    "refreshExpiresIn": null
  }
}
```


---

# Search auth methods ABHAAddress

`POST /abha/api/v3/phr/app/login/search`

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/search \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "abhaAddress": "<ABHA_ADDRESS>"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `abhaAddress` (string, required)

## Responses

- `200`: OK
  - `healthIdNumber` (string)
  - `abhaAddress` (string)
  - `authMethods` (string[])
  - `blockedAuthMethods` (object[])
  - `status` (string)
  - `message` (object)
  - `fullName` (string)
  - `mobile` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "healthIdNumber": "<ABHA_NUMBER>",
  "abhaAddress": "<ABHA_ADDRESS>",
  "authMethods": [
    "MOBILE_OTP",
    "PASSWORD",
    "... 1 more of the same shape"
  ],
  "blockedAuthMethods": [],
  "status": "ACTIVE",
  "message": null
}
```


---

# Login PHR verify

`POST /abha/api/v3/phr/app/login/verify`

Flows:
- P1-Registration-login › P1 - PHR Login › P1 - Login via Mobile Number › Login OTP Verify - Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Mobile OTP › Login OTP Verify - ABHAADDRES Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-Aadhaar OTP › Login OTP Verify - AADHAR
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-ABHA OTP › Login OTP Verify - ABHA
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Password › Login Verify - Password
- P1-Registration-login › P1 - PHR Login › P1 - Login via Aadhaar- OTP › new OTP verify- Aadhaar

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-address-login",
    "password-verify"
  ],
  "authData": {
    "authMethods": [
      "password"
    ],
    "password": {
      "abhaAddress": "<ABHA_ADDRESS>",
      "password": "<ENCRYPTED_PASSWORD>"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `authData` (object, required)
- `authData.authMethods` (string[])
- `authData.otp` (object)
- `authData.otp.txnId` (string)
- `authData.otp.otpValue` (string)
- `authData.password` (object)
- `authData.password.abhaAddress` (string)
- `authData.password.password` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `tokens.switchProfileEnabled` (boolean)
  - `accounts` (object[])
  - `accounts.mobile` (string)
  - `accounts.firstName` (string)
  - `accounts.middleName` (string)
  - `accounts.lastName` (string)
  - `accounts.name` (string)
  - `accounts.yearOfBirth` (string)
  - `accounts.dayOfBirth` (string)
  - `accounts.monthOfBirth` (string)
  - `accounts.gender` (string)
  - `accounts.email` (object)
  - `accounts.profilePhoto` (string)
  - `accounts.status` (string)
  - `accounts.stateCode` (string)
  - `accounts.districtCode` (string)
  - `accounts.subDistrictCode` (object)
  - `accounts.villageCode` (object)
  - `accounts.townCode` (object)
  - `accounts.wardCode` (object)
  - `accounts.pincode` (string)
  - `accounts.address` (string)
  - `accounts.kycPhoto` (string)
  - `accounts.stateName` (string)
  - `accounts.districtName` (string)
  - `accounts.subdistrictName` (string)
  - `accounts.villageName` (object)
  - `accounts.townName` (string)
  - `accounts.wardName` (object)
  - `accounts.authMethods` (string[])
  - `accounts.tags` (object)
  - `accounts.kycVerified` (boolean)
  - `accounts.verificationStatus` (string)
  - `accounts.verificationType` (string)
  - `accounts.emailVerified` (object)
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `preferredAbhaAddress` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "b81a963d-4b97-48b4-9f9f-acf9f13afab7",
  "message": "OTP verified successfully",
  "authResult": "success",
  "users": [
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "abhaNumber": "<ABHA_NUMBER>",
      "status": "ACTIVE",
      "kycStatus": "VERIFIED"
    },
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "abhaNumber": "<ABHA_NUMBER>",
      "status": "ACTIVE",
      "kycStatus": "PENDING"
    },
    "... 1 more of the same shape"
  ],
  "tokens": {
    "token": "<JWT TOKEN>",
    "expiresIn": 1800,
    "refreshToken": null,
    "refreshExpiresIn": null
  }
}
```


---

# Login request OTP

`POST /abha/api/v3/phr/app/login/request/otp`

Flows:
- P1-Registration-login › P1 - PHR Login › P1 - Login via Mobile Number › OTP Request - Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Mobile OTP › OTP Request - ABHAADDRES Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-Aadhaar OTP › OTP Request - AADHAR OTP
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-ABHA OTP › OTP Request - ABHA OTP
- P1-Registration-login › P1 - PHR Login › P1 - Login via Aadhaar- OTP › new OTP Request- Aadhaar

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-verify"
  ],
  "loginHint": "abha-number",
  "loginId": "{{encryptedData}}",
  "otpSystem": "aadhaar"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `loginHint` (string, required)
- `loginId` (string, required)
- `otpSystem` (string, required)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "b81a963d-4b97-48b4-9f9f-acf9f13afab7",
  "message": "OTP is sent to Mobile number ending with ******2425"
}
```


---

# Login PHR verify

`POST /abha/api/v3/phr/app/login/verify`

Flows:
- P1-Registration-login › P1 - PHR Login › P1 - Login via Mobile Number › Login OTP Verify - Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Mobile OTP › Login OTP Verify - ABHAADDRES Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-Aadhaar OTP › Login OTP Verify - AADHAR
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-ABHA OTP › Login OTP Verify - ABHA
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Password › Login Verify - Password
- P1-Registration-login › P1 - PHR Login › P1 - Login via Aadhaar- OTP › new OTP verify- Aadhaar

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
      "otpValue": "{{encryptedData}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `authData` (object, required)
- `authData.authMethods` (string[])
- `authData.otp` (object)
- `authData.otp.txnId` (string)
- `authData.otp.otpValue` (string)
- `authData.password` (object)
- `authData.password.abhaAddress` (string)
- `authData.password.password` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `tokens.switchProfileEnabled` (boolean)
  - `accounts` (object[])
  - `accounts.mobile` (string)
  - `accounts.firstName` (string)
  - `accounts.middleName` (string)
  - `accounts.lastName` (string)
  - `accounts.name` (string)
  - `accounts.yearOfBirth` (string)
  - `accounts.dayOfBirth` (string)
  - `accounts.monthOfBirth` (string)
  - `accounts.gender` (string)
  - `accounts.email` (object)
  - `accounts.profilePhoto` (string)
  - `accounts.status` (string)
  - `accounts.stateCode` (string)
  - `accounts.districtCode` (string)
  - `accounts.subDistrictCode` (object)
  - `accounts.villageCode` (object)
  - `accounts.townCode` (object)
  - `accounts.wardCode` (object)
  - `accounts.pincode` (string)
  - `accounts.address` (string)
  - `accounts.kycPhoto` (string)
  - `accounts.stateName` (string)
  - `accounts.districtName` (string)
  - `accounts.subdistrictName` (string)
  - `accounts.villageName` (object)
  - `accounts.townName` (string)
  - `accounts.wardName` (object)
  - `accounts.authMethods` (string[])
  - `accounts.tags` (object)
  - `accounts.kycVerified` (boolean)
  - `accounts.verificationStatus` (string)
  - `accounts.verificationType` (string)
  - `accounts.emailVerified` (object)
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `preferredAbhaAddress` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "b81a963d-4b97-48b4-9f9f-acf9f13afab7",
  "message": "OTP verified successfully",
  "authResult": "success",
  "users": [
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "abhaNumber": "<ABHA_NUMBER>",
      "status": "ACTIVE",
      "kycStatus": "VERIFIED"
    },
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "abhaNumber": "<ABHA_NUMBER>",
      "status": "ACTIVE",
      "kycStatus": "PENDING"
    },
    "... 1 more of the same shape"
  ],
  "tokens": {
    "token": "<JWT TOKEN>",
    "expiresIn": 1800,
    "refreshToken": null,
    "refreshExpiresIn": null
  }
}
```


---

# Verify User, verify user

`POST /abha/api/v3/phr/app/login/verify/user`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › Verify User
- P1-Registration-login › P1 - PHR Login › P1 - Login via Mobile Number › Verify - User
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-Aadhaar OTP › Verify - User
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-ABHA OTP › Verify - User
- P1-Registration-login › P1 - PHR Login › P1 - Login via Aadhaar- OTP › Verify - User

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/verify/user \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'T-token: Bearer <JWT TOKEN>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "abhaAddress": "<ABHA_ADDRESS>",
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `T-token` (string, required): The transaction token from the preceding login step, sent with a `Bearer ` prefix. It is valid only for that login.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `abhaAddress` (string, required)
- `txnId` (string, required)

## Responses

- `200`: OK
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
  - `code` (string)
  - `message` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors

Example 200 response. The values are placeholders:

```json
{
  "token": "<JWT TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<JWT TOKEN>",
  "refreshExpiresIn": 1296000
}
```


---

# Login request OTP

`POST /abha/api/v3/phr/app/login/request/otp`

Flows:
- P1-Registration-login › P1 - PHR Login › P1 - Login via Mobile Number › OTP Request - Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Mobile OTP › OTP Request - ABHAADDRES Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-Aadhaar OTP › OTP Request - AADHAR OTP
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-ABHA OTP › OTP Request - ABHA OTP
- P1-Registration-login › P1 - PHR Login › P1 - Login via Aadhaar- OTP › new OTP Request- Aadhaar

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "mobile-verify"
  ],
  "loginHint": "abha-number",
  "loginId": "{{encryptedData}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `loginHint` (string, required)
- `loginId` (string, required)
- `otpSystem` (string, required)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "b81a963d-4b97-48b4-9f9f-acf9f13afab7",
  "message": "OTP is sent to Mobile number ending with ******2425"
}
```


---

# Login PHR verify

`POST /abha/api/v3/phr/app/login/verify`

Flows:
- P1-Registration-login › P1 - PHR Login › P1 - Login via Mobile Number › Login OTP Verify - Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Mobile OTP › Login OTP Verify - ABHAADDRES Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-Aadhaar OTP › Login OTP Verify - AADHAR
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-ABHA OTP › Login OTP Verify - ABHA
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Password › Login Verify - Password
- P1-Registration-login › P1 - PHR Login › P1 - Login via Aadhaar- OTP › new OTP verify- Aadhaar

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
      "otpValue": "{{encryptedData}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `authData` (object, required)
- `authData.authMethods` (string[])
- `authData.otp` (object)
- `authData.otp.txnId` (string)
- `authData.otp.otpValue` (string)
- `authData.password` (object)
- `authData.password.abhaAddress` (string)
- `authData.password.password` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `tokens.switchProfileEnabled` (boolean)
  - `accounts` (object[])
  - `accounts.mobile` (string)
  - `accounts.firstName` (string)
  - `accounts.middleName` (string)
  - `accounts.lastName` (string)
  - `accounts.name` (string)
  - `accounts.yearOfBirth` (string)
  - `accounts.dayOfBirth` (string)
  - `accounts.monthOfBirth` (string)
  - `accounts.gender` (string)
  - `accounts.email` (object)
  - `accounts.profilePhoto` (string)
  - `accounts.status` (string)
  - `accounts.stateCode` (string)
  - `accounts.districtCode` (string)
  - `accounts.subDistrictCode` (object)
  - `accounts.villageCode` (object)
  - `accounts.townCode` (object)
  - `accounts.wardCode` (object)
  - `accounts.pincode` (string)
  - `accounts.address` (string)
  - `accounts.kycPhoto` (string)
  - `accounts.stateName` (string)
  - `accounts.districtName` (string)
  - `accounts.subdistrictName` (string)
  - `accounts.villageName` (object)
  - `accounts.townName` (string)
  - `accounts.wardName` (object)
  - `accounts.authMethods` (string[])
  - `accounts.tags` (object)
  - `accounts.kycVerified` (boolean)
  - `accounts.verificationStatus` (string)
  - `accounts.verificationType` (string)
  - `accounts.emailVerified` (object)
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `preferredAbhaAddress` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "b81a963d-4b97-48b4-9f9f-acf9f13afab7",
  "message": "OTP verified successfully",
  "authResult": "success",
  "users": [
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "abhaNumber": "<ABHA_NUMBER>",
      "status": "ACTIVE",
      "kycStatus": "VERIFIED"
    },
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "abhaNumber": "<ABHA_NUMBER>",
      "status": "ACTIVE",
      "kycStatus": "PENDING"
    },
    "... 1 more of the same shape"
  ],
  "tokens": {
    "token": "<JWT TOKEN>",
    "expiresIn": 1800,
    "refreshToken": null,
    "refreshExpiresIn": null
  }
}
```


---

# Verify User, verify user

`POST /abha/api/v3/phr/app/login/verify/user`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › Verify User
- P1-Registration-login › P1 - PHR Login › P1 - Login via Mobile Number › Verify - User
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-Aadhaar OTP › Verify - User
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-ABHA OTP › Verify - User
- P1-Registration-login › P1 - PHR Login › P1 - Login via Aadhaar- OTP › Verify - User

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/verify/user \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'T-token: Bearer <JWT TOKEN>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "abhaAddress": "<ABHA_ADDRESS>",
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `T-token` (string, required): The transaction token from the preceding login step, sent with a `Bearer ` prefix. It is valid only for that login.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `abhaAddress` (string, required)
- `txnId` (string, required)

## Responses

- `200`: OK
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
  - `code` (string)
  - `message` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors

Example 200 response. The values are placeholders:

```json
{
  "token": "<JWT TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<JWT TOKEN>",
  "refreshExpiresIn": 1296000
}
```


---

# Login request OTP

`POST /abha/api/v3/phr/app/login/request/otp`

Flows:
- P1-Registration-login › P1 - PHR Login › P1 - Login via Mobile Number › OTP Request - Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Mobile OTP › OTP Request - ABHAADDRES Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-Aadhaar OTP › OTP Request - AADHAR OTP
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-ABHA OTP › OTP Request - ABHA OTP
- P1-Registration-login › P1 - PHR Login › P1 - Login via Aadhaar- OTP › new OTP Request- Aadhaar

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-address-login",
    "mobile-verify"
  ],
  "loginHint": "mobile-number",
  "loginId": "{{encryptedData}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `loginHint` (string, required)
- `loginId` (string, required)
- `otpSystem` (string, required)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "b81a963d-4b97-48b4-9f9f-acf9f13afab7",
  "message": "OTP is sent to Mobile number ending with ******2425"
}
```


---

# Login PHR verify

`POST /abha/api/v3/phr/app/login/verify`

Flows:
- P1-Registration-login › P1 - PHR Login › P1 - Login via Mobile Number › Login OTP Verify - Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Mobile OTP › Login OTP Verify - ABHAADDRES Mobile
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-Aadhaar OTP › Login OTP Verify - AADHAR
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-ABHA OTP › Login OTP Verify - ABHA
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Address - Password › Login Verify - Password
- P1-Registration-login › P1 - PHR Login › P1 - Login via Aadhaar- OTP › new OTP verify- Aadhaar

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-address-login",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
      "otpValue": "{{encryptedData}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `authData` (object, required)
- `authData.authMethods` (string[])
- `authData.otp` (object)
- `authData.otp.txnId` (string)
- `authData.otp.otpValue` (string)
- `authData.password` (object)
- `authData.password.abhaAddress` (string)
- `authData.password.password` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
  - `tokens.switchProfileEnabled` (boolean)
  - `accounts` (object[])
  - `accounts.mobile` (string)
  - `accounts.firstName` (string)
  - `accounts.middleName` (string)
  - `accounts.lastName` (string)
  - `accounts.name` (string)
  - `accounts.yearOfBirth` (string)
  - `accounts.dayOfBirth` (string)
  - `accounts.monthOfBirth` (string)
  - `accounts.gender` (string)
  - `accounts.email` (object)
  - `accounts.profilePhoto` (string)
  - `accounts.status` (string)
  - `accounts.stateCode` (string)
  - `accounts.districtCode` (string)
  - `accounts.subDistrictCode` (object)
  - `accounts.villageCode` (object)
  - `accounts.townCode` (object)
  - `accounts.wardCode` (object)
  - `accounts.pincode` (string)
  - `accounts.address` (string)
  - `accounts.kycPhoto` (string)
  - `accounts.stateName` (string)
  - `accounts.districtName` (string)
  - `accounts.subdistrictName` (string)
  - `accounts.villageName` (object)
  - `accounts.townName` (string)
  - `accounts.wardName` (object)
  - `accounts.authMethods` (string[])
  - `accounts.tags` (object)
  - `accounts.kycVerified` (boolean)
  - `accounts.verificationStatus` (string)
  - `accounts.verificationType` (string)
  - `accounts.emailVerified` (object)
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `preferredAbhaAddress` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "b81a963d-4b97-48b4-9f9f-acf9f13afab7",
  "message": "OTP verified successfully",
  "authResult": "success",
  "users": [
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "abhaNumber": "<ABHA_NUMBER>",
      "status": "ACTIVE",
      "kycStatus": "VERIFIED"
    },
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "abhaNumber": "<ABHA_NUMBER>",
      "status": "ACTIVE",
      "kycStatus": "PENDING"
    },
    "... 1 more of the same shape"
  ],
  "tokens": {
    "token": "<JWT TOKEN>",
    "expiresIn": 1800,
    "refreshToken": null,
    "refreshExpiresIn": null
  }
}
```


---

# Verify User, verify user

`POST /abha/api/v3/phr/app/login/verify/user`

Flows:
- P1-Registration-login › P1 - Create ABHA Address Flow › Enrolment via ABHA Number-ABHA OTP › Verify User
- P1-Registration-login › P1 - PHR Login › P1 - Login via Mobile Number › Verify - User
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-Aadhaar OTP › Verify - User
- P1-Registration-login › P1 - PHR Login › P1 - Login via ABHA Number-ABHA OTP › Verify - User
- P1-Registration-login › P1 - PHR Login › P1 - Login via Aadhaar- OTP › Verify - User

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/verify/user \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'T-token: Bearer <JWT TOKEN>' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "abhaAddress": "<ABHA_ADDRESS>",
  "txnId": "48bc0a00-1127-459c-b040-8147f4ccc11a"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for each request.
- `T-token` (string, required): The transaction token from the preceding login step, sent with a `Bearer ` prefix. It is valid only for that login.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `abhaAddress` (string, required)
- `txnId` (string, required)

## Responses

- `200`: OK
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors
  - `code` (string)
  - `message` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p1/errors

Example 200 response. The values are placeholders:

```json
{
  "token": "<JWT TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<JWT TOKEN>",
  "refreshExpiresIn": 1296000
}
```


---

# P1 Registration and login errors

Seeing a symptom rather than a code? Start at [Troubleshooting](/docs/hiecm/v3/troubleshooting/).

## Codes

| Code        | HTTP | Message                        | Returned by                                 |
| ----------- | ---- | ------------------------------ | ------------------------------------------- |
| `900902`    | 401  | Missing Credentials            | `p1_get_v3_phr_app_enrollment_isexists`     |
| `ABDM-1107` | 400  | Invalid combinations of scopes | `p1_post_v3_phr_app_login_verify`           |
| `ABDM-1211` | 400  | User not found.                | `p1_post_v3_phr_app_login_search`           |
| `ABDM-9999` | 400  | Invalid LoginId                | `p1_post_v3_phr_app_enrollment_request_otp` |

Every code above is recorded in the specification that owns it. The aggregated list across modules is at [error codes](/docs/hiecm/v3/reference/error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# OPD token generation

`POST /api/hiecm/patient-share/v3/share`

This is an API will be invoked from the **PHR-HIU** to share the user/patient profile with HMIS/LIMS.

 **Header**

Authorisation will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-AUTH-TOKEN JWT Authentication token which was issued by ABDM after successful validation of username and password[ Example: ]

X-CM-ID consent manager ID[ Example: sbx ]

X-HIU-ID HIU ID[ Example: HIU ]

 **Request Body**

intent This is a key value pair which contains the purpose [ Example: {purpose: PROFILE_SHARE } ]

metaData This is a key value pair which contains the location longitude and latitude[ Example: {HIP_ID: ABDM_HIP, context: 123, lat: 20.5937 long: 78.9629} ]

profile which contains user details.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/patient-share/v3/share \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-HIU-ID: HIU_ID' \
  --header 'X-AUTH-TOKEN: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "intent": "PROFILE_SHARE",
  "metaData": {
    "hipId": "HIP_1",
    "context": "6",
    "hprId": "<EMAIL>",
    "latitude": 20.5937,
    "longitude": 78.9629
  },
  "profile": {
    "patient": {
      "abhaNumber": "<ABHA_NUMBER>",
      "abhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "gender": "M",
      "dayOfBirth": "<DOB>",
      "monthOfBirth": "<DOB>",
      "yearOfBirth": "9999",
      "address": {
        "line": "Address line 1",
        "district": "Coimbatore",
        "state": "Tamil Nadu",
        "pincode": "<PINCODE>"
      },
      "phoneNumber": "<MOBILE_NUMBER>"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Body

- `intent` (string, required): The intention of share API call One of: PROFILE_SHARE, RECORD_SHARE, PAYMENT_SHARE.
- `metaData` (object, required): A key-value pair carrying the location longitude and latitude.
- `metaData.hipId` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 @//_//-]*[A-Z a-z 0-9]
- `metaData.context` (string, required): This is a counter Id. Allows alpha numeric character and special characters like ^(?:[a-zA-Z0-9 ]|[a-zA-Z0-9 ][a-zA-Z0-9.\\-_ ]*[a-zA-Z0-9 ]){1,250}$
- `metaData.hprId` (string): Healthcare Professionals Registry id. Allows alpha numeric character and special characters like [a-zA-Z0-9][a-zA-Z0-9_.]+[a-zA-Z0-9]@(dr.abdm|hpr.abdm)$|^[1-9][0-9]{13}$
- `metaData.latitude` (number, required): The latitude of the location.Allows alpha numeric character and special characters like ^[0-9-.]+$
- `metaData.longitude` (number, required): The longitude of the location.Allows alpha numeric character and special characters like ^[0-9-.]+$
- `profile` (object, required): This should populated only for PROFILE_SHARE
- `profile.patient` (object, required)
- `profile.patient.abhaNumber` (string): The abha number of the patient. Should be only 14 digit. Allows alpha numeric character and special characters like ^(\\d+-?){13}\\d$
- `profile.patient.abhaAddress` (string, required): The abha address of the patient. Should start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx and Allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.\-!]+[a-zA-Z0-9]@(abdm|sbx)$
- `profile.patient.name` (string, required): The name of the patient. Allows alpha numeric character and special characters like ^[a-zA-Z0-9.-_,]+(([',. -][a-zA-Z0-9. ])?[a-zA-Z0-9. ]*)*$
- `profile.patient.gender` (string, required): The gender of the patient One of: M, F, O, D, T, U.
- `profile.patient.dayOfBirth` (string): The day of birth of the patient. Only allows numeric values between 1 abd 31 and ^(?!\\s*$)(0?[1-9]|[12][0-9]|3[01])$
- `profile.patient.monthOfBirth` (string): The month of birth of the patient. Only allows numeric values between 1 abd 12 and ^(?!\\s*$)(0?[1-9]|[1][0-2])$
- `profile.patient.yearOfBirth` (string, required): The month of birth of the patient. Only allows numeric values and must be 4 digit ranging between 1900 and 2200 and ^(?!\\s*$)(19|20|21|22)\\d{2}$
- `profile.patient.address` (object, required)
- `profile.patient.address.line` (string, required): The address line
- `profile.patient.address.district` (string): The district and should only contain alphabets
- `profile.patient.address.state` (string): The state and should only contain alphabets like [A-Z a-z]+[A-Z a-z //' ']*$
- `profile.patient.address.pincode` (string): Should be 5 digits and only contain numbers
- `profile.patient.phoneNumber` (string, required): The mobile number of the patient. Must be 10 digit and contain only 0-9 and it allows only numbers like ^(\+\d{1,3}[- ]?)?\d{10}$

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare (`ABDM-1006`) or with a trailing ": " separator (`ABDM-1006: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `408`: Request Timeout
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1007 - Connection failed due to timeout. May be returned either bare (`ABDM-1007`) or with a trailing ": " separator (`ABDM-1007: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `429`: Too Many Requests
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1022 - Too many requests. May be returned either bare (`ABDM-1022`) or with a trailing ": " separator (`ABDM-1022: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Receive the HIU patient on share

`POST /api/v3/hiu/patient/on-share`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This is an API will be invoked by **HIU** to share the response of HIECM's /api/hiecm/patient-share/v3/on-share API.

 **Header**

Authorisation will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-HIU-ID HIU ID[ Example: HIU ]

 **Request Body**

Incase of success scenario,acknowledgement is mandatory and error is optional

Incase if failure scenario,error is mandatory and acknowledgment is optional

response is mandatory object in both the cases

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hiu/patient/on-share \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: HIU_ID' \
  --header 'Content-Type: application/json' \
  --data '{
  "acknowledgement": {
    "status": "SUCCESS",
    "abhaAddress": "<ABHA_ADDRESS>",
    "profile": {
      "context": "43",
      "tokenNumber": "3",
      "expiry": 180
    }
  },
  "error": {
    "code": "ABDM-9999",
    "message": "Unknown exception"
  },
  "response": {
    "requestId": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `acknowledgement` (object, required)
- `acknowledgement.status` (string, required): The status of the transaction.Allows like (SUCCESS|FAILED)
- `acknowledgement.abhaAddress` (string, required): The abha address of the patient. Should start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx and Allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.\-!]+[a-zA-Z0-9]@(abdm|sbx)$
- `acknowledgement.profile` (object, required): Should be populated only if this is a response for PROFILE_SHARE request
- `acknowledgement.profile.context` (string, required): This is a counter Id. Allows alpha numeric character and special characters like ^(?:[a-zA-Z0-9 ]|[a-zA-Z0-9 ][a-zA-Z0-9.\\-_ ]*[a-zA-Z0-9 ]){1,250}$
- `acknowledgement.profile.tokenNumber` (string, required): The token number generated at HIP for the request
- `acknowledgement.profile.expiry` (number, required): The expiry time and should be only numeric value.Allows alpha numeric character and special characters like [\d]*$
- `error` (object, required): error is optional object in case of Sucess response.
- `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
- `error.message` (string, required)
- `response` (object, required)
- `response.requestId` (string, required): The requestId that was passed.Allows alpha numeric character and special characters like [0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `408`: Request Timeout
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1007 - Connection failed due to timeout. May be returned either bare (`ABDM-1007`) or with a trailing ": " separator (`ABDM-1007: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# OPD Token History

`GET /api/hiecm/patient-share/v3/profile/getTokenDetails`

This is an API will be invoked get the historical token numbers of the patient.

 **Header**

AUTHORIZATION will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

```bash
curl --request GET \
  --url "https://dev.abdm.gov.in/api/hiecm/patient-share/v3/profile/getTokenDetails?limit=<LIMIT>" \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: Bearer <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Query parameters

- `limit` (string, required): The limit of data to be fetched

## Responses

- `200`: OK
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare (`ABDM-1006`) or with a trailing ": " separator (`ABDM-1006: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `408`: Request Timeout
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1007 - Connection failed due to timeout. May be returned either bare (`ABDM-1007`) or with a trailing ": " separator (`ABDM-1007: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `429`: Too Many Requests
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1022 - Too many requests. May be returned either bare (`ABDM-1022`) or with a trailing ": " separator (`ABDM-1022: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
[
  {
    "id": 1,
    "patientId": "<ABHA_ADDRESS>",
    "tokenNumber": "1",
    "hipId": "ABDM_HIP",
    "hipName": "Health Information Provider Name",
    "hipAddress": "sample address",
    "expiresIn": 1800,
    "clientId": "ABDM",
    "dateCreated": "2024-09-11T07:31:02.357Z",
    "counterCode": "Counter 1"
  }
]
```


---

# Fetch the list of providers filtered by name

`GET /api/hiecm/gateway/v3/providers`

Retrieve a list of providers, filtered by their names. When invoked, it queries the system to fetch providers that match the specified name criteria. This functionality is particularly useful for narrowing down provider options based on specific naming conventions or patterns. By using this API, users can efficiently locate and manage providers within the network, ensuring they have access to the relevant provider information needed for various operational tasks.

```bash
curl --request GET \
  --url https://dev.abdm.gov.in/api/hiecm/gateway/v3/providers \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Query parameters

- `name` (string): Name of the provider
- `stateCode` (string): Filter by state code; -1 for all.
- `districtCode` (string): Filter by district code; -1 for all.

## Responses

- `200`: OK
- `204`: No Content
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1015 - Invalid Response. May be returned either bare (`ABDM-1015`) or with a trailing ": " separator (`ABDM-1015: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
[
  {
    "identifier": {
      "name": "AB - PMJAY",
      "id": "PMJAY"
    },
    "facilityType": [
      "HIP"
    ],
    "isHIP": true,
    "isHiu": false,
    "isHealthLocker": true,
    "isPhr": true,
    "isGovtEntity": false,
    "endpoints": {
      "healthLockerEndpoints": [
        {
          "use": "registration",
          "connectionType": "HTTPS",
          "address": "https://abc.com/register"
        }
      ]
    }
  }
]
```


---

# Fetch the record for provider details for requested provider ID

`GET /api/hiecm/gateway/v3/providers/{hip-id}`

Retrieve the details of a specific provider based on the provided provider ID. When invoked, it queries the system to fetch comprehensive information about the provider identified by the given ID.

```bash
curl --request GET \
  --url https://dev.abdm.gov.in/api/hiecm/gateway/v3/providers/{hip-id} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Path parameters

- `hip-id` (string, required)

## Responses

- `200`: OK
  - `identifier` (object)
  - `identifier.name` (string, required)
  - `identifier.id` (string, required)
  - `facilityType` (string[])
  - `isHIP` (boolean)
- `204`: No Content
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1015 - Invalid Response. May be returned either bare (`ABDM-1015`) or with a trailing ": " separator (`ABDM-1015: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "identifier": {
    "name": "AB - PMJAY",
    "id": "PMJAY"
  },
  "facilityType": [
    "HIP"
  ],
  "isHIP": true
}
```


---

# Discover his/her health records

`POST /api/hiecm/user-initiated-linking/v3/patient/care-context/discover`

Be invoked by the patient or user through the Personal Health Record (PHR) application to discover their health records. By using this API, patients can initiate a search to locate and access their health information across various Health Information Providers (HIPs). This functionality empowers patients to have greater control and visibility over their health data, facilitating a more informed and engaged approach to managing their health. The API supports the seamless retrieval of health records, ensuring that patients can easily discover and review their care contexts.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/user-initiated-linking/v3/patient/care-context/discover \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'X-AUTH-TOKEN: <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hip": {
    "id": "cowin_hip_01"
  },
  "unverifiedIdentifiers": [
    {
      "type": "MOBILE",
      "value": "+9198765*****"
    }
  ]
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Body

- `hip` (object, required): Identifier and name of the health information provider.
- `hip.id` (string, required): The service ID of the health information provider
- `unverifiedIdentifiers` (object[], required): Identifiers with which the HIP will search for the patient in its own records.
- `unverifiedIdentifiers.type` (string, required) One of: MR, MOBILE, ABHA_NUMBER, ABHA_ADDRESS.
- `unverifiedIdentifiers.value` (string, required): Allows alphanumeric characters and special characters like "^(\\+)?[a-zA-Z0-9_\\-@,. ]{0,255}$"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1103 - Duplicate Discovery request. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required): Unique UUID


---

# Receive the discovered care contexts of a patient

`POST /api/v3/hiu/patient/care-context/on-discover`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
The on-discover API endpoint allows HIUs to receive and process the care contexts associated with a patient. When a request is made to this endpoint, it returns a detailed response containing the patient’s care contexts, transaction details, and any errors that occurred. This ensures that HIUs have the necessary information to manage patient care effectively.

**NOTE:** In the request body, either 'patient' or 'error' must be included.

In case of success scenario, patient object is mandatory and error object is optional

In case of error scenario, error object is mandatory and patient object is optional

Response is mandatory in both scenarios

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hiu/patient/care-context/on-discover \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "transactionId": "f901b782-bfdf-4224-9f8d-da2cadc20c0d",
  "patient": [
    {
      "referenceNumber": "abc123",
      "display": "12345",
      "careContexts": [
        {
          "referenceNumber": "abc123",
          "display": "12345"
        }
      ],
      "hiType": "Prescription",
      "count": 1
    }
  ],
  "createdAt": "2024-12-31T05:45:35.429Z",
  "error": {
    "code": "ABDM-1001",
    "message": "No data found"
  },
  "response": {
    "requestId": "f29f0e59-8388-4698-9fe6-05db67aeac46"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `transactionId` (string, required)
- `patient` (object[], required)
- `patient.referenceNumber` (string, required): A patient identifier with which patient is registered in the facility/hospital.Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. ()/:\\\\]{0,255}$"
- `patient.display` (string): Display text for patient reference.Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"
- `patient.careContexts` (object[], required): List of care contexts linked at the HIP end for the identified patient.
- `patient.careContexts.referenceNumber` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data).Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. ()/:\\\\]{0,255}$"
- `patient.careContexts.display` (string, required): Display text for care context reference. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"
- `patient.hiType` (string, required): The health information type One of: DiagnosticReport, DischargeSummary, HealthDocumentRecord, ImmunizationRecord, OPConsultation, Prescription, WellnessRecord, Invoice.
- `patient.count` (integer, required): The count should match the number of care contexts in the payload
- `createdAt` (string, required)
- `error` (object): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message
- `response` (object, required)
- `response.requestId` (string, required): The request id that was passed.Allows alpha numeric characters and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"

## Responses

- `200`: Ok
  - `transactionId` (string)
  - `patient` (object[])
  - `patient.referenceNumber` (string): Reference number used while linking the health records of the patient.
  - `patient.display` (string): Displayed information about the care context.
  - `patient.careContexts` (object[]): List of care contexts linked at the HIP end for the identified patient.
  - `patient.careContexts.referenceNumber` (string): Reference number used while linking the health records of the patient.
  - `patient.careContexts.display` (string): Displayed information about the care context.
  - `patient.hiType` (string) One of: DiagnosticReport, DischargeSummary, HealthDocumentRecord, ImmunizationRecord, OPConsultation, Prescription, WellnessRecord, Invoice.
  - `patient.count` (integer): Number of health records in the careContext object.
  - `createdAt` (string)
  - `response` (object)
  - `response.requestId` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1106 - Duplicate On discovery request. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)

Example 200 response. The values are placeholders:

```json
{
  "transactionId": "0d36501c-551a-4bb5-b247-eec4bb42984b",
  "patient": [
    {
      "referenceNumber": "example01",
      "display": "abcd-display",
      "careContexts": [
        {
          "referenceNumber": "abcd",
          "display": "123-display"
        }
      ],
      "hiType": "Prescription",
      "count": 1
    }
  ],
  "createdAt": "2023-06-13T08:05:43.030Z",
  "response": {
    "requestId": "d89525a2-3a3f-4d39-98b5-477afb1865f6"
  }
}
```


---

# Link his/her health records

`POST /api/hiecm/user-initiated-linking/v3/link/care-context/init`

Be invoked by the patient or user to link their health records. By using this API, patients can initiate the process of associating their health information with their ABHA (Ayushman Bharat Health Account) address. This functionality empowers patients to actively manage and consolidate their health records, ensuring that all relevant care contexts are accurately linked and accessible. The API supports a seamless and efficient health information exchange, enhancing the overall quality and continuity of care within the healthcare ecosystem.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/user-initiated-linking/v3/link/care-context/init \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'X-AUTH-TOKEN: <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "transactionId": "f901b782-bfdf-4224-9f8d-da2cadc20c0d",
  "patient": [
    {
      "referenceNumber": "<ABHA_ADDRESS>",
      "display": "Test",
      "careContexts": [
        {
          "referenceNumber": "abc123",
          "display": "Sugar Test"
        }
      ],
      "hiType": "OPConsultation",
      "count": 1
    }
  ]
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Body

- `transactionId` (string, required): UUID from discover request callback to track the entire user link flow
- `patient` (object[], required)
- `patient.referenceNumber` (string, required): A patient identifier with which patient is registered in the facility/hospital.Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. ()/:\\\\]{0,255}$"
- `patient.display` (string, required): Display text for patient reference.Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"
- `patient.careContexts` (object[], required): List of care contexts linked at the HIP end for the identified patient.
- `patient.careContexts.referenceNumber` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data).Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. ()/:\\\\]{0,255}$"
- `patient.careContexts.display` (string): Display text for care context reference.Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"
- `patient.hiType` (string, required): The health information type One of: DiagnosticReport, DischargeSummary, HealthDocumentRecord, ImmunizationRecord, OPConsultation, Prescription, WellnessRecord, Invoice.
- `patient.count` (integer, required): The count should match the number of care contexts in the payload

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1104 - Duplicate Init request. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required): The request id from discover call back .Allows alpha numeric characters and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"


---

# Receive the initial linking of care contexts for a patient

`POST /api/v3/hiu/patient/care-context/on-init`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
The on-init API endpoint allows HIUs to receive and process the initial linking of care contexts associated with a patient. When a request is made to this endpoint, it returns a detailed response containing the transaction ID, linking information, authentication details, and any errors that occurred. This ensures that HIUs have the necessary information to manage patient care effectively.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hiu/patient/care-context/on-init \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "transactionId": "f901b782-bfdf-4224-9f8d-da2cadc20c0d",
  "link": {
    "referenceNumber": "d353b782-bfdf-4224-9f8d-da2cadc20c0d",
    "authenticationType": "DIRECT",
    "meta": {
      "communicationMedium": "MOBILE",
      "communicationHint": "OTP",
      "communicationExpiry": "2024-05-01T05:22:34.123Z"
    }
  },
  "error": {
    "code": "ABDM-1001",
    "message": "No data found"
  },
  "response": {
    "requestId": "f29f0e59-8388-4698-9fe6-05db67aeac46"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `transactionId` (string, required): UUID from discover request callback to track the entire user link flow
- `link` (object, required)
- `link.referenceNumber` (string, required): The link reference number. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. ()/:\\\\]{0,255}$"
- `link.authenticationType` (string, required): The authenticationType. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$" One of: DIRECT, MEDIATED.
- `link.meta` (object, required)
- `link.meta.communicationMedium` (string, required): The communication medium. Allows alpha numeric characters and special characters like"^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$ One of: MOBILE, EMAIL.
- `link.meta.communicationHint` (string, required): The communication hint. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$
- `link.meta.communicationExpiry` (string, required): The communication expiry date. Should be UTC date in ISO format.Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$
- `error` (object): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message
- `response` (object, required): The request id is from the link/init callback
- `response.requestId` (string, required): The request id that was passed.Allows alpha numeric characters and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"

## Responses

- `200`: OK
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1107 - Duplicate On init request. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required): The request id that was passed.Allows alpha numeric characters and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"


---

# Confirm his/her health records

`POST /api/hiecm/user-initiated-linking/v3/link/care-context/confirm`

Be invoked by the patient or user to confirm their health records. By using this API, patients can validate and confirm the linkage of their health information to their ABHA (Ayushman Bharat Health Account) address. This confirmation process ensures that all relevant care contexts are accurately linked and verified, providing patients with control over their health data. The API supports a seamless and efficient health information exchange, enhancing the overall quality and continuity of care within the healthcare ecosystem.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/user-initiated-linking/v3/link/care-context/confirm \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'X-AUTH-TOKEN: <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "token": 123456,
  "linkRefNumber": "d353b782-bfdf-4224-9f8d-da2cadc20c0d"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Body

- `token` (integer, required): The token number. Must be 6 digit and contain only 0-9. Allows the numerical values like "[\\d]*$"
- `linkRefNumber` (string, required): The link reference number from the /on-init call back . Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1105 - Duplicate Confirm request. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required): The request id from discover call back .Allows alpha numeric characters and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"


---

# Receive confirmation of the linked care contexts for a patient

`POST /api/v3/hiu/patient/care-context/on-confirm`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
The on-confirm API endpoint allows HIUs to receive and process the confirmation of care context linking for a patient. When a request is made to this endpoint, it returns a detailed response containing the patient’s care contexts, transaction details, and any errors that occurred. This ensures that HIUs have the necessary information to manage patient care effectively and verify that the care contexts have been correctly linked.

**NOTE:** In the request body, either 'patient' or 'error' must be included.

In case of success scenario, patient object is mandatory and error object is optional

In case of failure scenario, error object is mandatory and patient object is optional

Response is mandatory in both scenarios

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hiu/patient/care-context/on-confirm \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "response": {
    "requestId": "f29f0e59-8388-4698-9fe6-05db67aeac46"
  },
  "patient": {
    "referenceNumber": "abc123",
    "display": "12345",
    "careContexts": [
      {
        "referenceNumber": "abc123",
        "display": "12345"
      }
    ],
    "hiType": "Prescription",
    "count": 1
  },
  "error": {
    "code": "ABDM-1001",
    "message": "No data found"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `response` (object, required): The request id is from the link/confirm callback
- `response.requestId` (string, required): The request id that was passed.Allows alpha numeric characters and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"
- `patient` (object, required)
- `patient.referenceNumber` (string, required): A patient identifier with which patient is registered in the facility/hospitalauthenticationType.Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$
- `patient.display` (string, required): Display text for patient reference.Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"
- `patient.careContexts` (object[], required): List of care contexts linked at the HIP end for the identified patient.
- `patient.careContexts.referenceNumber` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data).Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$
- `patient.careContexts.display` (string, required): Display text for care context reference. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \"':|()/]{0,255}$"
- `patient.hiType` (string, required): The health information type One of: DiagnosticReport, DischargeSummary, HealthDocumentRecord, ImmunizationRecord, OPConsultation, Prescription, WellnessRecord, Invoice.
- `patient.count` (integer, required): The count should match the number of care contexts in the payload
- `error` (object): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message

## Responses

- `200`: OK
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1108 - Notification DB service unavailable. May be returned either bare (`ABDM-1108`) or with a trailing ": " separator (`ABDM-1108: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required): The request id that was passed.Allows alpha numeric characters and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"


---

# Fetch the list of govt programmes

`GET /api/hiecm/gateway/v3/govt-programs`

Retrieve a list of government programmes. When invoked, it queries the system to fetch comprehensive information about various government programmes available. This functionality is particularly useful for users who need to access detailed information about different programmes.
 **Note:**

This API will retrive the list of govt-programmes in the form of list.

```bash
curl --request GET \
  --url https://dev.abdm.gov.in/api/hiecm/gateway/v3/govt-programs \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Responses

- `200`: OK
- `204`: No Content
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1015 - Invalid Response. May be returned either bare (`ABDM-1015`) or with a trailing ": " separator (`ABDM-1015: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
[
  {
    "identifier": {
      "name": "AB - PMJAY",
      "id": "PMJAY"
    },
    "facilityType": [
      "HIP"
    ],
    "isHIP": true
  }
]
```


---

# Setup an auto-approval policy for given HIU

`POST /api/hiecm/consent/v3/auto/approve`

Set up an auto-approval policy for a specified Health Information User (HIU). By invoking this API, users can configure automatic approval of consent requests from the designated HIU, streamlining the process of granting access to health data. This functionality is essential for enhancing efficiency and reducing manual intervention in the consent management process. The API supports secure and compliant health information exchange, ensuring that auto-approval policies are implemented in accordance with user preferences and regulatory requirements.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/auto/approve \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "isApplicableForAllHIPs": false,
  "hiu": {
    "id": "cowin_hiu_01",
    "name": "Cowin",
    "type": "HIU"
  },
  "includedSources": [
    {
      "hiTypes": [
        "Prescription"
      ],
      "purpose": {
        "text": "Care Management",
        "code": "CAREMGT",
        "refUri": "www.abc.com"
      },
      "hip": {
        "id": "cowin_hip_01",
        "name": "Cowin",
        "type": "HIP"
      },
      "period": {
        "from": "2021-09-28T12:30:08.573Z",
        "to": "2021-09-28T12:30:08.573Z"
      }
    }
  ],
  "excludedSources": [
    {
      "hiTypes": [
        "Prescription"
      ],
      "purpose": {
        "text": "Care Management",
        "code": "CAREMGT",
        "refUri": "www.abc.com"
      },
      "hip": {
        "id": "cowin_hip_01",
        "name": "Cowin",
        "type": "HIP"
      },
      "period": {
        "from": "2021-09-28T12:30:08.573Z",
        "to": "2021-09-28T12:30:08.573Z"
      }
    }
  ]
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Body

- `isApplicableForAllHIPs` (boolean, required): A boolean value to denote if the policy is applicable to all the HIPs or only the specified HIP
- `hiu` (object, required)
- `hiu.id` (string, required): The service ID of the health information user.  Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `hiu.name` (string, required): The name of the health information user. Allows alpha numeric and special characters like  "^[a-zA-Z]+[A-Za-z0-9_\\-@,().\\s\\xa0:/]+"
- `hiu.type` (string, required): The type of the health information user. Allows alpha numeric and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `includedSources` (object[], required): Included sources, carrying the list of hi types.
- `includedSources.hiTypes` (string[], required): Types of health information document.
- `includedSources.purpose` (object, required)
- `includedSources.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
- `includedSources.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
- `includedSources.purpose.refUri` (string, required): The reference URL. Should be a valid URL. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `includedSources.hip` (object): Identifier and name of the health information provider.
- `includedSources.hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `includedSources.hip.name` (string, required): The name of the health information provider. Allows alpha numeric and special characters like "^[a-zA-Z]+[A-Za-z0-9_\\-@,().\\s\\xa0:/]+"
- `includedSources.hip.type` (string, required): The type of the health information provider. Allows alpha numeric and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `includedSources.period` (object, required)
- `includedSources.period.from` (string, required): Should be UTC date time in ISO format.Allows alpha numeric and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `includedSources.period.to` (string, required): Should be UTC date time in ISO format.Allows alpha numeric and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `excludedSources` (object[]): Excluded sources, carrying the list of hi types.
- `excludedSources.hiTypes` (string[], required): Types of health information document.
- `excludedSources.purpose` (object)
- `excludedSources.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
- `excludedSources.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
- `excludedSources.purpose.refUri` (string, required): The reference URL. Should be a valid URL. Allows alpha numeric and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `excludedSources.hip` (object): Identifier and name of the health information provider.
- `excludedSources.hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `excludedSources.hip.name` (string, required): The name of the health information provider. Allows alpha numeric and special characters like "^[a-zA-Z]+[A-Za-z0-9_\\-@,().\\s\\xa0:/]+"
- `excludedSources.hip.type` (string, required): The type of the health information provider. Allows alpha numeric and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `excludedSources.period` (object, required)
- `excludedSources.period.from` (string, required): Should be UTC date time in ISO format.Allows alpha numeric and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `excludedSources.period.to` (string, required): Should be UTC date time in ISO format. Allows alpha numeric and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Disable the auto-approval policy

`POST /api/hiecm/consent/v3/auto/approve/{consentId}/disable`

Disable an existing auto-approval policy. By invoking this API, users can deactivate the automatic approval of consent requests for the specified Health Information User (HIU). This functionality is essential for maintaining control over consent management, allowing users to modify or revoke auto-approval settings as needed.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/auto/approve/{consentId}/disable \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Path parameters

- `consentId` (string, required): The auto approval id

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
  - `message` (string)
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required): The appropriate error message
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1065 - Invalid X Auth token. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 202 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "message": "Successfully disabled auto approval policy",
  "error": {
    "code": "ABDM-1001",
    "message": "unable to connect database"
  }
}
```


---

# Enable the auto-approval policy

`POST /api/hiecm/consent/v3/auto/approve/{consentId}/enable`

Enable an existing auto-approval policy. By invoking this API, users can activate the automatic approval of consent requests for the specified Health Information User (HIU). This functionality is essential for streamlining the consent management process, allowing consent requests to be automatically approved without manual intervention. The API supports secure and compliant health information exchange, ensuring that auto-approval policies are implemented in accordance with user preferences and regulatory requirements.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/auto/approve/{consentId}/enable \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Path parameters

- `consentId` (string, required): The auto approval id

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
  - `message` (string)
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required): The appropriate error message
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1065 - Invalid X Auth token. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 202 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "message": "Successfully enabled auto approval policy",
  "error": {
    "code": "ABDM-1001",
    "message": "unable to connect database"
  }
}
```


---

# Fetch all the consent request details of a patient

`GET /api/hiecm/consent/v3/request`

Fetch all consent request details for a patient. By invoking this API, users can retrieve a comprehensive list of all consent requests associated with a patient’s health information. This functionality is essential for maintaining transparency and ensuring that users have access to complete and up-to-date consent information. The API supports efficient tracking and management of consent requests, facilitating secure and compliant health information exchange within the healthcare ecosystem.

```bash
curl --request GET \
  --url "https://dev.abdm.gov.in/api/hiecm/consent/v3/request?limit=<LIMIT>" \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): The user token the PHR service issued when the patient logged in.

## Query parameters

- `limit` (integer, required): The number of items to be returned at a time
- `offset` (integer): The number of items to be skipped before starting to collect data
- `status` (string): Status of the consent

## Responses

- `200`: OK
  - `size` (integer)
  - `limit` (integer)
  - `offset` (integer)
  - `requests` (object[])
  - `requests.requestId` (string)
  - `requests.purpose` (object)
  - `requests.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
  - `requests.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
  - `requests.purpose.refUri` (string, required): The reference URL. Should be a valid URL
  - `requests.patient` (object)
  - `requests.patient.id` (string, required): The abha address of the patient
  - `requests.hip` (object): Identifier and name of the health information provider.
  - `requests.hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
  - `requests.hip.name` (string, required): The name of the health information provider. Allows alpha numeric and special characters like _\-@,():/
  - `requests.hip.type` (string): The type of the health information provider. Allows alpha numeric and special characters like _\-@,. ":/
  - `requests.hiu` (object)
  - `requests.hiu.id` (string, required): The service ID of the health information user.  Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
  - `requests.hiu.name` (string, required): The name of the health information user. Allows alpha numeric and special characters like _\-@,():/
  - `requests.hiu.type` (string): The type of the health information user. Allows alpha numeric and special characters like _\-@,. ":/
  - `requests.careContexts` (object[]): List of care contexts linked at the HIP end for the identified patient.
  - `requests.careContexts.patientReference` (string, required): A patient identifier with which patient is registered in the facility/hospital
  - `requests.careContexts.careContextReference` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data)
  - `requests.requester` (object)
  - `requests.requester.name` (string, required): The name of the requester
  - `requests.requester.identifier` (object, required)
  - `requests.requester.identifier.value` (string, required): The type of the identification. Allows alpha numeric character and special characters like _\-@,. ":/
  - `requests.requester.identifier.type` (string, required): The identification value. Allows alpha numeric character and special characters like _\-@,. ":/
  - `requests.requester.identifier.system` (string, required): Allows alpha numeric character and special characters like _\-@,. ":/
  - `requests.status` (string) One of: REQUESTED, EXPIRED, DENIED, GRANTED, REVOKED.
  - `requests.createdAt` (string)
  - `requests.lastUpdated` (string)
  - `requests.hiType` (string[])
  - `requests.permission` (object)
  - `requests.permission.accessMode` (string, required) One of: VIEW, STORE, STREAM, QUERY.
  - `requests.permission.dateRange` (object, required)
  - `requests.permission.dateRange.from` (string, required): Should be UTC date time in ISO format
  - `requests.permission.dateRange.to` (string, required): Should be UTC date time in ISO format
  - `requests.permission.dataEraseAt` (string, required): The date at which the consent expire. Should be UTC date time in ISO format
  - `requests.permission.frequency` (object, required)
  - `requests.permission.frequency.unit` (string, required) One of: HOUR, DAY, WEEK, MONTH, YEAR.
  - `requests.permission.frequency.value` (number, required): The frequency unit value. Should be be a integer
  - `requests.permission.frequency.repeats` (number, required): Should be be a integer
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "size": 10,
  "limit": 10,
  "offset": 0,
  "requests": [
    {
      "requestId": "e5ec415f-c098-40f6-a0db-faa162fc5295",
      "purpose": {
        "text": "Care Management",
        "code": "CAREMGT",
        "refUri": "www.abc.com"
      },
      "patient": {
        "id": "<ABHA_ADDRESS>"
      },
      "hip": {
        "id": "cowin_hip_01",
        "name": "Cowin",
        "type": "HIP"
      },
      "hiu": {
        "id": "cowin_hiu_01",
        "name": "Cowin",
        "type": "HIU"
      },
      "careContexts": [
        {
          "patientReference": "batman@tmh",
          "careContextReference": "Episode1"
        }
      ],
      "requester": {
        "name": "<ABHA_ADDRESS>",
        "identifier": {
          "value": "REG1",
          "type": "MH1001",
          "system": "https://www.sample.com"
        }
      },
      "status": "GRANTED",
      "createdAt": "2021-09-28T12:30:08.573Z",
      "lastUpdated": "2021-09-28T12:30:08.573Z",
      "hiType": [
        "Prescription"
      ],
      "permission": {
        "accessMode": "VIEW",
        "dateRange": {
          "from": "2021-09-28T12:30:08.573Z",
          "to": "2021-09-28T12:30:08.573Z"
        },
        "dataEraseAt": "2021-09-28T12:30:08.573Z",
        "frequency": {
          "unit": "HOUR",
          "value": 1,
          "repeats": 0
        }
      }
    }
  ]
}
```


---

# Get the consent request details by REQUEST-ID

`GET /api/hiecm/consent/v3/request/{consentRequestId}`

Retrieve the details of a consent request using the REQUEST-ID. By invoking this API, users can obtain comprehensive information about a specific consent request, including its status, scope, and any associated conditions. This functionality is essential for ensuring that users have access to accurate and up-to-date consent information, supporting secure and compliant health information exchange. The API facilitates efficient management and verification of consent requests, enhancing the overall integrity of the consent management process.

```bash
curl --request GET \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/request/{consentRequestId} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): The user token the PHR service issued when the patient logged in.

## Path parameters

- `consentRequestId` (string, required): The consent request id

## Responses

- `200`: OK
  - `requestId` (string)
  - `purpose` (object)
  - `purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
  - `purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
  - `purpose.refUri` (string, required): The reference URL.Allows alpha numeric and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
  - `patient` (object)
  - `patient.id` (string, required): The abha address of the patient
  - `hip` (object): Identifier and name of the health information provider.
  - `hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
  - `hip.name` (string, required): The name of the health information provider. Allows alpha numeric and special characters like "^[a-zA-Z]+[A-Za-z0-9_\\-@,().\\s\\xa0:/]+"
  - `hip.type` (string): The type of the health information provider. Allows alpha numeric and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
  - `hiu` (object)
  - `hiu.id` (string, required): The service ID of the health information user.  Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
  - `hiu.name` (string, required): The name of the health information user. Allows alpha numeric and special characters like "^[a-zA-Z]+[A-Za-z0-9_\\-@,().\\s\\xa0:/]+"
  - `hiu.type` (string): The type of the health information user. Allows alpha numeric and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
  - `careContexts` (object[]): List of care contexts linked at the HIP end for the identified patient.
  - `careContexts.patientReference` (string, required): A patient identifier with which patient is registered in the facility/hospital
  - `careContexts.careContextReference` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data)
  - `requester` (object)
  - `requester.name` (string, required): The name of the requester
  - `requester.identifier` (object, required)
  - `requester.identifier.value` (string, required): The type of the identification. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
  - `requester.identifier.type` (string, required): The identification value. Allows alpha numeric character and special characters like  "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
  - `requester.identifier.system` (string, required): Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
  - `status` (string) One of: REQUESTED, EXPIRED, DENIED, GRANTED, REVOKED.
  - `createdAt` (string)
  - `lastUpdated` (string)
  - `hiType` (string[])
  - `permission` (object)
  - `permission.accessMode` (string, required) One of: VIEW, STORE, STREAM, QUERY.
  - `permission.dateRange` (object, required)
  - `permission.dateRange.from` (string, required): Should be UTC date time in ISO format
  - `permission.dateRange.to` (string, required): Should be UTC date time in ISO format
  - `permission.dataEraseAt` (string, required): The date at which the consent expire. Should be UTC date time in ISO format
  - `permission.frequency` (object, required)
  - `permission.frequency.unit` (string, required) One of: HOUR, DAY, WEEK, MONTH, YEAR.
  - `permission.frequency.value` (number, required): The frequency unit value. Should be be a integer
  - `permission.frequency.repeats` (number, required): Should be be a integer
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1039 - Invalid Consent request id. May be returned either bare (`ABDM-1039`) or with a trailing ": " separator (`ABDM-1039: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "requestId": "e5ec415f-c098-40f6-a0db-faa162fc5295",
  "purpose": {
    "text": "Care Management",
    "code": "CAREMGT",
    "refUri": "www.abc.com"
  },
  "patient": {
    "id": "<ABHA_ADDRESS>"
  },
  "hip": {
    "id": "cowin_hip_01",
    "name": "Cowin",
    "type": "HIP"
  },
  "hiu": {
    "id": "cowin_hiu_01",
    "name": "Cowin",
    "type": "HIU"
  },
  "careContexts": [
    {
      "patientReference": "batman@tmh",
      "careContextReference": "Episode1"
    }
  ],
  "requester": {
    "name": "<ABHA_ADDRESS>",
    "identifier": {
      "value": "REG1",
      "type": "MH1001",
      "system": "https://www.sample.com"
    }
  },
  "status": "GRANTED",
  "createdAt": "2021-09-28T12:30:08.573Z",
  "lastUpdated": "2021-09-28T12:30:08.573Z",
  "hiType": [
    "Prescription"
  ],
  "permission": {
    "accessMode": "VIEW",
    "dateRange": {
      "from": "2021-09-28T12:30:08.573Z",
      "to": "2021-09-28T12:30:08.573Z"
    },
    "dataEraseAt": "2021-09-28T12:30:08.573Z",
    "frequency": {
      "unit": "HOUR",
      "value": 1,
      "repeats": 0
    }
  }
}
```


---

# Approve the consent request raised by HIU from PHR/mobile application

`POST /api/hiecm/consent/v3/request/{consentRequestId}/approve`

Approve a consent request, specifying their preferred data access parameters. By invoking this API, the user grants permission for the Health Information User (HIU) to access their health data under the defined conditions. This approval process is essential for ensuring that patient data is shared securely and in accordance with the user’s preferences, supporting a transparent and compliant health information exchange. The API facilitates the establishment of trust and adherence to privacy regulations, enabling ethical and efficient access to health information.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/request/{consentRequestId}/approve \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "consents": [
    {
      "hiTypes": [
        "Prescription"
      ],
      "hip": {
        "id": "ABCD_12345",
        "name": "ABCD Hospital",
        "type": "HIP"
      },
      "careContexts": [
        {
          "patientReference": "batman@tmh",
          "careContextReference": "Episode1"
        }
      ],
      "permission": {
        "dateRange": {
          "from": "2021-09-28T12:30:08.573Z",
          "to": "2021-09-28T12:30:08.573Z"
        },
        "frequency": {
          "unit": "HOUR",
          "value": 1,
          "repeats": 0
        },
        "accessMode": "VIEW",
        "dataEraseAt": "2021-09-28T12:30:08.573Z"
      }
    }
  ]
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): The user token the PHR service issued when the patient logged in.

## Path parameters

- `consentRequestId` (string, required): The consent request id

## Body

- `consents` (object[], required)
- `consents.hiTypes` (string[], required): Types of health information document.
- `consents.hip` (object, required): Identifier and name of the health information provider.
- `consents.hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like[A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `consents.hip.name` (string, required): The name of the health information provider. Allows alpha numeric and special characters like "^[a-zA-Z]+[A-Za-z0-9_\\-@,().\\s\\xa0:/]+"
- `consents.hip.type` (string): The type of the health information provider. Allows alpha numeric and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `consents.careContexts` (object[], required): List of care contexts linked at the HIP end for the identified patient.
- `consents.careContexts.patientReference` (string, required): A patient identifier with which patient is registered in the facility/hospital. Allows alpha numeric character and special characters like ^[a-zA-Z0-9_\\-@,. \":/]{0,255}$
- `consents.careContexts.careContextReference` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data). Allows alpha numeric character and special characters like ^[a-zA-Z0-9_\\-@,().\"/:| ]{0,255}$
- `consents.permission` (object, required)
- `consents.permission.dateRange` (object, required)
- `consents.permission.dateRange.from` (string, required): Should be UTC date time in ISO format. Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `consents.permission.dateRange.to` (string, required): Should be UTC date time in ISO format. Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `consents.permission.frequency` (object, required)
- `consents.permission.frequency.unit` (string, required) One of: HOUR, DAY, WEEK, MONTH, YEAR.
- `consents.permission.frequency.value` (number, required): The frequency unit value. Should be be a integer.Allows alpha numeric character and special characters like ^[a-zA-Z0-9_\\-@,. \":/]{0,255}$
- `consents.permission.frequency.repeats` (number, required): Should be be a integer
- `consents.permission.accessMode` (string, required) One of: VIEW, STORE, STREAM, QUERY.
- `consents.permission.dataEraseAt` (string, required): The date at which the consent expire. Should be UTC date time in ISO format. Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
  - `message` (string)
  - `consentIds` (object[])
  - `consentIds.id` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 202 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "message": "Successful creation of consent artefact.",
  "consentIds": [
    {
      "id": "f29f0e59-8388-4698-9fe6-05db67aeac46"
    }
  ]
}
```


---

# Deny the consent request raised by HIU from PHR/mobile application

`POST /api/hiecm/consent/v3/request/{consentRequestId}/deny`

Deny a consent request from the Personal Health Record (PHR) or mobile application. By invoking this API, users can reject a consent request, preventing the Health Information User (HIU) from accessing their health data. This functionality is essential for maintaining user control over their health information, ensuring that consents are managed according to the user’s preferences. The API supports secure and compliant health information exchange, enabling users to deny consent requests as needed.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/request/{consentRequestId}/deny \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "reason": "Not authorized"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): The user token the PHR service issued when the patient logged in.

## Path parameters

- `consentRequestId` (string, required): The consent request id

## Body

- `reason` (string, required): The reason to deny the consent request. Allows alpha numeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{1,255}$"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1065 - Invalid X Auth token. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Revoke the granted consent from PHR/mobile application

`POST /api/hiecm/consent/v3/revoke`

Revoke a previously approved consent from the Personal Health Record (PHR) or mobile application. By invoking this API, users can withdraw their consent, thereby terminating the permissions granted to access their health data. This functionality is essential for maintaining user control over their health information, ensuring that consents can be managed dynamically and in accordance with the user’s preferences. The API supports secure and compliant health information exchange, enabling users to revoke consent as needed.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/revoke \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "consents": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ]
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): The user token the PHR service issued when the patient logged in.

## Body

- `consents` (string[], required)

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1080 - Invalid Consent artefact id. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 202 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "message": "Successful revocation of list of consents."
}
```


---

# Request artefact by consent REQUEST-ID

`GET /api/hiecm/consent/v3/artefact/request/{consentRequestId}`

Fetch all consent artefact details associated with a specific consent REQUEST-ID. By invoking this API, users can retrieve comprehensive information about all consent artefacts linked to the given REQUEST-ID, including their status, scope, and any associated conditions. This functionality is essential for ensuring that users have access to accurate and up-to-date consent artefact information, supporting secure and compliant health information exchange. The API facilitates efficient management and verification of consent artefacts, enhancing the overall integrity of the consent management process.

```bash
curl --request GET \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/artefact/request/{consentRequestId} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): The user token the PHR service issued when the patient logged in.

## Path parameters

- `consentRequestId` (string, required): Consent request id

## Responses

- `200`: Ok
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
[
  {
    "status": "GRANTED",
    "consentDetail": {
      "consentId": "e5ec415f-c098-40f6-a0db-faa162fc5295",
      "purpose": {
        "text": "Care Management",
        "code": "CAREMGT",
        "refUri": "www.abc.com"
      },
      "patient": {
        "id": "<ABHA_ADDRESS>"
      },
      "hip": {
        "id": "cowin_hip_01",
        "name": "Cowin",
        "type": "HIP"
      },
      "hiu": {
        "id": "cowin_hiu_01",
        "name": "Cowin",
        "type": "HIU"
      },
      "careContexts": [
        {
          "patientReference": "batman@tmh",
          "careContextReference": "Episode1"
        }
      ],
      "requester": {
        "name": "<ABHA_ADDRESS>",
        "identifier": {
          "value": "REG1",
          "type": "MH1001",
          "system": "https://www.sample.com"
        }
      },
      "createdAt": "2021-09-28T12:30:08.573Z",
      "lastUpdated": "2021-09-28T12:30:08.573Z",
      "schemaVersion": "v3",
      "consentManager": {
        "id": "abdm"
      },
      "hiTypes": [
        "Prescription"
      ],
      "permission": {
        "accessMode": "VIEW",
        "dateRange": {
          "from": "2021-09-28T12:30:08.573Z",
          "to": "2021-09-28T12:30:08.573Z"
        },
        "dataEraseAt": "2021-09-28T12:30:08.573Z",
        "frequency": {
          "unit": "HOUR",
          "value": 1,
          "repeats": 0
        }
      }
    },
    "signature": "Signature of CM as defined in W3C standards; Base64 encoded"
  }
]
```


---

# Fetch the consent artefact details associated with the artefact-ID

`GET /api/hiecm/consent/v3/artefact/{consentId}`

Fetch the details of a consent artefact associated with a specific artefact ID. By invoking this API, users can retrieve comprehensive information about the consent artefact, including its status, scope, and any associated conditions. This functionality is essential for ensuring that users have access to accurate and up-to-date consent artefact information, supporting secure and compliant health information exchange. The API facilitates efficient management and verification of consent artefacts, enhancing the overall integrity of the consent management process.

```bash
curl --request GET \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/artefact/{consentId} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): The user token the PHR service issued when the patient logged in.

## Path parameters

- `consentId` (string, required): Consent artefact id

## Responses

- `200`: Ok
  - `status` (string, required) One of: GRANTED, DENIED, EXPIRED, REVOKED.
  - `consentDetail` (object, required)
  - `consentDetail.consentId` (string): Allows alpha numeric character and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$";
  - `consentDetail.purpose` (object, required)
  - `consentDetail.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
  - `consentDetail.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
  - `consentDetail.purpose.refUri` (string, required): The reference URL. Should be a valid URL
  - `consentDetail.patient` (object, required)
  - `consentDetail.patient.id` (string, required): The abha address of the patient
  - `consentDetail.hip` (object): Identifier and name of the health information provider.
  - `consentDetail.hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
  - `consentDetail.hip.name` (string, required): The name of the health information provider. Allows alpha numeric and special characters like _\-@,():/
  - `consentDetail.hip.type` (string): The type of the health information provider. Allows alpha numeric and special characters like _\-@,. ":/
  - `consentDetail.hiu` (object, required)
  - `consentDetail.hiu.id` (string, required): The service ID of the health information user.  Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
  - `consentDetail.hiu.name` (string, required): The name of the health information user. Allows alpha numeric and special characters like _\-@,():/
  - `consentDetail.hiu.type` (string): The type of the health information user. Allows alpha numeric and special characters like _\-@,. ":/
  - `consentDetail.careContexts` (object[]): List of care contexts linked at the HIP end for the identified patient.
  - `consentDetail.careContexts.patientReference` (string, required): A patient identifier with which patient is registered in the facility/hospital
  - `consentDetail.careContexts.careContextReference` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data)
  - `consentDetail.requester` (object, required)
  - `consentDetail.requester.name` (string, required): The name of the requester
  - `consentDetail.requester.identifier` (object, required)
  - `consentDetail.requester.identifier.value` (string, required): The type of the identification. Allows alpha numeric character and special characters like _\-@,. ":/
  - `consentDetail.requester.identifier.type` (string, required): The identification value. Allows alpha numeric character and special characters like _\-@,. ":/
  - `consentDetail.requester.identifier.system` (string, required): Allows alpha numeric character and special characters like _\-@,. ":/
  - `consentDetail.createdAt` (string)
  - `consentDetail.lastUpdated` (string)
  - `consentDetail.schemaVersion` (string)
  - `consentDetail.consentManager` (object)
  - `consentDetail.consentManager.id` (string)
  - `consentDetail.hiTypes` (string[], required): Types of health information document.
  - `consentDetail.permission` (object, required)
  - `consentDetail.permission.accessMode` (string, required) One of: VIEW, STORE, STREAM, QUERY.
  - `consentDetail.permission.dateRange` (object, required)
  - `consentDetail.permission.dateRange.from` (string, required): Should be UTC date time in ISO format
  - `consentDetail.permission.dateRange.to` (string, required): Should be UTC date time in ISO format
  - `consentDetail.permission.dataEraseAt` (string, required): The date at which the consent expire. Should be UTC date time in ISO format
  - `consentDetail.permission.frequency` (object, required)
  - `consentDetail.permission.frequency.unit` (string, required) One of: HOUR, DAY, WEEK, MONTH, YEAR.
  - `consentDetail.permission.frequency.value` (number, required): The frequency unit value. Should be be a integer
  - `consentDetail.permission.frequency.repeats` (number, required): Should be be a integer
  - `signature` (string, required)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1080 - Invalid Consent artefact id. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "status": "GRANTED",
  "consentDetail": {
    "consentId": "e5ec415f-c098-40f6-a0db-faa162fc5295",
    "purpose": {
      "text": "Care Management",
      "code": "CAREMGT",
      "refUri": "www.abc.com"
    },
    "patient": {
      "id": "<ABHA_ADDRESS>"
    },
    "hip": {
      "id": "cowin_hip_01",
      "name": "Cowin",
      "type": "HIP"
    },
    "hiu": {
      "id": "cowin_hiu_01",
      "name": "Cowin",
      "type": "HIU"
    },
    "careContexts": [
      {
        "patientReference": "batman@tmh",
        "careContextReference": "Episode1"
      }
    ],
    "requester": {
      "name": "<ABHA_ADDRESS>",
      "identifier": {
        "value": "REG1",
        "type": "MH1001",
        "system": "https://www.sample.com"
      }
    },
    "createdAt": "2021-09-28T12:30:08.573Z",
    "lastUpdated": "2021-09-28T12:30:08.573Z",
    "schemaVersion": "v3",
    "consentManager": {
      "id": "abdm"
    },
    "hiTypes": [
      "Prescription"
    ],
    "permission": {
      "accessMode": "VIEW",
      "dateRange": {
        "from": "2021-09-28T12:30:08.573Z",
        "to": "2021-09-28T12:30:08.573Z"
      },
      "dataEraseAt": "2021-09-28T12:30:08.573Z",
      "frequency": {
        "unit": "HOUR",
        "value": 1,
        "repeats": 0
      }
    }
  },
  "signature": "Signature of CM as defined in W3C standards; Base64 encoded"
}
```


---

# Fetch all the consent artefact details of a patient

`GET /api/hiecm/consent/v3/artefact`

Fetch all consent artefact details for a patient. By invoking this API, users can retrieve comprehensive information about all consent artefacts associated with the patient’s health information. This functionality is essential for maintaining transparency and ensuring that users have access to complete and up-to-date consent artefact information. The API supports efficient tracking and management of consent artefacts, facilitating secure and compliant health information exchange within the healthcare ecosystem.

```bash
curl --request GET \
  --url "https://dev.abdm.gov.in/api/hiecm/consent/v3/artefact?limit=<LIMIT>" \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for tracking the end-to-end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds, and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): The user token the PHR service issued when the patient logged in.

## Query parameters

- `limit` (integer, required): The number of items to be returned at a time
- `offset` (integer): The number of items to be skipped before starting to collect data
- `status` (string): Status of the consent

## Responses

- `200`: Ok
  - `size` (integer)
  - `limit` (integer)
  - `offset` (integer)
  - `consentArtefacts` (object[]): List of consent artefact ids that were created.
  - `consentArtefacts.status` (string) One of: GRANTED, EXPIRED, REVOKED.
  - `consentArtefacts.consentDetail` (object)
  - `consentArtefacts.consentDetail.consentId` (string): Allows alpha numeric character and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$";
  - `consentArtefacts.consentDetail.purpose` (object, required)
  - `consentArtefacts.consentDetail.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
  - `consentArtefacts.consentDetail.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
  - `consentArtefacts.consentDetail.purpose.refUri` (string, required): The reference URL. Should be a valid URL
  - `consentArtefacts.consentDetail.patient` (object, required)
  - `consentArtefacts.consentDetail.patient.id` (string, required): The abha address of the patient
  - `consentArtefacts.consentDetail.hip` (object): Identifier and name of the health information provider.
  - `consentArtefacts.consentDetail.hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
  - `consentArtefacts.consentDetail.hip.name` (string, required): The name of the health information provider. Allows alpha numeric and special characters like _\-@,():/
  - `consentArtefacts.consentDetail.hip.type` (string): The type of the health information provider. Allows alpha numeric and special characters like _\-@,. ":/
  - `consentArtefacts.consentDetail.hiu` (object, required)
  - `consentArtefacts.consentDetail.hiu.id` (string, required): The service ID of the health information user. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
  - `consentArtefacts.consentDetail.hiu.name` (string, required): The name of the health information user. Allows alpha numeric and special characters like _\-@,():/
  - `consentArtefacts.consentDetail.hiu.type` (string): The type of the health information user. Allows alpha numeric and special characters like _\-@,. ":/
  - `consentArtefacts.consentDetail.careContexts` (object[]): List of care contexts linked at the HIP end for the identified patient.
  - `consentArtefacts.consentDetail.careContexts.patientReference` (string, required): A patient identifier with which patient is registered in the facility/hospital
  - `consentArtefacts.consentDetail.careContexts.careContextReference` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data)
  - `consentArtefacts.consentDetail.requester` (object, required)
  - `consentArtefacts.consentDetail.requester.name` (string, required): The name of the requester
  - `consentArtefacts.consentDetail.requester.identifier` (object, required)
  - `consentArtefacts.consentDetail.createdAt` (string)
  - `consentArtefacts.consentDetail.lastUpdated` (string)
  - `consentArtefacts.consentDetail.schemaVersion` (string)
  - `consentArtefacts.consentDetail.consentManager` (object)
  - `consentArtefacts.consentDetail.consentManager.id` (string)
  - `consentArtefacts.consentDetail.hiTypes` (string[], required): Types of health information document.
  - `consentArtefacts.consentDetail.permission` (object, required)
  - `consentArtefacts.consentDetail.permission.accessMode` (string, required) One of: VIEW, STORE, STREAM, QUERY.
  - `consentArtefacts.consentDetail.permission.dateRange` (object, required)
  - `consentArtefacts.consentDetail.permission.dataEraseAt` (string, required): The date at which the consent expire. Should be UTC date time in ISO format
  - `consentArtefacts.consentDetail.permission.frequency` (object, required)
  - `consentArtefacts.signature` (string)
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "size": 10,
  "limit": 10,
  "offset": 0,
  "consentArtefacts": [
    {
      "status": "GRANTED",
      "consentDetail": {
        "consentId": "e5ec415f-c098-40f6-a0db-faa162fc5295",
        "purpose": {
          "text": "Care Management",
          "code": "CAREMGT",
          "refUri": "www.abc.com"
        },
        "patient": {
          "id": "<ABHA_ADDRESS>"
        },
        "hip": {
          "id": "cowin_hip_01",
          "name": "Cowin",
          "type": "HIP"
        },
        "hiu": {
          "id": "cowin_hiu_01",
          "name": "Cowin",
          "type": "HIU"
        },
        "careContexts": [
          {
            "patientReference": "batman@tmh",
            "careContextReference": "Episode1"
          }
        ],
        "requester": {
          "name": "<ABHA_ADDRESS>",
          "identifier": {
            "value": "REG1",
            "type": "MH1001",
            "system": "https://www.sample.com"
          }
        },
        "createdAt": "2021-09-28T12:30:08.573Z",
        "lastUpdated": "2021-09-28T12:30:08.573Z",
        "schemaVersion": "v3",
        "consentManager": {
          "id": "abdm"
        },
        "hiTypes": [
          "Prescription"
        ],
        "permission": {
          "accessMode": "VIEW",
          "dateRange": {
            "from": "2021-09-28T12:30:08.573Z",
            "to": "2021-09-28T12:30:08.573Z"
          },
          "dataEraseAt": "2021-09-28T12:30:08.573Z",
          "frequency": {
            "unit": "HOUR",
            "value": 1,
            "repeats": 0
          }
        }
      },
      "signature": "e8nY601CYDsC0FKoDjSp+7GeQ2s2R8oZncLCz5ce+pEuDOr5bZV0aaHjwJg4b9S9V+twjt4hbojx3fl7egrt8+0c+lfPTi5/bBUAQXCABTfFmtFU7jn65HlTt8kgkiONx26ZBhJ0wX3xjYI72PPtzYIiT5Q08YtDoILA62KceioV7lwuKssw7wC4ECbBAvRuXT121TmtrPhf+0myJATSnaajS06S6OthrKfZLNTUFf3pFiJzqouSTrjNblOX6DT2+JuO3rom1Szz/03c0HQG+wWASv+PO3J6uRs0UI4JvKmM/4tP+Z+/HPKM15K5U5K+4pqf6czKrbIDpkT/kP8bGg=="
    }
  ]
}
```


---

# Link patient links

`GET /api/hiecm/hip/v3/link/patient/links`

Retrieve all linked care contexts for a patient from various Health Information Providers (HIPs). By invoking this API, users can obtain a comprehensive list of care contexts associated with a patient’s ABHA (Ayushman Bharat Health Account) address. This functionality is essential for ensuring that all relevant health records are accessible and consolidated, thereby supporting coordinated and efficient patient care. The API facilitates seamless health information exchange, enhancing the overall quality and continuity of care within the healthcare ecosystem.

```bash
curl --request GET \
  --url "https://dev.abdm.gov.in/api/hiecm/hip/v3/link/patient/links?limit=<LIMIT>" \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <X_AUTH_TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Query parameters

- `limit` (integer, required): Limit the number of records returned. Send -1 to get all the links of the patient.

## Responses

- `200`: OK
  - `Patient` (object)
  - `Patient.id` (string, required)
  - `Patient.links` (object[], required)
  - `Patient.links.hip` (object): Identifier and name of the health information provider.
  - `Patient.links.hip.id` (string)
  - `Patient.links.hip.name` (string)
  - `Patient.links.hip.type` (string)
  - `Patient.links.referenceNumber` (string): Reference number used while linking the health records of the patient.
  - `Patient.links.display` (string): Displayed information about the care context.
  - `Patient.links.hiType` (string) One of: DiagnosticReport, DischargeSummary, HealthDocumentRecord, ImmunizationRecord, OPConsultation, Prescription, WellnessRecord, Invoice.
  - `Patient.links.careContexts` (object[]): List of care contexts linked at the HIP end for the identified patient.
  - `Patient.links.careContexts.referenceNumber` (string): Reference number used while linking the health records of the patient.
  - `Patient.links.careContexts.display` (string): Displayed information about the care context.
  - `Patient.links.dateCreated` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1065 - Invalid X Auth token. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900902 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `message` (string)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "Patient": {
    "id": "<ABHA_ADDRESS>",
    "links": [
      {
        "hip": {
          "id": "ABDM_HIP",
          "name": "ABC Hospital",
          "type": "HIP"
        },
        "referenceNumber": "string",
        "display": "string",
        "hiType": "DiagnosticReport",
        "careContexts": [
          {
            "referenceNumber": "TMH-PUID-001",
            "display": "display 1"
          }
        ],
        "dateCreated": "2024-05-09T10:34:00.387Z"
      }
    ]
  }
}
```


---

# Initiate the consent request

`POST /api/hiecm/consent/v3/request/init`

Create a consent request by a Health Information User (HIU) to access a patient’s health data. By invoking this API, the HIU initiates the process of obtaining the necessary permissions from the patient to retrieve their health information. This consent request is a critical component of the health information exchange framework, ensuring that patient data is accessed in a secure, authorised, and transparent manner. The API supports the establishment of trust and compliance with privacy regulations, facilitating seamless and ethical health information exchange.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/request/init \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "consent": {
    "purpose": {
      "text": "Care Management",
      "code": "CAREMGT",
      "refUri": "www.abc.com"
    },
    "patient": {
      "id": "<ABHA_ADDRESS>"
    },
    "hip": null,
    "hiu": {
      "id": "cowin_hiu_01"
    },
    "careContexts": [
      {
        "patientReference": "batman@tmh",
        "careContextReference": "Episode1"
      }
    ],
    "requester": {
      "name": "<ABHA_ADDRESS>",
      "identifier": {
        "value": "REG1",
        "type": "MH1001",
        "system": "https://www.sample.com"
      }
    },
    "hiTypes": [
      "Prescription"
    ],
    "permission": {
      "accessMode": "VIEW",
      "dateRange": {
        "from": "2021-09-28T12:30:08.573Z",
        "to": "2021-09-28T12:30:08.573Z"
      },
      "dataEraseAt": "2021-09-28T12:30:08.573Z",
      "frequency": {
        "unit": "HOUR",
        "value": 1,
        "repeats": 0
      }
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `consent` (object, required)
- `consent.purpose` (object, required)
- `consent.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
- `consent.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
- `consent.purpose.refUri` (string, required): The reference URL. Should be a valid URL. Allow alpha numeric characters and special charactes like  "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `consent.patient` (object, required)
- `consent.patient.id` (string, required): The abha address of the patient. It must start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx. Allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.\-!]+[a-zA-Z0-9]@(abdm|sbx)$
- `consent.hip` (object): Identifier and name of the health information provider.
- `consent.hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `consent.hip.name` (string): The name of the health information provider. Allows alpha numeric and special characters like "^[a-zA-Z]+[A-Za-z0-9_\\-@,().\\s\\xa0:/]+"
- `consent.hip.type` (string): The type of the health information provider. Allows alpha numeric and special characters like  "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `consent.hiu` (object, required)
- `consent.hiu.id` (string, required): The service ID of the health information user.  Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `consent.hiu.name` (string): The name of the health information user. Allows alpha numeric and special characters like "^[a-zA-Z]+[A-Za-z0-9_\\-@,().\\s\\xa0:/]+"
- `consent.hiu.type` (string): The type of the health information user. Allows alpha numeric and special characters like  "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `consent.careContexts` (object[]): List of care contexts linked at the HIP end for the identified patient.
- `consent.careContexts.patientReference` (string, required): A patient identifier with which patient is registered in the facility/hospital like abhaAddress @sbx. Allows alpha numeric and special characters like "^[a-zA-Z0-9_\\-@,().\"/: ]{0,255}$"
- `consent.careContexts.careContextReference` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data). Allows alpha numeric and special characters like  "^[a-zA-Z0-9_\\-@,().\"/:| ]{0,255}$"
- `consent.requester` (object, required)
- `consent.requester.name` (string, required): The name of the requester
- `consent.requester.identifier` (object, required)
- `consent.requester.identifier.value` (string, required): The type of the identification. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `consent.requester.identifier.type` (string, required): The identification value. Allows alpha numeric character and special characters like  "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `consent.requester.identifier.system` (string, required): Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `consent.hiTypes` (string[], required): Types of health information document.
- `consent.permission` (object, required)
- `consent.permission.accessMode` (string, required) One of: VIEW, STORE, STREAM, QUERY.
- `consent.permission.dateRange` (object, required)
- `consent.permission.dateRange.from` (string, required): Should be UTC date time in ISO format. Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `consent.permission.dateRange.to` (string, required): Should be UTC date time in ISO format. Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `consent.permission.dataEraseAt` (string, required): The date at which the consent expire. Should be UTC.  Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$" date time in ISO format
- `consent.permission.frequency` (object, required)
- `consent.permission.frequency.unit` (string, required) One of: HOUR, DAY, WEEK, MONTH, YEAR.
- `consent.permission.frequency.value` (number, required): The frequency unit value. Should be be a integer
- `consent.permission.frequency.repeats` (number, required): Should be be a integer

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Get consent request status

`POST /api/hiecm/consent/v3/request/status`

Retrieve the status of a previously initiated consent request. By invoking this API, users can check the current state of their consent request, whether it is pending, approved, denied, or expired. This functionality is essential for maintaining transparency and keeping users informed about the progress of their consent requests. The API supports efficient tracking and management of consent, ensuring that health information exchange processes are conducted in a secure and compliant manner.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/request/status \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "consentRequestId": "5f7a535d-a3fd-416b-b069-c97d021fbacd"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `consentRequestId` (string, required): The consent request id from a consent. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Acknowledge the consent notification

`POST /api/hiecm/consent/v3/request/hip/on-notify`

Notification of consents, in cases of consent approval, revocation and expiration. Notified by CM earlier via Gateway API - **/api/v3/consent/request/hip/notify**

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/request/hip/on-notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "acknowledgement": {
    "status": "OK",
    "consentId": "e3c74829-3f82-4f94-959e-e10f57bcd57b"
  },
  "response": {
    "requestId": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `acknowledgement` (object, required)
- `acknowledgement.status` (string, required): The status of the notification.  Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `acknowledgement.consentId` (string, required): The consent artefact id. Should be valid UUID. Allows alpha numeric character and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$";
- `error` (object): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message
- `response` (object, required): The request id is from the /consent/request/hip/notify callback
- `response.requestId` (string, required): The requestId that was passed. it must be in Alpha numeric and - in middle and Allows alpha numeric character and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m2/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Acknowledge the consent notification

`POST /api/hiecm/consent/v3/request/hiu/on-notify`

Consent notifications, specifically for cases when consent is APPROVED, DENIED, or REVOKED or EXPIRED. Notified by CM earlier via Gateway API - **/api/v3/hiu/consent/request/notify**

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/request/hiu/on-notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "acknowledgement": [
    {
      "status": "OK",
      "consentId": "e3c74829-3f82-4f94-959e-e10f57bcd57b"
    }
  ],
  "error": {
    "code": "ABDM-1001",
    "message": "unable to connect database"
  },
  "response": {
    "requestId": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `acknowledgement` (object[], required)
- `acknowledgement.status` (string, required): The status of the notification. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
- `acknowledgement.consentId` (string, required): The consent artefact id. Should be valid UUID. Allows alpha numeric character and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$"
- `error` (object): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message
- `response` (object, required): The request id is from the /hiu/consent/request/notify callback
- `response.requestId` (string, required): The requestId that was passed. it must be in Alpha numeric and - in middle and Allows alpha numeric character and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Fetch the consent details

`POST /api/hiecm/consent/v3/fetch`

Fetch the details of a consent using the consent artefact ID. By invoking this API, HIUs can retrieve comprehensive information about a specific consent, including its status, scope, and any associated conditions. This functionality is essential for ensuring that HIUs have access to accurate and up-to-date consent information, supporting secure and compliant health information exchange. The API facilitates efficient management and verification of consents, enhancing the overall integrity of the consent management process.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/consent/v3/fetch \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "consentId": "5f7a535d-a3fd-416b-b069-c97d021fbacd"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `consentId` (string, required): The id of the consent artefact that needs to be fetched. Allows alpha numeric character and special characters like "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Unauthorized. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/m3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Request profile OTP

`POST /abha/api/v3/phr/app/login/profile/request/otp`

Flows:
- P2-Consents Management › P2 -PHR Profile › P2 - Update Mobile › Send OTP - Update Mobile
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via ABHA OTP › Send ABHA OTP - Link-DeLink
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via Aadhaar OTP › Send Aadhaar OTP - Link-DeLink

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-verify"
  ],
  "loginHint": "abha-number",
  "loginId": "<ENCRYPTED_LOGIN_ID>",
  "otpSystem": "aadhaar"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): The user token from a login or enrolment response, sent with a `Bearer ` prefix. It acts for that ABHA holder.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `loginHint` (string, required)
- `loginId` (string, required)
- `otpSystem` (string, required)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "d01cebdf-95f5-480c-8289-6f3b218e7248",
  "message": "OTP is sent to Mobile number ending with ******2425"
}
```


---

# Login profile verify

`POST /abha/api/v3/phr/app/login/profile/verify`

Flows:
- P2-Consents Management › P2 -PHR Profile › P2 - Update Mobile › Verify OTP - Update Mobile
- P2-Consents Management › P2 -PHR Profile › P2 - Update Password › Verify Password - Update Password
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via ABHA OTP › Verify ABHA OTP - Link-DeLink
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via Aadhaar OTP › Verify Aadhaar OTP - Link-DeLink

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
      "otpValue": "<ENCRYPTED_OTP_VALUE>"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): The user token from a login or enrolment response, sent with a `Bearer ` prefix. It acts for that ABHA holder.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `authData` (object, required)
- `authData.authMethods` (string[])
- `authData.otp` (object)
- `authData.otp.txnId` (string)
- `authData.otp.otpValue` (string)
- `authData.password` (object)
- `authData.password.abhaAddress` (string)
- `authData.password.password` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `accounts` (object[])
  - `accounts.mobile` (string)
  - `accounts.firstName` (string)
  - `accounts.middleName` (string)
  - `accounts.lastName` (string)
  - `accounts.name` (string)
  - `accounts.yearOfBirth` (string)
  - `accounts.dayOfBirth` (string)
  - `accounts.monthOfBirth` (string)
  - `accounts.gender` (string)
  - `accounts.email` (object)
  - `accounts.profilePhoto` (string)
  - `accounts.status` (string)
  - `accounts.stateCode` (string)
  - `accounts.districtCode` (string)
  - `accounts.subDistrictCode` (object)
  - `accounts.villageCode` (object)
  - `accounts.townCode` (object)
  - `accounts.wardCode` (object)
  - `accounts.pincode` (string)
  - `accounts.address` (string)
  - `accounts.kycPhoto` (string)
  - `accounts.stateName` (string)
  - `accounts.districtName` (string)
  - `accounts.subdistrictName` (string)
  - `accounts.villageName` (object)
  - `accounts.townName` (string)
  - `accounts.wardName` (object)
  - `accounts.authMethods` (string[])
  - `accounts.tags` (object)
  - `accounts.kycVerified` (boolean)
  - `accounts.verificationStatus` (string)
  - `accounts.verificationType` (string)
  - `accounts.emailVerified` (object)
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "e10ca603-97f5-4cf2-8191-d51ea7db3845",
  "message": "Entered OTP is incorrect. Kindly re-enter valid OTP.",
  "authResult": "failed",
  "users": []
}
```


---

# Link request

`POST /abha/api/v3/phr/app/login/profile/link`

Flows:
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via ABHA OTP › Link Request
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via Aadhaar OTP › Link Request

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile/link \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "action": "LINK",
  "transactionId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): The user token from a login or enrolment response, sent with a `Bearer ` prefix. It acts for that ABHA holder.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `action` (string, required)
- `transactionId` (string, required)

## Responses

- `200`: OK
  - `message` (string)
  - `authResult` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string)
  - `message` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors

Example 200 response. The values are placeholders:

```json
{
  "message": "ABHA number is securely linked to ABHA address",
  "authResult": "success"
}
```


---

# Request profile OTP

`POST /abha/api/v3/phr/app/login/profile/request/otp`

Flows:
- P2-Consents Management › P2 -PHR Profile › P2 - Update Mobile › Send OTP - Update Mobile
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via ABHA OTP › Send ABHA OTP - Link-DeLink
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via Aadhaar OTP › Send Aadhaar OTP - Link-DeLink

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "mobile-verify"
  ],
  "loginHint": "abha-number",
  "loginId": "<ENCRYPTED_LOGIN_ID>",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): The user token from a login or enrolment response, sent with a `Bearer ` prefix. It acts for that ABHA holder.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `loginHint` (string, required)
- `loginId` (string, required)
- `otpSystem` (string, required)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "d01cebdf-95f5-480c-8289-6f3b218e7248",
  "message": "OTP is sent to Mobile number ending with ******2425"
}
```


---

# Login profile verify

`POST /abha/api/v3/phr/app/login/profile/verify`

Flows:
- P2-Consents Management › P2 -PHR Profile › P2 - Update Mobile › Verify OTP - Update Mobile
- P2-Consents Management › P2 -PHR Profile › P2 - Update Password › Verify Password - Update Password
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via ABHA OTP › Verify ABHA OTP - Link-DeLink
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via Aadhaar OTP › Verify Aadhaar OTP - Link-DeLink

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
      "otpValue": "{{encryptedData}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): The user token from a login or enrolment response, sent with a `Bearer ` prefix. It acts for that ABHA holder.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `authData` (object, required)
- `authData.authMethods` (string[])
- `authData.otp` (object)
- `authData.otp.txnId` (string)
- `authData.otp.otpValue` (string)
- `authData.password` (object)
- `authData.password.abhaAddress` (string)
- `authData.password.password` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `accounts` (object[])
  - `accounts.mobile` (string)
  - `accounts.firstName` (string)
  - `accounts.middleName` (string)
  - `accounts.lastName` (string)
  - `accounts.name` (string)
  - `accounts.yearOfBirth` (string)
  - `accounts.dayOfBirth` (string)
  - `accounts.monthOfBirth` (string)
  - `accounts.gender` (string)
  - `accounts.email` (object)
  - `accounts.profilePhoto` (string)
  - `accounts.status` (string)
  - `accounts.stateCode` (string)
  - `accounts.districtCode` (string)
  - `accounts.subDistrictCode` (object)
  - `accounts.villageCode` (object)
  - `accounts.townCode` (object)
  - `accounts.wardCode` (object)
  - `accounts.pincode` (string)
  - `accounts.address` (string)
  - `accounts.kycPhoto` (string)
  - `accounts.stateName` (string)
  - `accounts.districtName` (string)
  - `accounts.subdistrictName` (string)
  - `accounts.villageName` (object)
  - `accounts.townName` (string)
  - `accounts.wardName` (object)
  - `accounts.authMethods` (string[])
  - `accounts.tags` (object)
  - `accounts.kycVerified` (boolean)
  - `accounts.verificationStatus` (string)
  - `accounts.verificationType` (string)
  - `accounts.emailVerified` (object)
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "e10ca603-97f5-4cf2-8191-d51ea7db3845",
  "message": "Entered OTP is incorrect. Kindly re-enter valid OTP.",
  "authResult": "failed",
  "users": []
}
```


---

# Link request

`POST /abha/api/v3/phr/app/login/profile/link`

Flows:
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via ABHA OTP › Link Request
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via Aadhaar OTP › Link Request

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile/link \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "action": "LINK",
  "transactionId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): The user token from a login or enrolment response, sent with a `Bearer ` prefix. It acts for that ABHA holder.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `action` (string, required)
- `transactionId` (string, required)

## Responses

- `200`: OK
  - `message` (string)
  - `authResult` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string)
  - `message` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors

Example 200 response. The values are placeholders:

```json
{
  "message": "ABHA number is securely linked to ABHA address",
  "authResult": "success"
}
```


---

# Get profile

`GET /abha/api/v3/phr/app/login/profile`

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-AUTH-TOKEN: <X_AUTH_TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): The user token from a login or enrolment response, sent with a `Bearer ` prefix. It acts for that ABHA holder.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.
- `X-AUTH-TOKEN` (string, required): The user token issued at login. Send it beside X-token.

## Responses

- `200`: OK
  - `abhaAddress` (string)
  - `fullName` (string)
  - `firstName` (string)
  - `middleName` (string)
  - `lastName` (string)
  - `dayOfBirth` (string)
  - `monthOfBirth` (string)
  - `yearOfBirth` (string)
  - `dateOfBirth` (string)
  - `gender` (string)
  - `email` (string)
  - `mobile` (string)
  - `abhaNumber` (string)
  - `address` (string)
  - `stateName` (string)
  - `districtName` (string)
  - `pinCode` (string)
  - `stateCode` (string)
  - `districtCode` (string)
  - `authMethods` (string[])
  - `status` (string)
  - `emailVerified` (string)
  - `mobileVerified` (string)
  - `kycStatus` (string)
  - `abhaLinkedCount` (string)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors

Example 200 response. The values are placeholders:

```json
{
  "abhaAddress": "<ABHA_ADDRESS>",
  "fullName": "John Doe",
  "firstName": "John",
  "middleName": "",
  "lastName": "Doe",
  "dayOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "yearOfBirth": "<DOB>",
  "dateOfBirth": "<DOB>",
  "gender": "M",
  "email": "<EMAIL>",
  "mobile": "******0903",
  "abhaNumber": "<ABHA_NUMBER>",
  "address": "<ADDRESS>",
  "stateName": "Maharashtra",
  "districtName": "<ADDRESS>",
  "pinCode": "<PINCODE>",
  "stateCode": "27",
  "districtCode": "123",
  "authMethods": [
    "MOBILE_OTP",
    "PASSWORD",
    "... 1 more of the same shape"
  ],
  "status": "ACTIVE",
  "emailVerified": "true",
  "mobileVerified": "true",
  "kycStatus": "VERIFIED",
  "abhaLinkedCount": "3"
}
```


---

# Get QR code

`GET /abha/api/v3/phr/app/login/profile/qrCode`

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile/qrCode \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-AUTH-TOKEN: <X_AUTH_TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): The user token from a login or enrolment response, sent with a `Bearer ` prefix. It acts for that ABHA holder.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.
- `X-AUTH-TOKEN` (string, required): The user token issued at login. Send it beside X-token.

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors


---

# Get PHR card

`GET /abha/api/v3/phr/app/login/profile/phrCard`

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile/phrCard \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-AUTH-TOKEN: <X_AUTH_TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): The user token from a login or enrolment response, sent with a `Bearer ` prefix. It acts for that ABHA holder.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.
- `X-AUTH-TOKEN` (string, required): The user token issued at login. Send it beside X-token.

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors


---

# Update profile

`POST /abha/api/v3/phr/app/login/profile/updateProfile`

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile/updateProfile \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "profilePhoto": "",
  "firstName": "John",
  "middleName": "",
  "lastName": "Doe",
  "dayOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "yearOfBirth": "<DOB>",
  "gender": "M",
  "email": "<EMAIL>",
  "mobile": "******0903",
  "address": "<ADDRESS>",
  "stateName": "Maharashtra",
  "districtName": "<ADDRESS>",
  "pinCode": "<PINCODE>",
  "stateCode": "27",
  "districtCode": "12"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): The user token from a login or enrolment response, sent with a `Bearer ` prefix. It acts for that ABHA holder.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `profilePhoto` (string, required)
- `firstName` (string, required)
- `middleName` (string, required)
- `lastName` (string, required)
- `dayOfBirth` (string, required)
- `monthOfBirth` (string, required)
- `yearOfBirth` (string, required)
- `gender` (string, required)
- `email` (string, required)
- `mobile` (string, required)
- `address` (string, required)
- `stateName` (string, required)
- `districtName` (string, required)
- `pinCode` (string, required)
- `stateCode` (string, required)
- `districtCode` (string, required)

## Responses

- `200`: OK
  - `abhaAddress` (string)
  - `fullName` (string)
  - `firstName` (string)
  - `middleName` (string)
  - `lastName` (string)
  - `dayOfBirth` (string)
  - `monthOfBirth` (string)
  - `yearOfBirth` (string)
  - `dateOfBirth` (string)
  - `gender` (string)
  - `email` (string)
  - `mobile` (string)
  - `abhaNumber` (string)
  - `address` (string)
  - `stateName` (string)
  - `districtName` (string)
  - `pinCode` (string)
  - `stateCode` (string)
  - `districtCode` (string)
  - `authMethods` (string[])
  - `status` (string)
  - `emailVerified` (string)
  - `mobileVerified` (string)
  - `kycStatus` (string)
  - `abhaLinkedCount` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors

Example 200 response. The values are placeholders:

```json
{
  "abhaAddress": "<ABHA_ADDRESS>",
  "fullName": "John Doe",
  "firstName": "John",
  "middleName": "",
  "lastName": "Doe",
  "dayOfBirth": "<DOB>",
  "monthOfBirth": "<DOB>",
  "yearOfBirth": "<DOB>",
  "dateOfBirth": "<DOB>",
  "gender": "M",
  "email": "",
  "mobile": "******0903",
  "abhaNumber": "<ABHA_NUMBER>",
  "address": "<ADDRESS>",
  "stateName": "Maharashtra",
  "districtName": "<ADDRESS>",
  "pinCode": "<PINCODE>",
  "stateCode": "27",
  "districtCode": "123",
  "authMethods": [
    "MOBILE_OTP",
    "AADHAAR_OTP"
  ],
  "status": "ACTIVE",
  "emailVerified": "false",
  "mobileVerified": "true",
  "kycStatus": "VERIFIED",
  "abhaLinkedCount": "3"
}
```


---

# Refresh token

`GET /abha/api/v3/phr/app/login/profile/request/token`

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile/request/token \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'R-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `R-token` (string, required): The refresh token from a login response, sent with a `Bearer ` prefix, exchanged for a new user token.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Responses

- `200`: OK
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors

Example 200 response. The values are placeholders:

```json
{
  "tokens": {
    "token": "<JWT TOKEN>",
    "expiresIn": 1800,
    "refreshToken": "<JWT TOKEN>",
    "refreshExpiresIn": 1296000
  }
}
```


---

# Logout

`GET /abha/api/v3/phr/app/login/profile/request/logout`

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile/request/logout \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): The user token from a login or enrolment response, sent with a `Bearer ` prefix. It acts for that ABHA holder.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Responses

- `200`: OK
  - `message` (string)
  - `timestamp` (string)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors

Example 200 response. The values are placeholders:

```json
{
  "message": "You have been logged out",
  "timestamp": "2023-07-27T13:36:28.000Z"
}
```


---

# Switch profile

`GET /abha/api/v3/phr/app/login/profile/switch-profile`

```bash
curl --request GET \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile/switch-profile \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): The user token from a login or enrolment response, sent with a `Bearer ` prefix. It acts for that ABHA holder.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Responses

- `200`: OK
  - `txnId` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (object)
  - `tokens.refreshExpiresIn` (object)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "baeb429f-4ff0-42e3-abd6-fb55fa0f5bf1",
  "users": [
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "status": "ACTIVE",
      "kycStatus": "PENDING"
    },
    {
      "abhaAddress": "<ABHA_ADDRESS>",
      "fullName": "John Doe",
      "status": "ACTIVE",
      "kycStatus": "PENDING"
    },
    "... 1 more of the same shape"
  ],
  "tokens": {
    "token": "<JWT TOKEN>",
    "expiresIn": 300,
    "refreshToken": null,
    "refreshExpiresIn": null
  }
}
```


---

# Verify user switch profile

`POST /abha/api/v3/phr/app/login/profile/verify/switch-profile/user`

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile/verify/switch-profile/user \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'T-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "abhaAddress": "<ABHA_ADDRESS>",
  "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `T-token` (string, required): The transaction token from the preceding login step, sent with a `Bearer ` prefix. It is valid only for that login.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `abhaAddress` (string, required)
- `txnId` (string, required)

## Responses

- `200`: OK
  - `token` (string)
  - `expiresIn` (integer)
  - `refreshToken` (string)
  - `refreshExpiresIn` (integer)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
  - `code` (string)
  - `message` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors

Example 200 response. The values are placeholders:

```json
{
  "token": "<JWT TOKEN>",
  "expiresIn": 1800,
  "refreshToken": "<JWT TOKEN>",
  "refreshExpiresIn": 1296000
}
```


---

# Request profile OTP

`POST /abha/api/v3/phr/app/login/profile/request/otp`

Flows:
- P2-Consents Management › P2 -PHR Profile › P2 - Update Mobile › Send OTP - Update Mobile
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via ABHA OTP › Send ABHA OTP - Link-DeLink
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via Aadhaar OTP › Send Aadhaar OTP - Link-DeLink

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile/request/otp \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-address-profile",
    "mobile-verify"
  ],
  "loginHint": "mobile-number",
  "loginId": "{{encryptedData}}",
  "otpSystem": "abdm"
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): The user token from a login or enrolment response, sent with a `Bearer ` prefix. It acts for that ABHA holder.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `loginHint` (string, required)
- `loginId` (string, required)
- `otpSystem` (string, required)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "d01cebdf-95f5-480c-8289-6f3b218e7248",
  "message": "OTP is sent to Mobile number ending with ******2425"
}
```


---

# Login profile verify

`POST /abha/api/v3/phr/app/login/profile/verify`

Flows:
- P2-Consents Management › P2 -PHR Profile › P2 - Update Mobile › Verify OTP - Update Mobile
- P2-Consents Management › P2 -PHR Profile › P2 - Update Password › Verify Password - Update Password
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via ABHA OTP › Verify ABHA OTP - Link-DeLink
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via Aadhaar OTP › Verify Aadhaar OTP - Link-DeLink

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-address-profile",
    "mobile-verify"
  ],
  "authData": {
    "authMethods": [
      "otp"
    ],
    "otp": {
      "txnId": "37d8d312-35a0-41e7-a6e4-1074eb18a5fa",
      "otpValue": "{{encryptedData}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): The user token from a login or enrolment response, sent with a `Bearer ` prefix. It acts for that ABHA holder.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `authData` (object, required)
- `authData.authMethods` (string[])
- `authData.otp` (object)
- `authData.otp.txnId` (string)
- `authData.otp.otpValue` (string)
- `authData.password` (object)
- `authData.password.abhaAddress` (string)
- `authData.password.password` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `accounts` (object[])
  - `accounts.mobile` (string)
  - `accounts.firstName` (string)
  - `accounts.middleName` (string)
  - `accounts.lastName` (string)
  - `accounts.name` (string)
  - `accounts.yearOfBirth` (string)
  - `accounts.dayOfBirth` (string)
  - `accounts.monthOfBirth` (string)
  - `accounts.gender` (string)
  - `accounts.email` (object)
  - `accounts.profilePhoto` (string)
  - `accounts.status` (string)
  - `accounts.stateCode` (string)
  - `accounts.districtCode` (string)
  - `accounts.subDistrictCode` (object)
  - `accounts.villageCode` (object)
  - `accounts.townCode` (object)
  - `accounts.wardCode` (object)
  - `accounts.pincode` (string)
  - `accounts.address` (string)
  - `accounts.kycPhoto` (string)
  - `accounts.stateName` (string)
  - `accounts.districtName` (string)
  - `accounts.subdistrictName` (string)
  - `accounts.villageName` (object)
  - `accounts.townName` (string)
  - `accounts.wardName` (object)
  - `accounts.authMethods` (string[])
  - `accounts.tags` (object)
  - `accounts.kycVerified` (boolean)
  - `accounts.verificationStatus` (string)
  - `accounts.verificationType` (string)
  - `accounts.emailVerified` (object)
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "e10ca603-97f5-4cf2-8191-d51ea7db3845",
  "message": "Entered OTP is incorrect. Kindly re-enter valid OTP.",
  "authResult": "failed",
  "users": []
}
```


---

# Login profile verify

`POST /abha/api/v3/phr/app/login/profile/verify`

Flows:
- P2-Consents Management › P2 -PHR Profile › P2 - Update Mobile › Verify OTP - Update Mobile
- P2-Consents Management › P2 -PHR Profile › P2 - Update Password › Verify Password - Update Password
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via ABHA OTP › Verify ABHA OTP - Link-DeLink
- P2-Consents Management › P2 -PHR Profile › P2 - Link ABHA Number › P2 - via Aadhaar OTP › Verify Aadhaar OTP - Link-DeLink

```bash
curl --request POST \
  --url https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/login/profile/verify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'X-token: Bearer <JWT TOKEN>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-address-profile",
    "password-verify"
  ],
  "authData": {
    "authMethods": [
      "password"
    ],
    "password": {
      "abhaAddress": "<ABHA_ADDRESS>",
      "password": "{{encryptedData}}"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `X-token` (string, required): The user token from a login or enrolment response, sent with a `Bearer ` prefix. It acts for that ABHA holder.
- `REQUEST-ID` (string, required): Unique UUID for each request.
- `TIMESTAMP` (string, required): Request timestamp in UTC, ISO-8601 with Z.

## Body

- `scope` (string[], required)
- `authData` (object, required)
- `authData.authMethods` (string[])
- `authData.otp` (object)
- `authData.otp.txnId` (string)
- `authData.otp.otpValue` (string)
- `authData.password` (object)
- `authData.password.abhaAddress` (string)
- `authData.password.password` (string)

## Responses

- `200`: OK
  - `txnId` (string)
  - `message` (string)
  - `authResult` (string)
  - `users` (object[])
  - `users.abhaAddress` (string)
  - `users.fullName` (string)
  - `users.abhaNumber` (string)
  - `users.status` (string)
  - `users.kycStatus` (string)
  - `accounts` (object[])
  - `accounts.mobile` (string)
  - `accounts.firstName` (string)
  - `accounts.middleName` (string)
  - `accounts.lastName` (string)
  - `accounts.name` (string)
  - `accounts.yearOfBirth` (string)
  - `accounts.dayOfBirth` (string)
  - `accounts.monthOfBirth` (string)
  - `accounts.gender` (string)
  - `accounts.email` (object)
  - `accounts.profilePhoto` (string)
  - `accounts.status` (string)
  - `accounts.stateCode` (string)
  - `accounts.districtCode` (string)
  - `accounts.subDistrictCode` (object)
  - `accounts.villageCode` (object)
  - `accounts.townCode` (object)
  - `accounts.wardCode` (object)
  - `accounts.pincode` (string)
  - `accounts.address` (string)
  - `accounts.kycPhoto` (string)
  - `accounts.stateName` (string)
  - `accounts.districtName` (string)
  - `accounts.subdistrictName` (string)
  - `accounts.villageName` (object)
  - `accounts.townName` (string)
  - `accounts.wardName` (object)
  - `accounts.authMethods` (string[])
  - `accounts.tags` (object)
  - `accounts.kycVerified` (boolean)
  - `accounts.verificationStatus` (string)
  - `accounts.verificationType` (string)
  - `accounts.emailVerified` (object)
  - `accounts.ABHANumber` (string)
  - `accounts.preferredAbhaAddress` (string)
  - `tokens` (object)
  - `tokens.token` (string)
  - `tokens.expiresIn` (integer)
  - `tokens.refreshToken` (string)
  - `tokens.refreshExpiresIn` (integer)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string)
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p2/errors

Example 200 response. The values are placeholders:

```json
{
  "txnId": "e10ca603-97f5-4cf2-8191-d51ea7db3845",
  "message": "Entered OTP is incorrect. Kindly re-enter valid OTP.",
  "authResult": "failed",
  "users": []
}
```


---

# P2 Consents Management errors

Seeing a symptom rather than a code? Start at [Troubleshooting](/docs/hiecm/v3/troubleshooting/).

## Codes

| Code        | HTTP | Message             | Returned by                                    |
| ----------- | ---- | ------------------- | ---------------------------------------------- |
| `900902`    | 401  | Missing Credentials | `p2_get_v3_phr_app_login_profile`              |
| `ABDM-9999` | 400  | Invalid LoginId     | `p2_post_v3_phr_app_login_profile_request_otp` |

Every code above is recorded in the specification that owns it. The aggregated list across modules is at [error codes](/docs/hiecm/v3/reference/error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# Initiate subscription request

`POST /api/hiecm/subscription-requests/v3/init`

Be invoked by Health Information Users (HIUs), patients, or users through the Personal Health Record (PHR) application to initiate a subscription request. By using this API, individuals can start the process of subscribing to specific health information services or updates. This functionality is essential for enabling users to manage their health data subscriptions effectively, ensuring they receive timely and relevant health information.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/subscription-requests/v3/init \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "subscription": {
    "purpose": {
      "text": "Care Management",
      "code": "CAREMGT",
      "refUri": "https://abc.def.in"
    },
    "patient": {
      "id": "<ABHA_ADDRESS>"
    },
    "hiu": {
      "id": "INDIA_HIU",
      "name": "INDIA HIU",
      "type": "HIU"
    },
    "hips": [
      {
        "id": "INDIA_HIP",
        "name": "INDIA HIP",
        "type": "HIP"
      }
    ],
    "categories": [
      "LINK"
    ],
    "period": {
      "from": "2024-05-09T10:34:00.389Z",
      "to": "2024-05-09T10:34:00.389Z"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `subscription` (object, required)
- `subscription.purpose` (object, required)
- `subscription.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
- `subscription.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
- `subscription.purpose.refUri` (string, required): The reference URL.Allows alpha numeric character and special characters like  "^[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-zA-Z0-9()]{1,6}\\b(?:[-a-zA-Z0-9()@:%_\\+.~#?&//=]*)$"
- `subscription.patient` (object, required)
- `subscription.patient.id` (string, required): The abha address of the patient. Must start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx. Allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.\\-!]+[a-zA-Z0-9]@(abdm|sbx)$
- `subscription.hiu` (object, required)
- `subscription.hiu.id` (string, required): The service ID of the health information user. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `subscription.hiu.name` (string): The name of the health information user. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
- `subscription.hiu.type` (string): The type of the health information user. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
- `subscription.hips` (object[], required)
- `subscription.hips.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `subscription.hips.name` (string): The name of the health information provider. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
- `subscription.hips.type` (string): The type of the health information provider. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
- `subscription.categories` (object[], required)
- `subscription.period` (object, required): The date range between when the subscription will be active
- `subscription.period.from` (string, required): UTC date time in ISO format. Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `subscription.period.to` (string, required): UTC date time in ISO format.Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Receive the HIU subscription requests on init

`POST /api/v3/hiu/hiecm/subscription-requests/on-init`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This API endpoint serves as a callback for the /api/hiecm/subscription-requests/v3/init API. It is used to handle the response from the subscription request initiation process. By invoking this API, the Health Information User (HIU) can receive and process the outcome of the subscription request, ensuring that the system accurately reflects the status and actions taken.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hiu/hiecm/subscription-requests/on-init \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "subscriptionRequest": {
    "id": "f29f0e59-8388-4698-9fe6-05db67aeac46"
  },
  "error": {
    "code": "ABDM-1001",
    "message": "No data found"
  },
  "response": {
    "requestId": "f29f0e59-8388-4698-9fe6-05db67aeac46"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `subscriptionRequest` (object, required)
- `subscriptionRequest.id` (string): Random generated uniqueid. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `error` (object): Incase of success, error object is optional
- `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message
- `response` (object, required)
- `response.requestId` (string, required): Request id that was passed. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$

## Responses

- `200`: OK
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1031 - Invalid request. May be returned either bare (`ABDM-1031`) or with a trailing ": " separator (`ABDM-1031: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Notify subscription requests HIU

`POST /api/v3/hiu/subscription-requests/hiu/notify`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This API endpoint serves as a callback for when a subscription request is approved or denied. By invoking this API, the Health Information User (HIU) is notified about the outcome of their subscription request, whether it has been approved or denied. This functionality is essential for maintaining transparency and ensuring that the HIU is informed about the status of their subscription requests.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hiu/subscription-requests/hiu/notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "notification": {
    "subscriptionRequestId": "f29f0e59-8388-4698-9fe6-05db67aeac46",
    "reason": "reason",
    "status": "GRANTED",
    "subscription": {
      "id": "f29f0e59-8388-4698-9fe6-05db67aeac46",
      "patient": {
        "id": "<ABHA_ADDRESS>"
      },
      "hiu": {
        "id": "INDIA_HIU",
        "name": "INDIA HIU",
        "type": "HIU"
      },
      "sources": [
        {
          "hiTypes": [
            "Prescription"
          ],
          "purpose": {
            "text": "Care Management",
            "code": "CAREMGT",
            "refUri": "https://abc.def.in"
          },
          "hip": {
            "id": "INDIA_HIP",
            "name": "INDIA HIP",
            "type": "HIP"
          },
          "categories": [
            "LINK"
          ],
          "period": {
            "from": "2024-05-09T10:34:00.389Z",
            "to": "2024-05-09T10:34:00.389Z"
          },
          "status": "SUCCESS"
        }
      ]
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `notification` (object, required)
- `notification.subscriptionRequestId` (string, required): subscriptionRequestId .Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `notification.reason` (string, required)
- `notification.status` (string, required) One of: GRANTED, DENIED.
- `notification.subscription` (object, required)
- `notification.subscription.id` (string)
- `notification.subscription.patient` (object)
- `notification.subscription.patient.id` (string, required): The abha address of the patient. Must start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx.Allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.\\-!]+[a-zA-Z0-9]@(abdm|sbx)$
- `notification.subscription.hiu` (object)
- `notification.subscription.hiu.id` (string, required): The service ID of the health information user. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `notification.subscription.hiu.name` (string): The name of the health information user. Allows alpha numeric and special characters like ^[a-zA-Z]+[A-Za-z0-9_\\-@,().\\s\\xa0:/]+
- `notification.subscription.hiu.type` (string): The type of the health information user.  Allows alpha numeric and special characters like ^[a-zA-Z0-9_\\-@,. \":/]{0,255}$
- `notification.subscription.sources` (object[])
- `notification.subscription.sources.hiTypes` (string[], required): Types of health information document.
- `notification.subscription.sources.purpose` (object, required)
- `notification.subscription.sources.hip` (object, required): Identifier and name of the health information provider.
- `notification.subscription.sources.categories` (string[], required)
- `notification.subscription.sources.period` (object, required): The date range between when the subscription will be active
- `notification.subscription.sources.status` (string): The status of the subscription approval. Allows alpha numeric character and special characters like ^[a-zA-Z0-9_\-@,. ":]{0,255}$

## Responses

- `200`: OK
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1031 - Invalid request. May be returned either bare (`ABDM-1031`) or with a trailing ": " separator (`ABDM-1031: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Answer the subscription request notification

`POST /api/hiecm/subscription-requests/v3/hiu/on-notify`

Be invoked by the Health Information User (HIU) to respond to notifications received from the /subscription-requests/hiu/notify API. By using this API, the HIU can acknowledge and process the subscription request notifications, ensuring that the system accurately reflects the status and actions taken. This functionality is essential for maintaining the integrity and synchronization of subscription requests, supporting efficient and transparent health information exchange within the healthcare ecosystem.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/subscription-requests/v3/hiu/on-notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "acknowledgement": {
    "status": "OK",
    "subscriptionRequestId": "f29f0e59-8388-4698-9fe6-05db67aeac46"
  },
  "error": {
    "code": "ABDM-1001",
    "message": "No data found"
  },
  "response": {
    "requestId": "f29f0e59-8388-4698-9fe6-05db67aeac46"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `acknowledgement` (object, required)
- `acknowledgement.status` (string, required): The status of the subscription request. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$":
- `acknowledgement.subscriptionRequestId` (string, required): The subscription request id. This should be from the subscription request. Allows alphanumeric characters and  special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$"
- `error` (object): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message
- `response` (object, required)
- `response.requestId` (string): Request id that was passed.  Allows alphanumeric characters and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1015 - Invalid Response. May be returned either bare (`ABDM-1015`) or with a trailing ": " separator (`ABDM-1015: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Notify HIU subscription

`POST /api/v3/hiu/subscription/notify`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This API endpoint serves as a callback to notify the subscribed Health Information User (HIU) when a care context is linked or updated for a patient. By invoking this API, the HIU is informed about any changes or additions to the patient’s care context, ensuring that they have the most current and accurate health information. This functionality is essential for maintaining the integrity and synchronization of patient health records, supporting efficient and transparent health information exchange within the healthcare ecosystem.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hiu/subscription/notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "event": {
    "id": "f29f0e59-8388-4698-9fe6-05db67aeac46",
    "published": "2024-09-10T04:27:47.696Z",
    "category": "LINK",
    "subscriptionId": "5dd76bb8-0eaf-4952-9db4-4c6fe844c257",
    "content": {
      "patient": {
        "id": "<ABHA_ADDRESS>"
      },
      "hip": {
        "id": "INDIA_HIP"
      },
      "contexts": [
        {
          "careContexts": [],
          "hiType": "HealthDocumentRecord"
        }
      ]
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `event` (object, required)
- `event.id` (string, required): the event Id .Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `event.published` (string, required): UTC. Allows alpha numeric character and special characters like \\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$
- `event.category` (string, required) One of: LINK, DATA.
- `event.subscriptionId` (string, required)
- `event.content` (object, required)
- `event.content.patient` (object, required)
- `event.content.patient.id` (string, required): The abha address of the patient. Must start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx and Allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.\\-!]+[a-zA-Z0-9]@(abdm|sbx)$
- `event.content.hip` (object, required): Identifier and name of the health information provider.
- `event.content.hip.id` (string, required): service Id. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `event.content.contexts` (object[], required)
- `event.content.contexts.careContexts` (object[], required): List of care contexts linked at the HIP end for the identified patient.
- `event.content.contexts.hiType` (string, required) One of: DiagnosticReport, DischargeSummary, HealthDocumentRecord, ImmunizationRecord, OPConsultation, Prescription, WellnessRecord, Invoice.

## Responses

- `200`: OK
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1031 - Invalid request. May be returned either bare (`ABDM-1031`) or with a trailing ": " separator (`ABDM-1031: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Answer the care context subscription notification

`POST /api/hiecm/subscription-requests/v3/hiu/care-context/on-notify`

Be invoked by the Health Information User (HIU) to respond to notifications received from the /api/v3/hiu/subscription/notify API. By using this API, the HIU can acknowledge and process notifications related to care context subscriptions, ensuring that the system accurately reflects the status and actions taken. This functionality is essential for maintaining the integrity and synchronization of care context subscription requests, supporting efficient and transparent health information exchange within the healthcare ecosystem.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/subscription-requests/v3/hiu/care-context/on-notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "acknowledgement": {
    "status": "OK",
    "eventId": "3c2f0e59-8388-4698-9fe6-05db67aeac46"
  },
  "error": {
    "code": "ABDM-1001",
    "message": "No data found"
  },
  "response": {
    "requestId": "f29f0e59-8388-4698-9fe6-05db67aeac46"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `acknowledgement` (object, required)
- `acknowledgement.status` (string, required): The status of the subscription approval. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
- `acknowledgement.eventId` (string, required): Must be a valid UUID. Allows alphanumeric characters and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$"
- `error` (object): The error code and message, if any occurred.
- `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
- `error.message` (string, required): The appropriate error message
- `response` (object, required)
- `response.requestId` (string, required): Request id that was passed. Allows alphanumeric characters and special characters like "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1015 - Invalid Response. May be returned either bare (`ABDM-1015`) or with a trailing ": " separator (`ABDM-1015: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Approve subscription request

`POST /api/hiecm/subscription-requests/v3/{subscriptionRequestId}/approve`

Be invoked by the patient or user through the Personal Health Record (PHR) application to approve a subscription request. By using this API, individuals can grant permission for the requested subscription, ensuring that they receive the desired health information services or updates. This functionality is essential for enabling users to manage their health data subscriptions effectively, ensuring they have control over the information they receive. The API supports secure and efficient approval of subscription requests, enhancing the overall user experience within the healthcare ecosystem.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/subscription-requests/v3/{subscriptionRequestId}/approve \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "isApplicableForAllHIPs": true,
  "includedSources": [
    {
      "hiTypes": [
        "Prescription",
        "DiagnosticReport",
        "OPConsultation",
        "DischargeSummary",
        "ImmunizationRecord",
        "HealthDocumentRecord",
        "WellnessRecord",
        "Invoice"
      ],
      "purpose": {
        "text": "Care Management",
        "code": "CAREMGT",
        "refUri": "www.abdm.gov.in"
      },
      "categories": [
        "LINK",
        "DATA"
      ],
      "period": {
        "from": "2025-01-09T09:00:00.000Z",
        "to": "2124-12-31T09:00:00.000Z"
      }
    }
  ],
  "excludedSources": []
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Path parameters

- `subscriptionRequestId` (string, required): The subscription request id

## Body

- `isApplicableForAllHIPs` (boolean, required): A boolean value to denote if the policy is applicable to all the HIPs or only the specified HIP
- `includedSources` (object[], required): Included sources, carrying the list of hi types.
- `includedSources.hiTypes` (string[], required): Types of health information document.
- `includedSources.purpose` (object, required)
- `includedSources.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
- `includedSources.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
- `includedSources.purpose.refUri` (string, required): The reference URL.Allows alpha numeric character and special characters like "^[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-zA-Z0-9()]{1,6}\\b(?:[-a-zA-Z0-9()@:%_\\+.~#?&//=]*)$"
- `includedSources.hip` (object): Identifier and name of the health information provider.
- `includedSources.hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `includedSources.hip.name` (string, required): The name of the health information provider. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
- `includedSources.hip.type` (string): The type of the health information provider. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
- `includedSources.categories` (string[], required)
- `includedSources.period` (object, required): The date range between when the subscription will be active
- `includedSources.period.from` (string, required): UTC date time in ISO format. Allows alpha numeric character and special characters like  "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `includedSources.period.to` (string, required): UTC date time in ISO format.Allows alpha numeric character and special characters like  "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `excludedSources` (object[]): Excluded sources, carrying the list of hi types.
- `excludedSources.hiTypes` (string[], required): Types of health information document.
- `excludedSources.purpose` (object, required)
- `excludedSources.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
- `excludedSources.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
- `excludedSources.purpose.refUri` (string, required): The reference URL. Allows alpha numeric character and special characters like "^[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-zA-Z0-9()]{1,6}\\b(?:[-a-zA-Z0-9()@:%_\\+.~#?&//=]*)$"
- `excludedSources.hip` (object, required): Identifier and name of the health information provider.
- `excludedSources.hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `excludedSources.hip.name` (string, required): The name of the health information provider. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
- `excludedSources.hip.type` (string): The type of the health information provider. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
- `excludedSources.categories` (string[], required)
- `excludedSources.period` (object, required): The date range between when the subscription will be active
- `excludedSources.period.from` (string, required): UTC date time in ISO format.Allows alpha numeric character and special characters like  "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `excludedSources.period.to` (string, required): UTC date time in ISO format.Allows alpha numeric character and special characters like  "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
  - `subscriptionId` (string)
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 202 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "subscriptionId": "f29f0e59-8388-4698-9fe6-05db67aeac46",
  "message": "Successfully approved Subscription request"
}
```


---

# Deny subscription request

`POST /api/hiecm/subscription-requests/v3/{subscriptionRequestId}/deny`

Be invoked by the patient or user through the Personal Health Record (PHR) application to deny a subscription request. By using this API, individuals can reject the requested subscription, ensuring that they do not receive unwanted health information services or updates. This functionality is essential for enabling users to manage their health data subscriptions effectively, maintaining control over the information they receive. The API supports secure and efficient denial of subscription requests, enhancing the overall user experience within the healthcare ecosystem.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/subscription-requests/v3/{subscriptionRequestId}/deny \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "reason": "Subscription denied."
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Path parameters

- `subscriptionRequestId` (string, required): The subscription request id

## Body

- `reason` (string, required): Reason for denying subscription request. Allows alpha numeric character and special characters like "^[A-Za-z .,]{1,50}$"

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1066 - Invalid JWT token. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 202 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "message": "Successfully denied Subscription request"
}
```


---

# Fetch his/her subscription requests details

`GET /api/hiecm/subscription-requests/v3/requests`

Be invoked by the patient or user through the Personal Health Record (PHR) application to fetch details of their subscription requests. By using this API, patients can retrieve comprehensive information about all their subscription requests, including the status and specifics of each request. This functionality is essential for maintaining transparency and enabling patients to manage their subscriptions effectively. The API supports secure and efficient access to subscription data, enhancing the overall user experience within the healthcare ecosystem.

```bash
curl --request GET \
  --url "https://dev.abdm.gov.in/api/hiecm/subscription-requests/v3/requests?limit=5&offset=5&status=ALL" \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Query parameters

- `limit` (integer, required): How many items to return at one time
- `offset` (integer, required): How many items out of line
- `status` (string, required): Query string parameter restricts the data returned from your request

## Responses

- `200`: OK
  - `size` (integer, required)
  - `limit` (integer, required)
  - `offset` (integer, required)
  - `requests` (object[], required)
  - `requests.subscriptionId` (string)
  - `requests.requestId` (string, required)
  - `requests.createdAt` (string)
  - `requests.lastUpdated` (string)
  - `requests.purpose` (object)
  - `requests.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
  - `requests.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
  - `requests.purpose.refUri` (string, required): The reference URL.Allows alpha numeric character and special characters like "^[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-zA-Z0-9()]{1,6}\\b(?:[-a-zA-Z0-9()@:%_\\+.~#?&//=]*)$"
  - `requests.patient` (object)
  - `requests.patient.id` (string, required): The abha address of the patient. Must start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx. Allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.\\-!]+[a-zA-Z0-9]@(abdm|sbx)$
  - `requests.hiu` (object)
  - `requests.hiu.id` (string, required): The service ID of the health information user. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
  - `requests.hiu.name` (string): The name of the health information user. Allows alphanumeric characters and special characters like"^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
  - `requests.hiu.type` (string): The type of the health information user. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
  - `requests.hips` (object[])
  - `requests.hips.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
  - `requests.hips.name` (string): The name of the health information provider. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
  - `requests.hips.type` (string): The type of the health information provider. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
  - `requests.categories` (string[])
  - `requests.period` (object)
  - `requests.period.from` (string, required): UTC date time in ISO format.Allows alpha numeric character and special characters like  "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
  - `requests.period.to` (string, required): UTC date time in ISO format.Allows alpha numeric character and special characters like  "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
  - `requests.status` (string) One of: REQUESTED, GRANTED, DENIED, EXPIRED, REVOKED.
  - `requests.requestType` (string) One of: HEALTH_LOCKER, HIU, HIP.
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1066 - Invalid JWT token. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "size": 0,
  "limit": 5,
  "offset": 5,
  "requests": [
    {
      "subscriptionId": "f29f0e59-8388-4698-9fe6-05db67aeac46",
      "requestId": "f29f0e59-8388-4698-9fe6-05db67aeac46",
      "createdAt": "2024-05-09T10:34:00.389Z",
      "lastUpdated": "2024-05-09T10:34:00.389Z",
      "purpose": {
        "text": "Care Management",
        "code": "CAREMGT",
        "refUri": "https://abc.def.in"
      },
      "patient": {
        "id": "<ABHA_ADDRESS>"
      },
      "hiu": {
        "id": "INDIA_HIU",
        "name": "INDIA HIU",
        "type": "HIU"
      },
      "hips": [
        {
          "id": "INDIA_HIP",
          "name": "INDIA HIP",
          "type": "HIP"
        }
      ],
      "categories": [
        "LINK"
      ],
      "period": {
        "from": "2024-05-09T10:34:00.389Z",
        "to": "2024-05-09T10:34:00.389Z"
      },
      "status": "GRANTED",
      "requestType": "HEALTH_LOCKER"
    }
  ]
}
```


---

# Edit the subscription details

`PUT /api/hiecm/subscription-requests/v3/patients/{subscriptionID}`

Edit the details of an existing subscription. By invoking this API, users can update the parameters and preferences associated with a specific subscription identified by the subscription ID.

```bash
curl --request PUT \
  --url https://dev.abdm.gov.in/api/hiecm/subscription-requests/v3/patients/{subscriptionID} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hiuId": "INDIA_HIU",
  "subscriptionEditAndApprovalRequest": {
    "isApplicableForAllHIPs": true,
    "includedSources": [
      {
        "hiTypes": [
          "Prescription"
        ],
        "purpose": {
          "text": "Care Management",
          "code": "CAREMGT",
          "refUri": "https://abc.def.in"
        },
        "hip": {
          "id": "INDIA_HIP",
          "name": "INDIA HIP",
          "type": "HIP"
        },
        "categories": [
          "LINK"
        ],
        "period": {
          "from": "2024-05-09T10:34:00.389Z",
          "to": "2024-05-09T10:34:00.389Z"
        },
        "status": "SUCCESS"
      }
    ],
    "excludedSources": [
      {
        "hiTypes": [
          "Prescription"
        ],
        "purpose": {
          "text": "Care Management",
          "code": "CAREMGT",
          "refUri": "https://abc.def.in"
        },
        "hip": {
          "id": "INDIA_HIP",
          "name": "INDIA HIP",
          "type": "HIP"
        },
        "categories": [
          "LINK"
        ],
        "period": {
          "from": "2024-05-09T10:34:00.389Z",
          "to": "2024-05-09T10:34:00.389Z"
        },
        "status": "SUCCESS"
      }
    ]
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Path parameters

- `subscriptionID` (string, required): The subscription id

## Body

- `hiuId` (string, required): The service ID of the health information provider Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
- `subscriptionEditAndApprovalRequest` (object, required)
- `subscriptionEditAndApprovalRequest.isApplicableForAllHIPs` (boolean, required): A boolean value to denote if the policy is applicable to all the HIPs or only the specified HIP
- `subscriptionEditAndApprovalRequest.includedSources` (object[], required): Included sources, carrying the list of hi types.
- `subscriptionEditAndApprovalRequest.includedSources.hiTypes` (string[], required): Types of health information document.
- `subscriptionEditAndApprovalRequest.includedSources.purpose` (object, required)
- `subscriptionEditAndApprovalRequest.includedSources.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
- `subscriptionEditAndApprovalRequest.includedSources.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
- `subscriptionEditAndApprovalRequest.includedSources.purpose.refUri` (string, required): The reference URL.Allows alpha numeric character and special characters like "^[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-zA-Z0-9()]{1,6}\\b(?:[-a-zA-Z0-9()@:%_\\+.~#?&//=]*)$"
- `subscriptionEditAndApprovalRequest.includedSources.hip` (object, required): Identifier and name of the health information provider.
- `subscriptionEditAndApprovalRequest.includedSources.hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `subscriptionEditAndApprovalRequest.includedSources.hip.name` (string, required): The name of the health information provider. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
- `subscriptionEditAndApprovalRequest.includedSources.hip.type` (string): The type of the health information provider. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
- `subscriptionEditAndApprovalRequest.includedSources.categories` (string[], required)
- `subscriptionEditAndApprovalRequest.includedSources.period` (object, required): The date range between when the subscription will be active
- `subscriptionEditAndApprovalRequest.includedSources.period.from` (string, required): UTC date time in ISO format. Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `subscriptionEditAndApprovalRequest.includedSources.period.to` (string, required): UTC date time in ISO format. Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `subscriptionEditAndApprovalRequest.includedSources.status` (string, required): The status of the subscription approval
- `subscriptionEditAndApprovalRequest.excludedSources` (object[], required): Excluded sources, carrying the list of hi types.
- `subscriptionEditAndApprovalRequest.excludedSources.hiTypes` (string[], required): Types of health information document.
- `subscriptionEditAndApprovalRequest.excludedSources.purpose` (object, required)
- `subscriptionEditAndApprovalRequest.excludedSources.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
- `subscriptionEditAndApprovalRequest.excludedSources.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
- `subscriptionEditAndApprovalRequest.excludedSources.purpose.refUri` (string, required): The reference URL. Allows alpha numeric character and special characters like "^[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-zA-Z0-9()]{1,6}\\b(?:[-a-zA-Z0-9()@:%_\\+.~#?&//=]*)$"
- `subscriptionEditAndApprovalRequest.excludedSources.hip` (object, required): Identifier and name of the health information provider.
- `subscriptionEditAndApprovalRequest.excludedSources.hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
- `subscriptionEditAndApprovalRequest.excludedSources.hip.name` (string, required): The name of the health information provider. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
- `subscriptionEditAndApprovalRequest.excludedSources.hip.type` (string): The type of the health information provider. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
- `subscriptionEditAndApprovalRequest.excludedSources.categories` (string[], required)
- `subscriptionEditAndApprovalRequest.excludedSources.period` (object, required): The date range between when the subscription will be active
- `subscriptionEditAndApprovalRequest.excludedSources.period.from` (string, required): UTC date time in ISO format.Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `subscriptionEditAndApprovalRequest.excludedSources.period.to` (string, required): UTC date time in ISO format.Allows alpha numeric character and special characters like "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$"
- `subscriptionEditAndApprovalRequest.excludedSources.status` (string, required): The status of the subscription approval

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
  - `subscriptionId` (string)
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1066 - Invalid JWT token. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 202 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "subscriptionId": "f29f0e59-8388-4698-9fe6-05db67aeac46",
  "message": "Successfully approved Subscription request"
}
```


---

# Disable the subscription by subscription ID

`POST /api/hiecm/subscription-requests/v3/disable/{subscriptionID}`

Disable an existing subscription identified by the subscription ID. By invoking this API, users can deactivate the subscription, ensuring that the associated health information services or updates are no longer delivered.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/subscription-requests/v3/disable/{subscriptionID} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Path parameters

- `subscriptionID` (string, required): The subscription id

## Responses

- `200`: OK
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1066 - Invalid JWT token. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "message": "Subscription disabled successfully"
}
```


---

# Enable the subscription by subscription ID

`POST /api/hiecm/subscription-requests/v3/enable/{subscriptionID}`

Enable an existing subscription identified by the subscription ID. By invoking this API, users can activate the subscription, ensuring that the associated health information services or updates are delivered as requested. This functionality is essential for managing subscriptions effectively, allowing users to control the activation status of their health data subscriptions. The API supports secure and efficient enablement of subscriptions, enhancing the overall user experience within the healthcare ecosystem.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/subscription-requests/v3/enable/{subscriptionID} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Path parameters

- `subscriptionID` (string, required): The subscription id

## Responses

- `200`: OK
  - `message` (string)
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1066 - Invalid JWT token. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "message": "Subscription enabled successfully"
}
```


---

# Fetch his/her subscription details by subscription REQUEST-ID

`GET /api/hiecm/subscription-requests/v3/request/{subscriptionRequestId}`

Be invoked by the patient or user through the Personal Health Record (PHR) application to fetch their subscription details using the subscription REQUEST-ID. By using this API, individuals can retrieve comprehensive information about a specific subscription request, including its status, scope, and any associated conditions. This functionality is essential for enabling users to manage their health data subscriptions effectively, ensuring they have access to accurate and up-to-date subscription information.

```bash
curl --request GET \
  --url https://dev.abdm.gov.in/api/hiecm/subscription-requests/v3/request/{subscriptionRequestId} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Path parameters

- `subscriptionRequestId` (string, required): The subscription request id

## Responses

- `200`: OK
  - `id` (number, required)
  - `requestId` (string, required)
  - `subscriptionId` (string, required)
  - `patientId` (string, required): abha address of the patient. Allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.\\-!]+[a-zA-Z0-9]@(abdm|sbx)$
  - `requesterType` (string, required)
  - `status` (string, required) One of: GRANTED, DENIED, REQUESTED, REVOKED.
  - `details` (object, required)
  - `details.subscriptionRequestId` (string, required)
  - `details.purpose` (object, required)
  - `details.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
  - `details.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
  - `details.purpose.refUri` (string, required): The reference URL.Allows alpha numeric character and special characters like "^[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-zA-Z0-9()]{1,6}\\b(?:[-a-zA-Z0-9()@:%_\\+.~#?&//=]*)$"
  - `details.patient` (object, required)
  - `details.patient.id` (string, required): The abha address of the patient. Must start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx. Allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.\\-!]+[a-zA-Z0-9]@(abdm|sbx)$
  - `details.hiu` (object, required)
  - `details.hiu.id` (string, required): The service ID of the health information user. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
  - `details.hiu.name` (string): The name of the health information user.Allows alpha numeric character and special characters like ^[a-zA-Z]+(([',. -][a-zA-Z ])?[a-zA-Z]*)*$
  - `details.hiu.type` (string): The type of the health information user. Allows alpha numeric and special characters like  "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
  - `details.hips` (object[], required)
  - `details.hips.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
  - `details.hips.name` (string): The name of the health information provider. Allows alpha numeric and special characters like "^[a-zA-Z]+[A-Za-z0-9_\\-@,().\\s\\xa0:/]+"
  - `details.hips.type` (string): The type of the health information provider. Allows alpha numeric and special characters like  "^[a-zA-Z0-9_\\-@,. \":/]{0,255}$"
  - `details.categories` (object[], required)
  - `details.period` (object, required): The date range between when the subscription will be active
  - `details.period.from` (string, required): UTC date time in ISO format. Allows alpha numeric character and special characters like \\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$
  - `details.period.to` (string, required): UTC date time in ISO format.Allows alpha numeric character and special characters like \\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$
  - `dateCreated` (string, required): created date. Allows alpha numeric character and special characters like \\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$
  - `dateModified` (string, required): modified date.Allows alpha numeric character and special characters like \\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{3}Z$
  - `healthIdNumber` (string, required): abha number of the user.
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1066 - Invalid JWT token. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "id": 1234,
  "requestId": "ab1f0e59-8388-4698-9fe6-05db67aeac46",
  "subscriptionId": "c12f0e59-8388-4698-9fe6-05db67aea3c4",
  "patientId": "<ABHA_ADDRESS>",
  "requesterType": "phr",
  "status": "GRANTED",
  "details": {
    "subscriptionRequestId": "38d8dbfc-9ea6-4f9f-b807-b00d2b885a54",
    "purpose": {
      "text": "Care Management",
      "code": "CAREMGT",
      "refUri": "https://abc.def.in"
    },
    "patient": {
      "id": "<ABHA_ADDRESS>"
    },
    "hiu": {
      "id": "INDIA_HIU",
      "name": "INDIA HIU",
      "type": "HIU"
    },
    "hips": [
      {
        "id": "INDIA_HIP",
        "name": "INDIA HIP",
        "type": "HIP"
      }
    ],
    "categories": [
      "LINK"
    ],
    "period": {
      "from": "2024-05-09T10:34:00.389Z",
      "to": "2024-05-09T10:34:00.389Z"
    }
  },
  "dateCreated": "2022-10-06T10:10:00.587Z",
  "dateModified": "2022-10-06T10:10:00.587Z",
  "healthIdNumber": "<ABHA_NUMBER>"
}
```


---

# Fetch his/her subscription details by subscription ID

`GET /api/hiecm/subscription-requests/v3/{subscriptionID}`

Be invoked by the patient or user through the Personal Health Record (PHR) application to fetch their subscription details using the subscription ID. By using this API, individuals can retrieve comprehensive information about a specific subscription, including its status, scope, and any associated conditions. This functionality is essential for enabling users to manage their health data subscriptions effectively, ensuring they have access to accurate and up-to-date subscription information.

```bash
curl --request GET \
  --url https://dev.abdm.gov.in/api/hiecm/subscription-requests/v3/{subscriptionID} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Path parameters

- `subscriptionID` (string, required): The subscription id

## Responses

- `200`: OK
  - `subscriptionId` (string, required)
  - `purpose` (object, required)
  - `purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
  - `purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
  - `purpose.refUri` (string, required): The reference URL. Allows alpha numeric character and special characters like "^[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-zA-Z0-9()]{1,6}\\b(?:[-a-zA-Z0-9()@:%_\\+.~#?&//=]*)$"
  - `dateCreated` (string, required)
  - `status` (string, required) One of: REQUESTED, GRANTED, DENIED, EXPIRED, REVOKED.
  - `dateGranted` (string, required)
  - `patient` (object, required)
  - `patient.id` (string, required): The abha address of the patient. Must start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx
  - `requester` (object, required)
  - `requester.id` (string, required)
  - `requester.name` (string, required)
  - `requester.type` (string, required)
  - `includedSources` (object[], required): Included sources, carrying the list of hi types.
  - `includedSources.hip` (object, required): Identifier and name of the health information provider.
  - `includedSources.hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 //_//-]*[A-Z a-z 0-9]$
  - `includedSources.hip.name` (string, required): The name of the health information provider. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
  - `includedSources.hip.type` (string): The type of the health information provider. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
  - `includedSources.categories` (string[], required)
  - `includedSources.hiTypes` (string[], required): Types of health information document.
  - `includedSources.period` (object, required): The date range between when the subscription will be active
  - `includedSources.period.from` (string, required): UTC date time in ISO format
  - `includedSources.period.to` (string, required): UTC date time in ISO format
  - `includedSources.status` (string): The status of the subscription approval
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1015 - Invalid Response. May be returned either bare (`ABDM-1015`) or with a trailing ": " separator (`ABDM-1015: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `404`: server cannot find the requested resource
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/p3/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "subscriptionId": "f29f0e59-8388-4698-9fe6-05db67aeac46",
  "purpose": {
    "text": "Care Management",
    "code": "CAREMGT",
    "refUri": "https://abc.def.in"
  },
  "dateCreated": "2021-09-28T12:30:08.573Z",
  "status": "GRANTED",
  "dateGranted": "2021-09-28T12:30:08.573Z",
  "patient": {
    "id": "<ABHA_ADDRESS>"
  },
  "requester": {
    "id": "<ABHA_ADDRESS>",
    "name": "ABDM_HIU",
    "type": "HIU"
  },
  "includedSources": [
    {
      "hip": {
        "id": "INDIA_HIP",
        "name": "INDIA HIP",
        "type": "HIP"
      },
      "categories": [
        "LINK"
      ],
      "hiTypes": [
        "Prescription"
      ],
      "period": {
        "from": "2024-05-09T10:34:00.389Z",
        "to": "2024-05-09T10:34:00.389Z"
      },
      "status": "GRANTED"
    }
  ]
}
```


---

# P3 Subscription errors

Seeing a symptom rather than a code? Start at [Troubleshooting](/docs/hiecm/v3/troubleshooting/).

The P3 Subscription specification records no error code yet. That is a gap in the specification, not a promise that this module cannot fail.

Every code above is recorded in the specification that owns it. The aggregated list across modules is at [error codes](/docs/hiecm/v3/reference/error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# Setup health locker for a patient

`POST /api/hiecm/subscription-requests/v3/setup-locker`

Set up a health locker for a patient. By invoking this API, users can configure a secure storage space for the patient’s health records, ensuring that all health information is organized and easily accessible. This functionality is essential for managing and safeguarding health data, providing patients with a centralized location for their medical documents.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/subscription-requests/v3/setup-locker \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>' \
  --header 'X-LOCKER-ID: <X_LOCKER_ID>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for tracking the end-to-end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds, and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token issued by ABDM after successful validation of username and password
- `X-LOCKER-ID` (string, required): The locker id

## Responses

- `200`: OK
  - `consentAutoApprovalId` (string)
- `400`: Bad Request
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1066 - Invalid JWT token. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
- `404`: server cannot find the requested resource
- `500`: Internal Server Error
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Service Unavailable
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "consentAutoApprovalId": "e5ec415f-c098-40f6-a0db-faa162fc5295"
}
```


---

# Get the subscription requests patients lockers

`GET /api/hiecm/subscription-requests/v3/patients/lockers`

Retrieve a list of health lockers associated with a given ABHA address. It includes both active and inactive subscriptions based on the `includeInactive` parameter.

```bash
curl --request GET \
  --url "https://dev.abdm.gov.in/api/hiecm/subscription-requests/v3/patients/lockers?includeInactive=true" \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for tracking the end-to-end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds, and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token issued by ABDM after successful validation of username and password

## Query parameters

- `includeInactive` (string, required): Indicates whether to include inactive records

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
[
  {
    "id": 212,
    "lockerId": "HIU_V3",
    "lockerName": "HIU_V3",
    "patientId": "<ABHA_ADDRESS>",
    "dateCreated": "2024-03-15T01:49:16.316Z",
    "dateModified": "2024-03-120T01:49:16.316Z",
    "isActive": true
  }
]
```


---

# Get health locker settings of a patient by locker ID

`GET /api/hiecm/subscription-requests/v3/patients/lockers/{locker-id}`

Retrieve the health locker settings of a patient using the locker ID. By invoking this API, users can access detailed information about the configuration and preferences of the patient’s health locker. This functionality is essential for managing and customizing the storage and access settings of health records, ensuring that patients have control over their health information. The API supports secure and efficient retrieval of health locker settings, enhancing the overall management of health data within the healthcare ecosystem.

```bash
curl --request GET \
  --url https://dev.abdm.gov.in/api/hiecm/subscription-requests/v3/patients/lockers/{locker-id} \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for tracking the end-to-end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds, and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token issued by ABDM after successful validation of username and password

## Path parameters

- `locker-id` (string, required): The locker id

## Responses

- `200`: OK
  - `lockerId` (string)
  - `lockerName` (string)
  - `active` (boolean)
  - `dateCreated` (string)
  - `subscriptions` (object[])
  - `subscriptions.subscriptionId` (string, required)
  - `subscriptions.purpose` (object, required)
  - `subscriptions.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
  - `subscriptions.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
  - `subscriptions.purpose.refUri` (string, required): The reference URL. Allows alpha numeric character and special characters like "^[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-zA-Z0-9()]{1,6}\\b(?:[-a-zA-Z0-9()@:%_\\+.~#?&//=]*)$"
  - `subscriptions.status` (string, required) One of: REQUESTED, GRANTED, DENIED, EXPIRED, REVOKED.
  - `subscriptions.dateCreated` (string, required)
  - `subscriptions.dateGranted` (string, required)
  - `subscriptions.patient` (object, required)
  - `subscriptions.patient.id` (string, required): The abha address of the patient. Must start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx
  - `subscriptions.requester` (object, required)
  - `subscriptions.requester.id` (string, required)
  - `subscriptions.requester.name` (string, required)
  - `subscriptions.requester.type` (string, required)
  - `subscriptions.includedSources` (object[], required): Included sources, carrying the list of hi types.
  - `subscriptions.includedSources.hiTypes` (string[], required): Types of health information document.
  - `subscriptions.includedSources.purpose` (object, required)
  - `subscriptions.includedSources.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
  - `subscriptions.includedSources.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
  - `subscriptions.includedSources.purpose.refUri` (string, required): The reference URL. Allows alpha numeric character and special characters like "^[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-zA-Z0-9()]{1,6}\\b(?:[-a-zA-Z0-9()@:%_\\+.~#?&//=]*)$"
  - `subscriptions.includedSources.hip` (object, required): Identifier and name of the health information provider.
  - `subscriptions.includedSources.hip.id` (string, required): The service ID of the health information provider. Must be Alpha numeric and _ or - in middle
  - `subscriptions.includedSources.hip.name` (string, required): The name of the health information provider. Allows alphanumeric characters and special characters like _\-@,. ":
  - `subscriptions.includedSources.hip.type` (string): The type of the health information provider. Allows alphanumeric characters and special characters like _\-@,. ":
  - `subscriptions.includedSources.categories` (string[], required)
  - `subscriptions.includedSources.period` (object, required): The date range between when the subscription will be active
  - `subscriptions.includedSources.period.from` (string, required): UTC date time in ISO format
  - `subscriptions.includedSources.period.to` (string, required): UTC date time in ISO format
  - `subscriptions.includedSources.status` (string): The status of the subscription approval
  - `autoApprovals` (object[])
  - `autoApprovals.id` (number)
  - `autoApprovals.autoApprovalId` (string)
  - `autoApprovals.hiuId` (string): Identifier of the health information user that raised the request.
  - `autoApprovals.patientId` (string)
  - `autoApprovals.isActive` (boolean)
  - `autoApprovals.dateCreated` (string)
  - `autoApprovals.dateModified` (string)
  - `autoApprovals.policy` (object)
  - `autoApprovals.policy.isApplicableForAllHIPs` (boolean, required)
  - `autoApprovals.policy.hiu` (object, required)
  - `autoApprovals.policy.hiu.id` (string, required): The service ID of the health information user. Must be Alpha numeric and _ or - in middle
  - `autoApprovals.policy.hiu.name` (string): The name of the health information user. Allows alphanumeric characters and special characters like _\-@,. ":
  - `autoApprovals.policy.hiu.type` (string): The type of the health information user. Allows alphanumeric characters and special characters like _\-@,. ":
  - `autoApprovals.policy.includedSources` (object[], required): Included sources, carrying the list of hi types.
  - `autoApprovals.policy.includedSources.hiTypes` (string[], required): Types of health information document.
  - `autoApprovals.policy.includedSources.purpose` (object, required)
  - `autoApprovals.policy.includedSources.hip` (object, required): Identifier and name of the health information provider.
  - `autoApprovals.policy.includedSources.categories` (string[], required)
  - `autoApprovals.policy.includedSources.period` (object, required): The date range between when the subscription will be active
  - `autoApprovals.policy.includedSources.status` (string): The status of the subscription approval
  - `autoApprovals.policy.excludedSources` (object[], required): Excluded sources, carrying the list of hi types.
  - `autoApprovals.policy.excludedSources.hiTypes` (string[], required): Types of health information document.
  - `autoApprovals.policy.excludedSources.purpose` (object, required)
  - `autoApprovals.policy.excludedSources.hip` (object, required): Identifier and name of the health information provider.
  - `autoApprovals.policy.excludedSources.categories` (string[], required)
  - `autoApprovals.policy.excludedSources.period` (object, required): The date range between when the subscription will be active
  - `autoApprovals.policy.excludedSources.status` (string): The status of the subscription approval
- `400`: Bad Request
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1066 - Invalid JWT token. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
- `404`: server cannot find the requested resource
- `500`: Internal Server Error
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Service Unavailable
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "lockerId": "1234",
  "lockerName": "Locker 1",
  "active": true,
  "dateCreated": "2021-09-28T12:30:08.573Z",
  "subscriptions": [
    {
      "subscriptionId": "f29f0e59-8388-4698-9fe6-05db67aeac46",
      "purpose": {
        "text": "Care Management",
        "code": "CAREMGT",
        "refUri": "https://abc.def.in"
      },
      "status": "GRANTED",
      "dateCreated": "2021-09-28T12:30:08.573Z",
      "dateGranted": "2021-09-28T12:30:08.573Z",
      "patient": {
        "id": "<ABHA_ADDRESS>"
      },
      "requester": {
        "id": "<ABHA_ADDRESS>",
        "name": "ABDM_HIU",
        "type": "HIU"
      },
      "includedSources": [
        {
          "hiTypes": [
            "Prescription"
          ],
          "purpose": {
            "text": "Care Management",
            "code": "CAREMGT",
            "refUri": "https://abc.def.in"
          },
          "hip": {
            "id": "INDIA_HIP",
            "name": "INDIA HIP",
            "type": "HIP"
          },
          "categories": [
            "LINK"
          ],
          "period": {
            "from": "2024-05-09T10:34:00.389Z",
            "to": "2024-05-09T10:34:00.389Z"
          },
          "status": "SUCCESS"
        }
      ]
    }
  ],
  "autoApprovals": [
    {
      "id": 1234,
      "autoApprovalId": "e5ec415f-c098-40f6-a0db-faa162fc5295",
      "hiuId": "India_HIU",
      "patientId": "<ABHA_ADDRESS>",
      "isActive": false,
      "dateCreated": "2021-09-28T12:30:08.573Z",
      "dateModified": "2021-09-28T12:30:08.573Z",
      "policy": {
        "isApplicableForAllHIPs": true,
        "hiu": {
          "id": "INDIA_HIU",
          "name": "INDIA HIU",
          "type": "HIU"
        },
        "includedSources": [
          {
            "hiTypes": [],
            "categories": [],
            "status": "SUCCESS"
          }
        ],
        "excludedSources": [
          {
            "hiTypes": [],
            "categories": [],
            "status": "SUCCESS"
          }
        ]
      }
    }
  ]
}
```


---

# Get all the consent and subscription requests with given filters

`GET /api/hiecm/subscription-requests/v3/patients/requests`

Retrieve all consent and subscription requests based on specified filters. By invoking this API, users can obtain a comprehensive list of requests that match the given criteria, including details about their status, scope, and any associated conditions. This functionality is essential for managing and tracking consent and subscription requests efficiently, ensuring that users have access to accurate and up-to-date information.

```bash
curl --request GET \
  --url "https://dev.abdm.gov.in/api/hiecm/subscription-requests/v3/patients/requests?consentLimit=<CONSENTLIMIT>&consentOffset=<CONSENTOFFSET>&subscriptionLimit=<SUBSCRIPTIONLIMIT>&subscriptionOffset=<SUBSCRIPTIONOFFSET>&status=ALL" \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for tracking the end-to-end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds, and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Query parameters

- `consentLimit` (string, required): The consent limit - to limit records being fetched
- `consentOffset` (string, required): The consent offset - to skip the records before fetching the first record
- `subscriptionLimit` (string, required): The subscription limit - to limit records being fetched
- `subscriptionOffset` (string, required): The subscription offset - to skip the records before fetching the first record
- `status` (string, required): The status of the subscription and consent

## Responses

- `200`: OK
  - `consents` (object)
  - `consents.size` (integer)
  - `consents.limit` (integer)
  - `consents.offset` (integer)
  - `consents.requests` (object[])
  - `consents.requests.requestId` (string)
  - `consents.requests.createdAt` (string)
  - `consents.requests.lastUpdated` (string)
  - `consents.requests.status` (string) One of: REQUESTED, EXPIRED, DENIED, GRANTED, REVOKED.
  - `consents.requests.purpose` (object)
  - `consents.requests.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
  - `consents.requests.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
  - `consents.requests.purpose.refUri` (string, required): The reference URL.Allows alpha numeric character and special characters like "^[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-zA-Z0-9()]{1,6}\\b(?:[-a-zA-Z0-9()@:%_\\+.~#?&//=]*)$"
  - `consents.requests.patient` (object)
  - `consents.requests.patient.id` (string, required): The abha address of the patient
  - `consents.requests.hip` (object): Identifier and name of the health information provider.
  - `consents.requests.hip.id` (string, required): The service ID of the health information provider. Allows alpha numeric and _ or - in middle
  - `consents.requests.hip.name` (string, required): The name of the health information provider. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
  - `consents.requests.hip.type` (string): The type of the health information provider. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
  - `consents.requests.hiu` (object)
  - `consents.requests.hiu.id` (string, required): The service ID of the health information user.  Allows alpha numeric and _ or - in middle
  - `consents.requests.hiu.name` (string, required): The name of the health information user. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
  - `consents.requests.hiu.type` (string): The type of the health information user. Allows alphanumeric characters and special characters like "^[a-zA-Z0-9_\\-@,. \":]{0,255}$"
  - `consents.requests.requester` (object)
  - `consents.requests.requester.name` (string, required): The name of the requester
  - `consents.requests.requester.identifier` (object, required)
  - `consents.requests.hiTypes` (string[]): Types of health information document.
  - `consents.requests.careContexts` (object[]): List of care contexts linked at the HIP end for the identified patient.
  - `consents.requests.careContexts.patientReference` (string, required): A patient identifier with which patient is registered in the facility/hospital
  - `consents.requests.careContexts.careContextReference` (string, required): An identifier of patient's care context created in HIP. A care context is a group of patient's health data (Not the actual health data)
  - `consents.requests.permission` (object)
  - `consents.requests.permission.accessMode` (string, required) One of: VIEW, STORE, STREAM, QUERY.
  - `consents.requests.permission.dateRange` (object, required)
  - `consents.requests.permission.dataEraseAt` (string, required): The date at which the consent expire. Should be UTC date time in ISO format
  - `consents.requests.permission.frequency` (object, required)
  - `subscriptions` (object)
  - `subscriptions.limit` (integer, required)
  - `subscriptions.size` (integer, required)
  - `subscriptions.offset` (integer, required)
  - `subscriptions.requests` (object[], required)
  - `subscriptions.requests.id` (string)
  - `subscriptions.requests.requestId` (string, required)
  - `subscriptions.requests.subscriptionId` (string)
  - `subscriptions.requests.patient` (object)
  - `subscriptions.requests.patient.id` (string, required): The abha address of the patient. Must start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx
  - `subscriptions.requests.purpose` (object)
  - `subscriptions.requests.purpose.text` (string, required) One of: Care Management, Break the Glass, Public Health, Healthcare Payment, Disease Specific Healthcare Research, Self Requested.
  - `subscriptions.requests.purpose.code` (string, required) One of: CAREMGT, BTG, PUBHLTH, HPAYMT, DSRCH, PATRQT.
  - `subscriptions.requests.purpose.refUri` (string, required): The reference URL. Allows alpha numeric character and special characters like "^[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-zA-Z0-9()]{1,6}\\b(?:[-a-zA-Z0-9()@:%_\\+.~#?&//=]*)$"
  - `subscriptions.requests.hiu` (object)
  - `subscriptions.requests.hiu.id` (string, required): The service ID of the health information user. Must be Alpha numeric and _ or - in middle
  - `subscriptions.requests.hiu.name` (string): The name of the health information user. Allows alphanumeric characters and special characters like _\-@,. ":
  - `subscriptions.requests.hiu.type` (string): The type of the health information user. Allows alphanumeric characters and special characters like _\-@,. ":
  - `subscriptions.requests.hips` (object[])
  - `subscriptions.requests.hips.id` (string, required): The service ID of the health information provider. Must be Alpha numeric and _ or - in middle
  - `subscriptions.requests.hips.name` (string): The name of the health information provider. Allows alphanumeric characters and special characters like _\-@,. ":
  - `subscriptions.requests.hips.type` (string): The type of the health information provider. Allows alphanumeric characters and special characters like _\-@,. ":
  - `subscriptions.requests.categories` (string[])
  - `subscriptions.requests.period` (object)
  - `subscriptions.requests.period.from` (string, required): UTC date time in ISO format
  - `subscriptions.requests.period.to` (string, required): UTC date time in ISO format
  - `subscriptions.requests.createdAt` (string)
  - `subscriptions.requests.lastUpdated` (string)
  - `subscriptions.requests.status` (string) One of: REQUESTED, GRANTED, DENIED, EXPIRED, REVOKED.
  - `subscriptions.requests.requestType` (string) One of: HEALTH_LOCKER, HIU, HIP.
- `400`: Bad Request
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1066 - Invalid JWT token. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
- `404`: server cannot find the requested resource
- `500`: Internal Server Error
  - `timestamp` (number, required)
  - `path` (string, required)
  - `status` (integer, required)
  - `error` (string, required): The error code and message, if any occurred.
  - `requestId` (string, required)
- `503`: Internal Server Error
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
{
  "consents": {
    "size": 10,
    "limit": 10,
    "offset": 0,
    "requests": [
      {
        "requestId": "e5ec415f-c098-40f6-a0db-faa162fc5295",
        "createdAt": "2021-09-28T12:30:08.573Z",
        "lastUpdated": "2021-09-28T12:30:08.573Z",
        "status": "GRANTED",
        "purpose": {
          "text": "Care Management",
          "code": "CAREMGT",
          "refUri": "www.abc.com"
        },
        "patient": {
          "id": "<ABHA_ADDRESS>"
        },
        "hip": {
          "id": "cowin_hip_01",
          "name": "Cowin",
          "type": "HIP"
        },
        "hiu": {
          "id": "cowin_hiu_01",
          "name": "Cowin",
          "type": "HIU"
        },
        "requester": {
          "name": "<ABHA_ADDRESS>",
          "identifier": {
            "value": "REG1",
            "type": "MH1001",
            "system": "https://www.sample.com"
          }
        },
        "hiTypes": [
          "Prescription"
        ],
        "careContexts": [
          {
            "patientReference": "batman@tmh",
            "careContextReference": "Episode1"
          }
        ],
        "permission": {
          "accessMode": "VIEW",
          "dateRange": {
            "from": "2021-09-28T12:30:08.573Z",
            "to": "2021-09-28T12:30:08.573Z"
          },
          "dataEraseAt": "2021-09-28T12:30:08.573Z",
          "frequency": {
            "unit": "HOUR",
            "value": 1,
            "repeats": 0
          }
        }
      }
    ]
  },
  "subscriptions": {
    "limit": 5,
    "size": 0,
    "offset": 5,
    "requests": [
      {
        "id": "1234",
        "requestId": "f29f0e59-8388-4698-9fe6-05db67aeac46",
        "subscriptionId": "f29f0e59-8388-4698-9fe6-05db67aeac46",
        "patient": {
          "id": "<ABHA_ADDRESS>"
        },
        "purpose": {
          "text": "Care Management",
          "code": "CAREMGT",
          "refUri": "https://abc.def.in"
        },
        "hiu": {
          "id": "INDIA_HIU",
          "name": "INDIA HIU",
          "type": "HIU"
        },
        "hips": [
          {
            "id": "INDIA_HIP",
            "name": "INDIA HIP",
            "type": "HIP"
          }
        ],
        "categories": [
          "LINK"
        ],
        "period": {
          "from": "2024-05-09T10:34:00.389Z",
          "to": "2024-05-09T10:34:00.389Z"
        },
        "createdAt": "2024-05-09T10:34:00.389Z",
        "lastUpdated": "2024-05-09T10:34:00.389Z",
        "status": "GRANTED",
        "requestType": "HEALTH_LOCKER"
      }
    ]
  }
}
```


---

# Fetch the record with health locker enabled provider details

`GET /api/hiecm/gateway/v3/health-lockers`

Retrieve records of providers that have health locker functionality enabled. When invoked, it queries the system to fetch detailed information about these specific providers. This functionality is particularly useful for users who need to identify and manage providers offering health locker services, which may include secure storage of health records, easy access to medical information, and other related features. By using this API, users can efficiently gather and manage data about health locker-enabled providers, ensuring they have access to all necessary details for effective service utilization and operational management.

```bash
curl --request GET \
  --url https://dev.abdm.gov.in/api/hiecm/gateway/v3/health-lockers \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Query parameters

- `name` (string): Name of the Locker

## Responses

- `200`: OK
- `204`: No Content
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `400`: Bad Request
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1015 - Invalid Response. May be returned either bare (`ABDM-1015`) or with a trailing ": " separator (`ABDM-1015: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
- `500`: Internal Server Error
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
[
  {
    "identifier": {
      "name": "AB - PMJAY",
      "id": "PMJAY"
    },
    "facilityType": [
      "HIP"
    ],
    "isHip": true,
    "isGovtEntity": false,
    "endpoints": {
      "healthLockerEndpoints": [
        {
          "use": "registration",
          "connectionType": "HTTPS",
          "address": "https://abc.com/register"
        }
      ]
    }
  }
]
```


---

# Receive a patient's share request, as the HIU

`POST /api/v3/patient-record/share`

**Hosted by the HIU, not by ABDM.** The HIE-CM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.

This is a callback API for the HIU. The HIE-CM provides the record share request the PHR app raised: the patient's profile, the number of records and the care contexts to share, and a transactionId for the transfer. Reply by calling POST /api/hiecm/patient-record/v3/on-share with the data push URL and the encryption key, carrying this transactionId and this request's REQUEST-ID.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/patient-record/share \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'request-id: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'timestamp: 2022-10-06T15:10:00.587Z' \
  --header 'x-hiu-id: HIU_ID' \
  --header 'Content-Type: application/json' \
  --data '{
  "metaData": {
    "hiuId": "MANISH_HIU",
    "counterId": "cf554160-1db7-453e-9d7a-3793ae2f50e0"
  },
  "transactionId": "56582bc6-5c17-4b32-9244-9b61d47a8059",
  "profile": {
    "patient": {
      "abhaNumber": null,
      "abhaAddress": "abhaAddress@sbx",
      "name": "Nitesh",
      "gender": "M",
      "dayOfBirth": "18",
      "monthOfBirth": "10",
      "yearOfBirth": "1912",
      "address": {
        "line": "Rohini Delhi",
        "district": "Delhi",
        "state": "Delhi",
        "pincode": "110042"
      },
      "phoneNumber": "989141XXXX"
    }
  },
  "sharedRecordCount": 2,
  "consent": {
    "careContexts": [
      {
        "patientReference": "manikandanb87@sbx",
        "careContextReference": "COC497647c1-0627-48fa-8131-0dddc1b3e0b4"
      },
      {
        "patientReference": "manikandanb87@sbx",
        "careContextReference": "COC497647c1-0627-48fa-8131-0dddc1b3e0b5"
      }
    ],
    "permission": {
      "accessMode": "VIEW"
    },
    "dataEraseAt": "2026-10-12T08:58:09.738Z"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): JWT access token issued by the ABDM session API after successful validation of client id and secret.

## Headers

- `request-id` (string, required): Random UUID, a v4 style guid, unique per callback.
- `timestamp` (string, required): ISO 8601 timestamp of when the callback was sent.
- `x-hiu-id` (string, required): Identifier of the health information user to which the request was intended.

## Body

- `metaData` (object, required): The HIU and the counter the QR code named.
- `metaData.hiuId` (string, required): The HIU's identifier, read from the QR code.
- `metaData.counterId` (string, required): The counter at the HIU, read from the QR code.
- `transactionId` (string, required): The transfer's identifier, assigned by the HIE-CM. Carry it in on-share and in notify.
- `profile` (object, required): The essential patient details, including ABHA number, ABHA address and the patient's contact address, used for initiating the record share process.
- `profile.patient` (object, required)
- `profile.patient.abhaNumber` (string,null): The 14 digit ABHA number, or null when the patient has an address only.
- `profile.patient.abhaAddress` (string, required): The patient's ABHA address.
- `profile.patient.name` (string, required)
- `profile.patient.gender` (string, required): M, F or O.
- `profile.patient.dayOfBirth` (string)
- `profile.patient.monthOfBirth` (string)
- `profile.patient.yearOfBirth` (string, required)
- `profile.patient.address` (object, required)
- `profile.patient.address.line` (string)
- `profile.patient.address.district` (string)
- `profile.patient.address.state` (string)
- `profile.patient.address.pincode` (string)
- `profile.patient.phoneNumber` (string, required)
- `sharedRecordCount` (integer, required): Number of records that are to be shared to the HIU.
- `consent` (object, required): The care contexts to share, the permission specifying how the records can be accessed, and the dataEraseAt date until which the data remains accessible.
- `consent.careContexts` (object[], required)
- `consent.careContexts.patientReference` (string, required): The patient reference the care context was linked under.
- `consent.careContexts.careContextReference` (string, required)
- `consent.permission` (object, required)
- `consent.permission.accessMode` (string, required): How the HIU may use the records. One of: VIEW.
- `consent.dataEraseAt` (string, required): Until when the data remains accessible to the HIU.

## Responses

- `202`: Accepted. Answer with the on-share call.
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives


---

# Submit the reply to a share request with the data push URL and the encryption key

`POST /api/hiecm/patient-record/v3/on-share`

Acts as the callback endpoint for the PHR application. After the initial request, the HIU responds to this callback with the data push URL and the encryption key required for securely transferring the user's health records.

The HIU makes this call after receiving the share request on its /api/v3/patient-record/share bridge endpoint. The transactionId is the one that request carried, and response.requestId is that request's REQUEST-ID. The HIE-CM forwards the body to the PHR app's /api/v3/patient-record/on-share callback.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/patient-record/v3/on-share \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: HIU_ID' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "hiRequest": {
    "transactionId": "18235d89-cb13-479d-ad71-7a57d5f669a8",
    "dataPushUrl": "https://webhook.site/a2477c41-2185-47eb-835a/health-information/transfer",
    "keyMaterial": {
      "cryptoAlg": "ECDH.",
      "curve": "curve25519",
      "dhPublicKey": {
        "expiry": "2022-12-28T13:18:20.742Z",
        "parameters": "Ephemeral public key.",
        "keyValue": "BFN7KTdOT0jIAExG2A8Jg+01wMPWxptiGqwHRVvtiVEsUq2FR7P2UdqZxJyPJSeR6muai21iQhasNxnhh8I5M+g="
      },
      "nonce": "28236d89-cb13-479d-ad71-7a57d5f669a9"
    }
  },
  "response": {
    "requestId": "efd6964f-6893-4b66-9e4e-28afc164126b"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): JWT access token issued by the ABDM session API after successful validation of client id and secret.

## Headers

- `REQUEST-ID` (string, required): Random UUID, a v4 style guid, unique per request.
- `TIMESTAMP` (string, required): ISO 8601 timestamp of when the request was initiated.
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended.
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended. sbx in the sandbox, abdm in production.

## Body

- `hiRequest` (object, required): The data push URL and the encryption key.
- `hiRequest.transactionId` (string, required): The transactionId the share request carried.
- `hiRequest.dataPushUrl` (string, required): The HIU's URL the PHR app posts the encrypted records to.
- `hiRequest.keyMaterial` (object, required)
- `response` (object, required)
- `response.requestId` (string, required): The REQUEST-ID of the share request this answers.

## Responses

- `202`: Accepted. The HIE-CM forwards the data push URL and key to the PHR app's on-share callback.
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives


---

# Receive the encrypted records at the data push URL, as the HIU

`POST /health-information/transfer`

**Hosted by the HIU at the dataPushUrl it supplied in on-share, not by ABDM.** The PHR application posts here directly; the path is whatever the data push URL names.

The PHR app sends the records covered by the share, one entry per care context, each an encrypted FHIR bundle with its checksum, along with the PHR app's own ECDH key material so the HIU can derive the shared key and decrypt. The shape below is the placeholder body in NHA's Postman collection; it follows the M2 and M3 health information transfer.

```bash
curl --request POST \
  --url {bridgeUrl}/health-information/transfer \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'request-id: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'timestamp: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "pageNumber": 0,
  "pageCount": 0,
  "transactionId": "string",
  "entries": [
    {
      "content": "Encrypted content of data packaged in FHIR bundle",
      "media": "mimetype of the content.",
      "checksum": "string",
      "careContextReference": "10004-20200001768-1"
    },
    {
      "content": "Encrypted content of data packaged in FHIR bundle",
      "media": "mimetype of the content.",
      "checksum": "string",
      "careContextReference": "10004-20200001768-2"
    }
  ],
  "keyMaterial": {
    "cryptoAlg": "ECDH",
    "curve": "Curve25519",
    "dhPublicKey": {
      "expiry": "2026-12-28T13:18:20.742Z",
      "parameters": "Curve25519/32byte random key",
      "keyValue": "string"
    },
    "nonce": "string"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): JWT access token issued by the ABDM session API after successful validation of client id and secret.

## Headers

- `request-id` (string, required): Random UUID, a v4 style guid, unique per callback.
- `timestamp` (string, required): ISO 8601 timestamp of when the callback was sent.

## Body

- `pageNumber` (integer, required): This page, counting from 0.
- `pageCount` (integer, required): How many pages the transfer has.
- `transactionId` (string, required): The transfer's identifier, from the share request.
- `entries` (object[], required): One entry per care context shared.
- `entries.content` (string): Encrypted content of data packaged in a FHIR bundle.
- `entries.media` (string): MIME type of the content.
- `entries.checksum` (string): Checksum of the content.
- `entries.careContextReference` (string)
- `keyMaterial` (object, required): ECDH key material for encrypting the records.
- `keyMaterial.cryptoAlg` (string, required)
- `keyMaterial.curve` (string, required)
- `keyMaterial.dhPublicKey` (object, required)
- `keyMaterial.dhPublicKey.expiry` (string, required)
- `keyMaterial.dhPublicKey.parameters` (string, required)
- `keyMaterial.dhPublicKey.keyValue` (string, required): The public key, base64.
- `keyMaterial.nonce` (string, required): A 32 byte random nonce for this transfer.

## Responses

- `202`: Accepted. Decrypt, then call notify with RECEIVED, PARTIAL_RECEIVED or FAILED.
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives


---

# Receive the other side's transfer status

`POST /api/v3/patient-record/on-notify`

**Hosted by the PHR application and by the HIU, not by ABDM.** The HIE-CM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.

This is a callback API for the PHR application and the HIU. This API is used to receive the status of the health record transfer process: the HIU receives what the PHR app sent to notify, and the PHR app receives what the HIU sent.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/patient-record/on-notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'request-id: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'timestamp: 2022-10-06T15:10:00.587Z' \
  --header 'x-hiu-id: HIU_ID' \
  --header 'Content-Type: application/json' \
  --data '{
  "notification": {
    "transactionId": "103a6265-8d5d-411b-9a9d-b460b5f00e4e",
    "doneAt": "2026-03-19T08:01:11.090Z",
    "statusNotification": {
      "sessionStatus": "TRANSFERRED",
      "statusResponses": [
        {
          "careContextReference": "COC497647c1-0627-48fa-8131-0dddc1b3e0b4",
          "hiStatus": "DELIVERED",
          "description": "Data sent successfully"
        }
      ]
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): JWT access token issued by the ABDM session API after successful validation of client id and secret.

## Headers

- `request-id` (string, required): Random UUID, a v4 style guid, unique per callback.
- `timestamp` (string, required): ISO 8601 timestamp of when the callback was sent.
- `x-hiu-id` (string, required): Identifier of the health information user to which the request was intended.

## Body

- `notification` (object, required): The transaction id, the session status and each care context's transfer status.
- `notification.transactionId` (string, required)
- `notification.doneAt` (string, required): When the transfer completed.
- `notification.statusNotification` (object, required)
- `notification.statusNotification.sessionStatus` (string, required): TRANSFERRED, PARTIAL_TRANSFERRED or FAILED from the PHR app or health locker; RECEIVED, PARTIAL_RECEIVED or FAILED from the HIU. One of: TRANSFERRED, PARTIAL_TRANSFERRED, RECEIVED, PARTIAL_RECEIVED, FAILED.
- `notification.statusNotification.statusResponses` (object[], required)
- `notification.statusNotification.statusResponses.careContextReference` (string, required)
- `notification.statusNotification.statusResponses.hiStatus` (string, required): DELIVERED or ERRORED from the PHR app or health locker; VALID, CORRUPTED, BLANK or ERRORED from the HIU. One of: DELIVERED, ERRORED, VALID, CORRUPTED, BLANK.
- `notification.statusNotification.statusResponses.description` (string)

## Responses

- `202`: Accepted.
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives


---

# Notify patient record

`POST /api/hiecm/patient-record/v3/notify`

Update the status of the health record transfer process. It is invoked by the PHR application and HIU to notify the HIE-CM about the completion status of the transaction and the individual care-contexts. Each care-context's transfer status is included to provide a detailed update on which records were successfully shared and received.

The PHR app or health locker, on the transfer of data, sends sessionStatus as one of TRANSFERRED, PARTIAL_TRANSFERRED or FAILED, and an hiStatus for each careContextReference as one of DELIVERED or ERRORED.

The HIU, on receipt of data, sends sessionStatus as one of RECEIVED, PARTIAL_RECEIVED or FAILED, for example FAILED when data was not received or invalid data was received, and an hiStatus for each careContextReference as one of VALID, CORRUPTED, BLANK or ERRORED.

Send the notification once, after the data transfer has completed. The HIE-CM forwards it to the other side's /api/v3/patient-record/on-notify callback.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/patient-record/v3/notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: HIU_ID' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "notification": {
    "transactionId": "a0e7bed4-ef98-4ea8-9077-f4a6192bfe2b",
    "doneAt": "2026-03-19T08:01:11.090Z",
    "statusNotification": {
      "sessionStatus": "TRANSFERRED",
      "statusResponses": [
        {
          "careContextReference": "COC497647c1-0627-48fa-8131-0dddc1b3e0b4",
          "hiStatus": "DELIVERED",
          "description": "Data sent successfully"
        },
        {
          "careContextReference": "COC497647c1-0627-48fa-8131-0dddc1b3e0b5",
          "hiStatus": "DELIVERED",
          "description": "Data sent successfully"
        }
      ]
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): JWT access token issued by the ABDM session API after successful validation of client id and secret.

## Headers

- `REQUEST-ID` (string, required): Random UUID, a v4 style guid, unique per request.
- `TIMESTAMP` (string, required): ISO 8601 timestamp of when the request was initiated.
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended.
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended. sbx in the sandbox, abdm in production.

## Body

- `notification` (object, required): The transaction id, the session status and each care context's transfer status.
- `notification.transactionId` (string, required)
- `notification.doneAt` (string, required): When the transfer completed.
- `notification.statusNotification` (object, required)
- `notification.statusNotification.sessionStatus` (string, required): TRANSFERRED, PARTIAL_TRANSFERRED or FAILED from the PHR app or health locker; RECEIVED, PARTIAL_RECEIVED or FAILED from the HIU. One of: TRANSFERRED, PARTIAL_TRANSFERRED, RECEIVED, PARTIAL_RECEIVED, FAILED.
- `notification.statusNotification.statusResponses` (object[], required)
- `notification.statusNotification.statusResponses.careContextReference` (string, required)
- `notification.statusNotification.statusResponses.hiStatus` (string, required): DELIVERED or ERRORED from the PHR app or health locker; VALID, CORRUPTED, BLANK or ERRORED from the HIU. One of: DELIVERED, ERRORED, VALID, CORRUPTED, BLANK.
- `notification.statusNotification.statusResponses.description` (string)

## Responses

- `202`: Accepted. The HIE-CM forwards the status to the other side's on-notify callback.
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives


---

# Share a patient's records with the HIU whose QR code was scanned

`POST /api/hiecm/patient-record/v3/share`

Is the first step in initiating the health data sharing process. It is invoked by an integrator application (such as any PHR application like ABHA) after scanning the HIU's QR code. The QR code provides the Health Information User (HIU) identifier, which is then used to share the user's profile details and care-context information with the HIE-CM.

The HIE-CM answers 202 Accepted and forwards the request to the HIU as a POST to /api/v3/patient-record/share on the HIU's bridge. The HIU's reply, with the data push URL and encryption key, arrives on the PHR app's /api/v3/patient-record/on-share callback.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/patient-record/v3/share \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: HIU_ID' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: Bearer <USER_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "metaData": {
    "hiuId": "MANISH_HIU",
    "counterId": "IN081010313"
  },
  "profile": {
    "patient": {
      "abhaNumber": null,
      "abhaAddress": "abhaAddress@sbx",
      "name": "String",
      "gender": "M",
      "dayOfBirth": "18",
      "monthOfBirth": "10",
      "yearOfBirth": "1991",
      "address": {
        "line": "String",
        "district": "String",
        "state": "String",
        "pincode": "XXXXXX"
      },
      "phoneNumber": "989141XXXX"
    }
  },
  "sharedRecordCount": 2,
  "consent": {
    "careContexts": [
      {
        "patientReference": "manishk1991@sbx",
        "careContextReference": "10004-20200001768-1"
      },
      {
        "patientReference": "manishk1991@sbx",
        "careContextReference": "10004-20200001768-2"
      }
    ],
    "permission": {
      "accessMode": "VIEW"
    },
    "dataEraseAt": "2025-10-11T08:58:09.738Z"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): JWT access token issued by the ABDM session API after successful validation of client id and secret.

## Headers

- `REQUEST-ID` (string, required): Random UUID, a v4 style guid, unique per request.
- `TIMESTAMP` (string, required): ISO 8601 timestamp of when the request was initiated.
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended.
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended. sbx in the sandbox, abdm in production.
- `X-AUTH-TOKEN` (string, required): JWT access token issued by the PHR service after successful user authentication. If the HIP does not have any role, then it is mandatory.

## Body

- `metaData` (object, required): The HIU and the counter the QR code named.
- `metaData.hiuId` (string, required): The HIU's identifier, read from the QR code.
- `metaData.counterId` (string, required): The counter at the HIU, read from the QR code.
- `profile` (object, required): The essential patient details, including ABHA number, ABHA address and the patient's contact address, used for initiating the record share process.
- `profile.patient` (object, required)
- `profile.patient.abhaNumber` (string,null): The 14 digit ABHA number, or null when the patient has an address only.
- `profile.patient.abhaAddress` (string, required): The patient's ABHA address.
- `profile.patient.name` (string, required)
- `profile.patient.gender` (string, required): M, F or O.
- `profile.patient.dayOfBirth` (string)
- `profile.patient.monthOfBirth` (string)
- `profile.patient.yearOfBirth` (string, required)
- `profile.patient.address` (object, required)
- `profile.patient.address.line` (string)
- `profile.patient.address.district` (string)
- `profile.patient.address.state` (string)
- `profile.patient.address.pincode` (string)
- `profile.patient.phoneNumber` (string, required)
- `sharedRecordCount` (integer, required): Number of records that are to be shared to the health information user (HIU).
- `consent` (object, required): The care contexts to share, the permission specifying how the records can be accessed, and the dataEraseAt date until which the data remains accessible.
- `consent.careContexts` (object[], required)
- `consent.careContexts.patientReference` (string, required): The patient reference the care context was linked under.
- `consent.careContexts.careContextReference` (string, required)
- `consent.permission` (object, required)
- `consent.permission.accessMode` (string, required): How the HIU may use the records. One of: VIEW.
- `consent.dataEraseAt` (string, required): Until when the data remains accessible to the HIU.

## Responses

- `202`: Accepted. The HIE-CM forwards the request to the HIU; the HIU's data push URL and key arrive on the on-share callback.
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives


---

# Receive the HIU's data push URL and encryption key, as the PHR app

`POST /api/v3/patient-record/on-share`

**Hosted by the PHR application, not by ABDM.** The HIE-CM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.

This is a callback API for the PHR application. The HIE-CM provides the HIU's answer to the share request: the data push URL to post the records to, and the ECDH key material to encrypt them with. Generate your own key pair and nonce, encrypt each record, and POST them to the data push URL, then call POST /api/hiecm/patient-record/v3/notify with the transfer status.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/patient-record/on-share \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'request-id: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'timestamp: 2022-10-06T15:10:00.587Z' \
  --header 'x-hiu-id: HIU_ID' \
  --header 'Content-Type: application/json' \
  --data '{
  "hiRequest": {
    "transactionId": "56582bc6-5c17-4b32-9244-9b61d47a8059",
    "dataPushUrl": "https://webhook.site/a2477c41-2185-47eb-835a/health-information/transfer",
    "keyMaterial": {
      "cryptoAlg": "ECDH.",
      "curve": "curve25519",
      "dhPublicKey": {
        "expiry": "2026-12-28T13:18:20.742Z",
        "parameters": "Ephemeral public key.",
        "keyValue": "BFN7KTdOT0jIAExG2A8Jg+01wMPWxptiGqwHRVvtiVEsUq2FR7P2UdqZxJyPJSeR6muai21iQhasNxnhh8I5M+g="
      },
      "nonce": "e589643f-48a9-41ed-ab2b-479e709e8f80"
    }
  },
  "response": {
    "requestId": "180ce450-ce28-493f-ac43-9f5253fa1167"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): JWT access token issued by the ABDM session API after successful validation of client id and secret.

## Headers

- `request-id` (string, required): Random UUID, a v4 style guid, unique per callback.
- `timestamp` (string, required): ISO 8601 timestamp of when the callback was sent.
- `x-hiu-id` (string, required): Identifier of the health information user to which the request was intended.

## Body

- `hiRequest` (object, required): The data push URL and the encryption key.
- `hiRequest.transactionId` (string, required): The transactionId the share request carried.
- `hiRequest.dataPushUrl` (string, required): The HIU's URL the PHR app posts the encrypted records to.
- `hiRequest.keyMaterial` (object, required)
- `response` (object, required)
- `response.requestId` (string, required): The REQUEST-ID of the share request this answers.

## Responses

- `202`: Accepted. Post the encrypted records to the data push URL next.
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives


---

# Receive the encrypted records at the data push URL, as the HIU

`POST /health-information/transfer`

**Hosted by the HIU at the dataPushUrl it supplied in on-share, not by ABDM.** The PHR application posts here directly; the path is whatever the data push URL names.

The PHR app sends the records covered by the share, one entry per care context, each an encrypted FHIR bundle with its checksum, along with the PHR app's own ECDH key material so the HIU can derive the shared key and decrypt. The shape below is the placeholder body in NHA's Postman collection; it follows the M2 and M3 health information transfer.

```bash
curl --request POST \
  --url {bridgeUrl}/health-information/transfer \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'request-id: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'timestamp: 2022-10-06T15:10:00.587Z' \
  --header 'Content-Type: application/json' \
  --data '{
  "pageNumber": 0,
  "pageCount": 0,
  "transactionId": "string",
  "entries": [
    {
      "content": "Encrypted content of data packaged in FHIR bundle",
      "media": "mimetype of the content.",
      "checksum": "string",
      "careContextReference": "10004-20200001768-1"
    },
    {
      "content": "Encrypted content of data packaged in FHIR bundle",
      "media": "mimetype of the content.",
      "checksum": "string",
      "careContextReference": "10004-20200001768-2"
    }
  ],
  "keyMaterial": {
    "cryptoAlg": "ECDH",
    "curve": "Curve25519",
    "dhPublicKey": {
      "expiry": "2026-12-28T13:18:20.742Z",
      "parameters": "Curve25519/32byte random key",
      "keyValue": "string"
    },
    "nonce": "string"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): JWT access token issued by the ABDM session API after successful validation of client id and secret.

## Headers

- `request-id` (string, required): Random UUID, a v4 style guid, unique per callback.
- `timestamp` (string, required): ISO 8601 timestamp of when the callback was sent.

## Body

- `pageNumber` (integer, required): This page, counting from 0.
- `pageCount` (integer, required): How many pages the transfer has.
- `transactionId` (string, required): The transfer's identifier, from the share request.
- `entries` (object[], required): One entry per care context shared.
- `entries.content` (string): Encrypted content of data packaged in a FHIR bundle.
- `entries.media` (string): MIME type of the content.
- `entries.checksum` (string): Checksum of the content.
- `entries.careContextReference` (string)
- `keyMaterial` (object, required): ECDH key material for encrypting the records.
- `keyMaterial.cryptoAlg` (string, required)
- `keyMaterial.curve` (string, required)
- `keyMaterial.dhPublicKey` (object, required)
- `keyMaterial.dhPublicKey.expiry` (string, required)
- `keyMaterial.dhPublicKey.parameters` (string, required)
- `keyMaterial.dhPublicKey.keyValue` (string, required): The public key, base64.
- `keyMaterial.nonce` (string, required): A 32 byte random nonce for this transfer.

## Responses

- `202`: Accepted. Decrypt, then call notify with RECEIVED, PARTIAL_RECEIVED or FAILED.
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives


---

# Notify patient record

`POST /api/hiecm/patient-record/v3/notify`

Update the status of the health record transfer process. It is invoked by the PHR application and HIU to notify the HIE-CM about the completion status of the transaction and the individual care-contexts. Each care-context's transfer status is included to provide a detailed update on which records were successfully shared and received.

The PHR app or health locker, on the transfer of data, sends sessionStatus as one of TRANSFERRED, PARTIAL_TRANSFERRED or FAILED, and an hiStatus for each careContextReference as one of DELIVERED or ERRORED.

The HIU, on receipt of data, sends sessionStatus as one of RECEIVED, PARTIAL_RECEIVED or FAILED, for example FAILED when data was not received or invalid data was received, and an hiStatus for each careContextReference as one of VALID, CORRUPTED, BLANK or ERRORED.

Send the notification once, after the data transfer has completed. The HIE-CM forwards it to the other side's /api/v3/patient-record/on-notify callback.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/patient-record/v3/notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: HIU_ID' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "notification": {
    "transactionId": "a0e7bed4-ef98-4ea8-9077-f4a6192bfe2b",
    "doneAt": "2026-03-19T08:01:11.090Z",
    "statusNotification": {
      "sessionStatus": "TRANSFERRED",
      "statusResponses": [
        {
          "careContextReference": "COC497647c1-0627-48fa-8131-0dddc1b3e0b4",
          "hiStatus": "DELIVERED",
          "description": "Data sent successfully"
        },
        {
          "careContextReference": "COC497647c1-0627-48fa-8131-0dddc1b3e0b5",
          "hiStatus": "DELIVERED",
          "description": "Data sent successfully"
        }
      ]
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): JWT access token issued by the ABDM session API after successful validation of client id and secret.

## Headers

- `REQUEST-ID` (string, required): Random UUID, a v4 style guid, unique per request.
- `TIMESTAMP` (string, required): ISO 8601 timestamp of when the request was initiated.
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended.
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended. sbx in the sandbox, abdm in production.

## Body

- `notification` (object, required): The transaction id, the session status and each care context's transfer status.
- `notification.transactionId` (string, required)
- `notification.doneAt` (string, required): When the transfer completed.
- `notification.statusNotification` (object, required)
- `notification.statusNotification.sessionStatus` (string, required): TRANSFERRED, PARTIAL_TRANSFERRED or FAILED from the PHR app or health locker; RECEIVED, PARTIAL_RECEIVED or FAILED from the HIU. One of: TRANSFERRED, PARTIAL_TRANSFERRED, RECEIVED, PARTIAL_RECEIVED, FAILED.
- `notification.statusNotification.statusResponses` (object[], required)
- `notification.statusNotification.statusResponses.careContextReference` (string, required)
- `notification.statusNotification.statusResponses.hiStatus` (string, required): DELIVERED or ERRORED from the PHR app or health locker; VALID, CORRUPTED, BLANK or ERRORED from the HIU. One of: DELIVERED, ERRORED, VALID, CORRUPTED, BLANK.
- `notification.statusNotification.statusResponses.description` (string)

## Responses

- `202`: Accepted. The HIE-CM forwards the status to the other side's on-notify callback.
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives


---

# Receive the other side's transfer status

`POST /api/v3/patient-record/on-notify`

**Hosted by the PHR application and by the HIU, not by ABDM.** The HIE-CM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.

This is a callback API for the PHR application and the HIU. This API is used to receive the status of the health record transfer process: the HIU receives what the PHR app sent to notify, and the PHR app receives what the HIU sent.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/patient-record/on-notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'request-id: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'timestamp: 2022-10-06T15:10:00.587Z' \
  --header 'x-hiu-id: HIU_ID' \
  --header 'Content-Type: application/json' \
  --data '{
  "notification": {
    "transactionId": "103a6265-8d5d-411b-9a9d-b460b5f00e4e",
    "doneAt": "2026-03-19T08:01:11.090Z",
    "statusNotification": {
      "sessionStatus": "TRANSFERRED",
      "statusResponses": [
        {
          "careContextReference": "COC497647c1-0627-48fa-8131-0dddc1b3e0b4",
          "hiStatus": "DELIVERED",
          "description": "Data sent successfully"
        }
      ]
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): JWT access token issued by the ABDM session API after successful validation of client id and secret.

## Headers

- `request-id` (string, required): Random UUID, a v4 style guid, unique per callback.
- `timestamp` (string, required): ISO 8601 timestamp of when the callback was sent.
- `x-hiu-id` (string, required): Identifier of the health information user to which the request was intended.

## Body

- `notification` (object, required): The transaction id, the session status and each care context's transfer status.
- `notification.transactionId` (string, required)
- `notification.doneAt` (string, required): When the transfer completed.
- `notification.statusNotification` (object, required)
- `notification.statusNotification.sessionStatus` (string, required): TRANSFERRED, PARTIAL_TRANSFERRED or FAILED from the PHR app or health locker; RECEIVED, PARTIAL_RECEIVED or FAILED from the HIU. One of: TRANSFERRED, PARTIAL_TRANSFERRED, RECEIVED, PARTIAL_RECEIVED, FAILED.
- `notification.statusNotification.statusResponses` (object[], required)
- `notification.statusNotification.statusResponses.careContextReference` (string, required)
- `notification.statusNotification.statusResponses.hiStatus` (string, required): DELIVERED or ERRORED from the PHR app or health locker; VALID, CORRUPTED, BLANK or ERRORED from the HIU. One of: DELIVERED, ERRORED, VALID, CORRUPTED, BLANK.
- `notification.statusNotification.statusResponses.description` (string)

## Responses

- `202`: Accepted.
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives


---

# List the record sharing history of the signed in user

`GET /api/hiecm/patient-record/v3/audit-history`

Retrieve the complete history of record-sharing transactions for a specific user. It provides details of all past and ongoing transactions, including associated care-contexts. The user is the one the X-AUTH-TOKEN was issued to. Filter by date with startDate and endDate, and page with limit and offset.

```bash
curl --request GET \
  --url https://dev.abdm.gov.in/api/hiecm/patient-record/v3/audit-history \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: Bearer <USER_TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): JWT access token issued by the ABDM session API after successful validation of client id and secret.

## Headers

- `REQUEST-ID` (string, required): Random UUID, a v4 style guid, unique per request.
- `TIMESTAMP` (string, required): ISO 8601 timestamp of when the request was initiated.
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended. sbx in the sandbox, abdm in production.
- `X-AUTH-TOKEN` (string, required): JWT access token issued by the PHR service after successful user authentication. If the HIP does not have any role, then it is mandatory.

## Query parameters

- `limit` (integer): The number of records to return.
- `startDate` (string): Start date of the records, ISO 8601.
- `endDate` (string): End date of the records, ISO 8601.
- `offset` (integer): Where to start. When the offset is 0, retrieval starts from the very first record in the dataset.

## Responses

- `200`: The sharing transactions of the user, newest first.

Example 200 response. The values are placeholders:

```json
[
  {
    "requestId": "ed9f451d-9e07-484d-ab68-9972d6529d68",
    "abhaAddress": "manishk1991@sbx",
    "senderFacilityId": "MANISH_PHR_TEST",
    "senderFacilityName": "MANISH-PHR-TEST",
    "receiverFacilityId": "MANISH_HIU",
    "receiverFacilityName": "MANISH_HIU",
    "counterCode": "f4cd0d8e-25ec-465f-993c-01c91a56e0e4",
    "transactionId": "f413b202-16b6-4d4a-9900-5cdcfb8baa50",
    "status": "RECORD_SHARE_REQUESTED",
    "sharedRecordCount": 2,
    "consent": {
      "accessMode": "VIEW",
      "dataEraseAt": "2026-10-12T08:58:09.738Z",
      "careContexts": [
        {
          "patientReference": "manikandanb87@sbx",
          "careContextReference": "COC497647c1-0627-48fa-8131-0dddc1b3e0b4"
        },
        {
          "patientReference": "manikandanb87@sbx",
          "careContextReference": "COC497647c1-0627-48fa-8131-0dddc1b3e0b5"
        }
      ]
    },
    "dateCreated": "2025-12-08T12:04:53.594Z",
    "dateModified": "2025-12-08T12:04:53.594Z"
  }
]
```


---

# Patient scan and record share errors

Seeing a symptom rather than a code? Start at [Troubleshooting](/docs/hiecm/v3/troubleshooting/).

The Patient scan and record share specification records no error code yet. That is a gap in the specification, not a promise that this module cannot fail.

Every code above is recorded in the specification that owns it. The aggregated list across modules is at [error codes](/docs/hiecm/v3/reference/error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# Patient scan and record share

The patient or end-user can log in to the PHR application and use the "Scan and Record share" feature by scanning the facility's QR code.

This process shares the patient's health records with the Health Information User (HIU) system. It ensures secure authentication and consent before sharing sensitive health information. Patients can easily control and transmit their health data to the intended HIU.

## Base URL and X-CM-ID

| Environment | Base URL                   | X-CM-ID |
| ----------- | -------------------------- | ------- |
| Sandbox     | `https://dev.abdm.gov.in`  | `sbx`   |
| Production  | `https://apis.abdm.gov.in` | `abdm`  |

## Terminology

- **Bridge ID** is the client ID provided by NHA to the HIP. It is alphanumeric, for example `SBX_00XXXX`.
- **Service ID** is the facility ID generated from the NHPR application. It is alphanumeric, for example `IN02100000XX`.

## The calls

Each side makes its calls in this order. A callback is a POST from the HIE-CM to the URL registered for your bridge.

| Step | PHR app                                                                                                     | HIU                                                                                                   |
| ---- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| 1    | `POST /api/hiecm/patient-record/v3/share` after scanning the QR code                                        | Receives the share request on `/api/v3/patient-record/share`                                          |
| 2    | Receives the data push URL and key on `/api/v3/patient-record/on-share`                                     | `POST /api/hiecm/patient-record/v3/on-share` with the data push URL and key                           |
| 3    | Posts the encrypted records to the data push URL                                                            | Receives the encrypted records at the data push URL                                                   |
| 4    | `POST /api/hiecm/patient-record/v3/notify`, session status `TRANSFERRED`, `PARTIAL_TRANSFERRED` or `FAILED` | `POST /api/hiecm/patient-record/v3/notify`, session status `RECEIVED`, `PARTIAL_RECEIVED` or `FAILED` |
| 5    | Receives the other side's status on `/api/v3/patient-record/on-notify`                                      | Receives the other side's status on `/api/v3/patient-record/on-notify`                                |
| 6    | `GET /api/hiecm/patient-record/v3/audit-history` for the sharing history                                    |                                                                                                       |

The full operation list is in the [record share API reference](/reference/hiecm-record-share).


---

# Share patient open order

`POST /api/hiecm/scan-gateway/v3/patient/share/open-order`

This is an API will be invoked from the **integrator application** to share the user/patient profile with HMIS/LIMS.

 **Header**

Authorisation will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

X-AUTH-TOKEN JWT Authentication token which was issued by ABDM after successful validation of user[ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-CM-ID consent manager ID[ Example: sbx ]

X-HIU-ID [ Example: HIU ID ]

 **Request Body**

intent This is a key value pair which contains the purpose [ Example: type: OPEN_PAYMENT_ORDER ]

metaData This is a key value pair which contains hipId, counterId[ Example: { hipId:IN3810000008
 counterId: 12123 } ]

profile which contains user details

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/scan-gateway/v3/patient/share/open-order \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "intent": "OPEN_PAYMENT_ORDER",
  "metaData": {
    "hipId": "HIP_1",
    "counterId": "123-456"
  },
  "profile": {
    "patient": {
      "abhaNumber": "91-7507-xxxx-xxxx",
      "abhaAddress": "<ABHA_ADDRESS>",
      "name": "name",
      "gender": "M",
      "dayOfBirth": "string",
      "monthOfBirth": "string",
      "yearOfBirth": "string",
      "address": {
        "line": "Address line 1",
        "district": "XXXXXXX",
        "state": "XXXXXX",
        "pincode": "XXXXXX"
      },
      "phoneNumber": "987654xxxx"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `intent` (string, required): The intention of share API call
- `metaData` (object, required): A key-value pair carrying the location longitude and latitude.
- `metaData.hipId` (string, required): The service ID of the health information provider
- `metaData.counterId` (number, required)
- `profile` (object, required): This should populated only for PAYMENT_SHARE
- `profile.patient` (object, required)
- `profile.patient.abhaNumber` (string, required): The abha number of the patient. Should be only 14 digit
- `profile.patient.abhaAddress` (string, required): The abha address of the patient. Should start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx
- `profile.patient.name` (string, required): The name of the patient. Only alphabets.
- `profile.patient.gender` (string, required): The gender of the patient One of: M, F, O, D.
- `profile.patient.dayOfBirth` (string, required): The day of birth of the patient. Only allows numeric values between 1 abd 31
- `profile.patient.monthOfBirth` (string, required): The month of birth of the patient. Only allows numeric values between 1 abd 12
- `profile.patient.yearOfBirth` (string, required): The month of birth of the patient. Only allows numeric values and must be 4 digit ranging between 1900 and 2200
- `profile.patient.address` (object, required)
- `profile.patient.address.line` (string, required): The address line
- `profile.patient.address.district` (string): The district and should only contain alphabets
- `profile.patient.address.state` (string): The state and should only contain alphabets
- `profile.patient.address.pincode` (string): Should be 5 digits and only contain numbers
- `profile.patient.phoneNumber` (string, required): The mobile number of the patient. Must be 10 digit and contain only 0-9

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - no mapping found to the resp.requestId cache. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `429`: Too Many Requests
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2429 - Too Many Requests found. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Receive the patient on-share

`POST /v3/patient/on-share/open-order`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This is a callback API for patient on-share. This API needs to implement by HIU for receive all the open order.

 **Header**

Authorisation will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-HIU-ID [Example: HIU_ID]

 **Request Body**

intent This is a key value pair which contains the purpose [ Example: type: OPEN_PAYMENT_ORDER ]

ABHA Address of the user/patient.

error is optional object in case of any error or Failure then only send error object

Procedures which contains the list of open order

response which contains the requestId [ Example: resquestId: 059fcb69-8ad8-4789-a049-62db16c7b5a0 ]

```bash
curl --request POST \
  --url {bridgeUrl}/v3/patient/on-share/open-order \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "intent": "OPEN_PAYMENT_ORDER",
  "abhaAddress": "<ABHA_ADDRESS>",
  "patientUid": "string5",
  "procedures": [
    {
      "category": "OPD consultation",
      "services": [
        {
          "name": "consultation",
          "serviceId": "service-12345",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    },
    {
      "category": "Laboratory and Diagnostics",
      "services": [
        {
          "name": "Diagnostics",
          "serviceId": "service-12346",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    },
    {
      "category": "Pharmacy",
      "services": [
        {
          "name": "Pharmacy",
          "serviceId": "service-12347",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    },
    {
      "category": "Miscellaneous/Other",
      "services": [
        {
          "name": "Miscellaneous",
          "serviceId": "service-12348",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    }
  ],
  "response": {
    "requestId": "6c3d4e5c-09d1-4ecc-817b-a0c82d130c53"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `intent` (string, required): The intention of share API call
- `abhaAddress` (string, required): The abha address of the patient. Should start with Alphanumeric . and _ in the middle and must be ending with @abdm or @sbx
- `patientUid` (string, required)
- `procedures` (object[], required)
- `procedures.category` (string, required): The category of the procedure
- `procedures.services` (object[], required)
- `procedures.services.serviceId` (string): Unique identifier for the service
- `procedures.services.name` (string, required): Name of the service
- `procedures.services.description` (string): Description of the service
- `procedures.services.amount` (number, required): Amount for the service
- `response` (object): This is the response request-id which is generated from the share API
- `response.requestId` (string, required)

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Select the all open-order and send to HIP for a payment request detail

`POST /api/hiecm/scan-gateway/v3/patient/selection`

Select the all open-order and send to HIP for a payment request detail. In this user can select the multiple procedures.

 **Header**

Authorisation will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-CM-ID consent manager ID[ Example: sbx ]

X-AUTH-TOKEN JWT Authentication token which was issued by ABDM after successful validation of user[ Example: Bearer ]

X-HIU-ID [ Example: HIU ID ]

 **Request Body**

intent This is a key value pair which contains the purpose [ Example: type: PAYMENT_ORDER ]

openOrderRequestId from the share open order requestId [ Example: 059fcb69-****-4789-a049-62db16c7b5a0 ]

 abhaAddress of the user/patient

Procedures which contains the list of open order

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/scan-gateway/v3/patient/selection \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "intent": "PAYMENT_ORDER",
  "openOrderRequestId": "b767614f-153a-***-946f-1622596f0fab",
  "abhaAddress": "<ABHA_ADDRESS>",
  "procedures": [
    {
      "category": "OPD consultation",
      "services": [
        {
          "name": "consultation",
          "serviceId": "service-12345",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    },
    {
      "category": "Laboratory and Diagnostics",
      "services": [
        {
          "name": "Diagnostics",
          "serviceId": "service-12345",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    },
    {
      "category": "Pharmacy",
      "services": [
        {
          "name": "Pharmacy",
          "serviceId": "service-12345",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    }
  ]
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `intent` (string, required): The intention of share API call
- `openOrderRequestId` (object, required): This is the response request-id which is generated from the share/openOrder api
- `abhaAddress` (string, required): abha address of the user/patient.
- `procedures` (object[], required)
- `procedures.category` (string, required): The category of the procedure
- `procedures.services` (object[], required)
- `procedures.services.serviceId` (string): Unique identifier for the service
- `procedures.services.name` (string, required): Name of the service
- `procedures.services.description` (string): Description of the service
- `procedures.services.amount` (number, required): Amount for the service

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - no mapping found to the resp.requestId cache. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `429`: Too Many Requests
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2429 - Too Many Requests found. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Receive the patient on selection

`POST /v3/patient/on-selection`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This is callback API for the on-selection API. This API needs to implement by HIU to received all the select open order payment requests.

 **Header**

X-HIU-ID [Example: HIU_ID]

Authorisation will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

 **Request Body**

intent This is a key value pair which contains the purpose [ Example: type: PAYMENT_ORDER ]

openOrderRequestId from the share open order requestId [ Example: 059fcb69-****-4789-a049-62db16c7b5a0 ]

ABHA address of the user

error is optional object in case of any error or Failure then only send error object

Procedures which contains the list of open order

Payment bundle: which contains payment details.

response which contains the requestId [ Example: requestId: 059fcb69-8ad8-4789-a049-62db16c7b5a0 ]

```bash
curl --request POST \
  --url {bridgeUrl}/v3/patient/on-selection \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "intent": "PAYMENT_ORDER",
  "openOrderRequestId": "b767614f-153a-4aa3-946f-1622596f0fab",
  "abhaAddress": "<ABHA_ADDRESS>",
  "procedures": [
    {
      "category": "OPD consultation",
      "services": [
        {
          "name": "consultation",
          "serviceId": "service-12345",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    },
    {
      "category": "Laboratory and Diagnostics",
      "services": [
        {
          "name": "Diagnostics",
          "serviceId": "service-12346",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    },
    {
      "category": "Pharmacy",
      "services": [
        {
          "name": "Pharmacy",
          "serviceId": "service-12347",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    }
  ],
  "paymentBundle": {
    "paymentMode": "GATEWAY",
    "paymentUrl": "string",
    "orderNumber": "string",
    "amount": "1250.55",
    "merchantId": "123465",
    "description": "Testing"
  },
  "response": {
    "requestId": "b767614f-153a-4aa3-946f-1622596f0fab"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `intent` (string, required): The intention of share API call
- `openOrderRequestId` (object, required): This is the response request-id which is generated from the share api
- `abhaAddress` (string, required)
- `procedures` (object[], required)
- `procedures.category` (string, required): The category of the procedure
- `procedures.services` (object[], required)
- `procedures.services.serviceId` (string): Unique identifier for the service
- `procedures.services.name` (string, required): Name of the service
- `procedures.services.description` (string): Description of the service
- `procedures.services.amount` (number, required): Amount for the service
- `paymentBundle` (object, required): This should be populated for payments
- `paymentBundle.paymentMode` (string, required): Specifies the mode of payment. For example, “GATEWAY” indicates that the payment is processed through a payment gateway
- `paymentBundle.paymentUrl` (string, required): A URL provided by the payment gateway for processing the payment. This is typically a link where the user can complete the payment transaction.
- `paymentBundle.orderNumber` (string, required): A unique identifier for the order associated with the payment. This helps in tracking and referencing the specific transaction.
- `paymentBundle.amount` (string, required): The total amount to be paid. This is usually a numeric value representing the cost of the transaction.
- `paymentBundle.merchantId` (string, required): A unique identifier for the merchant receiving the payment. This ID is used to identify the merchant in the payment system.
- `paymentBundle.description` (string, required): A brief description of the payment or the transaction. This can include details about what the payment is for or any other relevant information.
- `response` (object, required): This is the response request-id which is generated from the share api
- `response.requestId` (string, required)

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Notify patient scan pay

`POST /v3/patient/scan-pay/notify`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This is callback API for the notify API. This API needs to implement by HIU to received the payment status.

 **Header**

X-HIU-ID [Example: HIU_ID]

Authorisation will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

 **Request Body**

acknowledgement This is a key value which contains the payment status abhaAddress transactionId orderNumber paymentRecipetURL[ Example: { status: [SUCCESS, CANCELED, PENDING, FAIL, REFUND_INITIATED, REFUND_SUCCESS] abhaAddress: transactionId: uniqueId orderNumber: 76274**** openOrderRequestId: 3876e71 paymentDate: 12314 paymentRecipetURL: URL } ]

```bash
curl --request POST \
  --url {bridgeUrl}/v3/patient/scan-pay/notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "acknowledgement": {
    "status": "SUCCESS/ CANCELED/ PENDING/ FAIL/ REFUND_INITIATED/ REFUND_SUCCESS",
    "abhaAddress": "<username>@sbx",
    "transactionId": "string",
    "orderNumber": "string",
    "openOrderRequestId": "b767614f-153a-4aa3-946f-1622596f0fab",
    "paymentDate": "2025-01-20T07:47:49.102Z",
    "paymentRecipetLink": "PDF URL LINK of RECIPT"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `acknowledgement` (object, required): The intention of share API call
- `acknowledgement.status` (string, required): Indicates the outcome of the transaction. Possible values are: SUCCESS: The transaction was completed successfully. FAIL: The transaction failed. CANCELED: The transaction was cancelled. PENDING: The transaction in pending. REFUND_INITIATED: refund initiated. REFUND_SUCCESS: refunded successfully
- `acknowledgement.abhaAddress` (string, required): The abha addresss of the user, formatted as . This is a unique identifier for the user in the health system.
- `acknowledgement.transactionId` (string, required): A unique identifier for the transaction. This helps in tracking and referencing the specific transaction.
- `acknowledgement.orderNumber` (string, required): A unique identifier for the order associated with the transaction. This helps in tracking and referencing the specific order.
- `acknowledgement.openOrderRequestId` (object, required): This is the response request-id which is generated from the share/openOrder api
- `acknowledgement.paymentDate` (string, required): ISO Timestamp.
- `acknowledgement.paymentRecipetLink` (string, required): This attribute holds the URL link to the payment receipt. It is a string that provides a direct link to a PDF document or other format of the receipt for the transaction.

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Notify to HIP so that confirm that the HIU received the payment status

`POST /api/hiecm/scan-gateway/v3/patient/scan-pay/on-notify`

Notify to HIP so that confirm that the HIU received the payment status. This HIU will confirm the we will received the payment bundle(SUCCESS,CANCELED,PENDING,FAIL,REFUND_INITIATED, REFUND_SUCCESS) from HIP.

 **Header**

AUTHORIZATION will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-CM-ID consent manager ID[ Example: sbx ]

 **Request Body**

acknowledgement This is a key value which contains the payment status abhaAddress transactionId orderNumber paymentRecipetURL[ Example: { status: [SUCCESS, CANCELED, PENDING, FAIL, REFUND_INITIATED, REFUND_SUCCESS] abhaAddress: transactionId: uniqueId orderNumber: 76274**** openOrderRequestId: 939** 800-325d-42c3-****-1******* paymentDate: 2025-01-20T07:47:49.102Z paymentRecipetURL: URL } ]

error is optional object in case of any error or Failure then only send error object

response which contains the requestId [ Example: requestId: 059fcb69-8ad8-4789-a049-62db16c7b5a0 ]

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/scan-gateway/v3/patient/scan-pay/on-notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "acknowledgement": {
    "status": "SUCCESS/ CANCELED/ PENDING/ FAIL/ REFUND_INITIATED/ REFUND_SUCCESS",
    "abhaAddress": "<username>@sbx",
    "transactionId": "string",
    "orderNumber": "string",
    "openOrderRequestId": "b767614f-153a-4aa3-946f-1622596f0fab",
    "paymentDate": "2025-01-20T07:47:49.102Z",
    "paymentRecipetLink": "PDF URL LINK of RECIPT"
  },
  "response": {
    "requestId": "b767614f-153a-***-946f-1622596f0fab"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `acknowledgement` (object, required): error is optional, incase of success case.
- `acknowledgement.status` (string, required): Indicates the outcome of the transaction. Possible values are: SUCCESS: The transaction was completed successfully. FAIL: The transaction failed. CANCELED: The transaction was cancelled. PENDING: The transaction in pending. REFUND_INITIATED: refund initiated. REFUND_SUCCESS: refunded successfully
- `acknowledgement.abhaAddress` (string, required): The health ID of the user, formatted as . This is a unique identifier for the user in the health system.
- `acknowledgement.transactionId` (string, required): A unique identifier for the transaction. This helps in tracking and referencing the specific transaction.
- `acknowledgement.orderNumber` (string, required): A unique identifier for the order associated with the transaction. This helps in tracking and referencing the specific order.
- `acknowledgement.openOrderRequestId` (object, required): This is the response request-id which is generated from the share/openOrder api
- `acknowledgement.paymentDate` (string, required): ISO Timestamp.
- `acknowledgement.paymentRecipetLink` (string, required): This attribute holds the URL link to the payment receipt. It is a string that provides a direct link to a PDF document or other format of the receipt for the transaction. The intention of share API call
- `response` (object, required): This is the response request-id which is generated from the share api
- `response.requestId` (string, required)

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - no mapping found to the resp.requestId cache. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `429`: Too Many Requests
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2429 - Too Many Requests found. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Check the status of reports

`POST /api/hiecm/scan-gateway/v3/patient/scan-pay/order-status`

Check the status of reports. If the notification is not get from HIP then this API will help to check the status on HIU side.

 **Header**

Authorisation will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

X-AUTH-TOKEN JWT Authentication token which was issued by ABDM after successful validation of user[ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-CM-ID consent manager ID[ Example: sbx ]

X-HIU-ID [ EXample: HIU_ID]

 **Request Body**

 queryStatus which contains the orderNumber and requestId[ Example: { orderNumber: 39413413 abhaAddress: openOrderRequestId: 059fcb69-8ad8-***-a049-62db16c7b5a0 } ]

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/scan-gateway/v3/patient/scan-pay/order-status \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "queryStatus": {
    "orderNumber": "string",
    "abhaAddress": "<ABHA_ADDRESS>",
    "openOrderRequestId": "0d8bd16b-117c-4d07-9916-109fe3a9ab88"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `queryStatus` (object, required): The queryStatus is used to check the status of a specific order and its associated patient-share request.
- `queryStatus.orderNumber` (string, required): A unique identifier for the order. This helps in tracking and referencing the specific order associated with the query.
- `queryStatus.abhaAddress` (string, required): abha address of the user/patient.
- `queryStatus.openOrderRequestId` (string, required): The request id is generated from the /share/Open Order Request id

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - no mapping found to the resp.requestId cache. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `429`: Too Many Requests
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2429 - Too Many Requests found. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Receive the patient scan pay on order status

`POST /v3/patient/scan-pay/on-order-status`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This is callback for the on-order-status API. This API needs to implement by HIU for receive the payment status.

 **Header**

 X-HIU-ID [Example: HIU_ID]

Authorisation will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

 **Request Body**

acknowledgement This is a key value which contains the payment status abhaAddress transactionId orderNumber paymentRecipetURL[ Example: { status: [SUCCESS, CANCELED, PENDING, FAIL, REFUND_INITIATED, REFUND_SUCCESS] abhaAddress: transactionId: uniqueId orderNumber: 76274**** paymentRecipetURL: URL } ]

resp which contains the requestId [ Example: requestId: 059fcb69-8ad8-4789-a049-62db16c7b5a0 ]

```bash
curl --request POST \
  --url {bridgeUrl}/v3/patient/scan-pay/on-order-status \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIU-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "acknowledgement": {
    "status": "SUCCESS/ CANCELED/ PENDING/ FAIL/ REFUND_INITIATED/ REFUND_SUCCESS",
    "abhaAddress": "<username>@sbx",
    "transactionId": "string",
    "orderNumber": "string",
    "openOrderRequestId": "Queried Request id",
    "paymentDate": "Transaction Date UTC",
    "paymentRecipetLink": "PDF URL LINK of RECIPT"
  },
  "response": {
    "requestId": "b767614f-153a-4aa3-946f-1622596f0fab"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-HIU-ID` (string, required): Identifier of the health information user to which the request was intended

## Body

- `acknowledgement` (object, required): The intention of share API call
- `acknowledgement.status` (string, required): Indicates the outcome of the transaction. Possible values are: SUCCESS: The transaction was completed successfully. FAIL: The transaction failed. CANCELED: The transaction was cancelled. PENDING: The transaction in pending. REFUND_INITIATED: refund initiated. REFUND_SUCCESS: refunded successfully
- `acknowledgement.abhaAddress` (string, required): The abha Address of the user, formatted as . This is a unique identifier for the user in the health system.
- `acknowledgement.transactionId` (string, required): A unique identifier for the transaction. This helps in tracking and referencing the specific transaction.
- `acknowledgement.orderNumber` (string, required): A unique identifier for the order associated with the transaction. This helps in tracking and referencing the specific order.
- `acknowledgement.openOrderRequestId` (string, required): The unique identifier for the queried request. This ID is used to track and reference the specific request within the system.
- `acknowledgement.paymentDate` (string, required): he date and time when the transaction occurred, formatted in UTC
- `acknowledgement.paymentRecipetLink` (string, required): This attribute holds the URL link to the payment receipt. It is a string that provides a direct link to a PDF document or other format of the receipt for the transaction.
- `response` (object, required): This is the response request-id which is generated from the share api
- `response.requestId` (string, required)

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Check the status of reports

`POST /v3/patient/share/open-order`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This is an API is called by HIU to check the status of reports.

 **Header**

Authorisation will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-HIP-ID [ Example: HIP ID ]

 **Request Body**

intent This is a key value pair which contains the purpose [ Example: type: OPEN_PAYMENT_ORDER ]

metaData This is a key value pair which contains hipId and counterId[ Example: { hipId: IN3810000008 counterId:12123 } ]

profile which contains user details

```bash
curl --request POST \
  --url {bridgeUrl}/v3/patient/share/open-order \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "intent": "OPEN_PAYMENT_ORDER",
  "metaData": {
    "hipId": "HIP_1",
    "counterId": 1
  },
  "profile": {
    "patient": {
      "abhaNumber": "91-7507-xxxx-xxxx",
      "abhaAddress": "<ABHA_ADDRESS>",
      "name": "name",
      "gender": "M",
      "dayOfBirth": "string",
      "monthOfBirth": "string",
      "yearOfBirth": "string",
      "address": {
        "line": "Address line 1",
        "district": "XXXXXXX",
        "state": "XXXXXX",
        "pincode": "XXXXXX"
      },
      "phoneNumber": "987654xxxx"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `intent` (string, required): The intention of share API call
- `metaData` (object, required): A key-value pair carrying the location longitude and latitude.
- `metaData.hipId` (string, required): The service ID of the health information provider
- `metaData.counterId` (number, required): it describes the counterId.
- `profile` (object, required): This should populated only for PAYMENT_SHARE
- `profile.patient` (object, required)
- `profile.patient.abhaNumber` (string, required): The abha number of the patient. Should be only 14 digit
- `profile.patient.abhaAddress` (string, required): The abha address of the patient. Should start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx
- `profile.patient.name` (string, required): The name of the patient. Only alphabets.
- `profile.patient.gender` (string, required): The gender of the patient One of: M, F, O, D.
- `profile.patient.dayOfBirth` (string): The day of birth of the patient. Only allows numeric values between 1 abd 31
- `profile.patient.monthOfBirth` (string): The month of birth of the patient. Only allows numeric values between 1 abd 12
- `profile.patient.yearOfBirth` (string, required): The month of birth of the patient. Only allows numeric values and must be 4 digit ranging between 1900 and 2200
- `profile.patient.address` (object, required)
- `profile.patient.address.line` (string, required): The address line
- `profile.patient.address.district` (string): The district and should only contain alphabets
- `profile.patient.address.state` (string): The state and should only contain alphabets
- `profile.patient.address.pincode` (string): Should be 5 digits and only contain numbers
- `profile.patient.phoneNumber` (string): The mobile number of the patient. Must be 10 digit and contain only 0-9

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Submit the HIE-CM to send all the open order for patient

`POST /api/hiecm/scan-gateway/v3/patient/on-share/open-order`

Share the response of HIECM's /hiecm/api/v3/scan-gateway/patient/on-share/open API.

 **Header**

AUTHORIZATION will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-CM-ID consent manager ID [ Example: sbx ]

 **Request Body**

intent This is a key value pair which contains the purpose [ Example: type: OPEN_PAYMENT_ORDER ]

ABHA address of the user.

PatientUid of the user.

error is optional object in case of any error or Failure then only send error object

procedures which contains the list of open order

response which contains the requestId [ Example: requestId: 059fcb69-8ad8-4789-a049-62db16c7b5a0 ]

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/scan-gateway/v3/patient/on-share/open-order \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "intent": "OPEN_PAYMENT_ORDER",
  "abhaAddress": "<ABHA_ADDRESS>",
  "patientUid": "string",
  "procedures": [
    {
      "category": "OPD consultation",
      "services": [
        {
          "name": "consultation",
          "serviceId": "service-12345",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    },
    {
      "category": "Laboratory and Diagnostics",
      "services": [
        {
          "name": "Diagnostics",
          "serviceId": "service-12345",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    },
    {
      "category": "Pharmacy",
      "services": [
        {
          "name": "Pharmacy",
          "serviceId": "service-12345",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    },
    {
      "category": "Miscellaneous/Other",
      "services": [
        {
          "name": "Miscellaneous",
          "serviceId": "service-12345",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    }
  ],
  "response": {
    "requestId": "6c3d4e5c-09d1-****-817b-a0c82d130c53"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `intent` (string, required): The intention of share API call
- `abhaAddress` (string, required): The abha address of the patient. Should start with Alphanumeric . and _ in the middle and must be ending with @abdm or @sbx
- `patientUid` (string, required): Patient UId(unique ID).
- `procedures` (object[], required)
- `procedures.category` (string, required): The category of the procedure
- `procedures.services` (object[], required)
- `procedures.services.serviceId` (string): Unique identifier for the service
- `procedures.services.name` (string, required): Name of the service
- `procedures.services.description` (string): Description of the service
- `procedures.services.amount` (number, required): Amount for the service
- `response` (object, required): This is the response request-id which is generated from the share API
- `response.requestId` (string, required)

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - no mapping found to the resp.requestId cache. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `429`: Too Many Requests
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2429 - Too Many Requests found. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Receive the patient selection

`POST /v3/patient/selection`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This is the call back API for the selection API. This API needs to implement by HIP to receive all selected open order.

 **Header**

Authorisation will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-HIP-ID consent manager ID[ Example: sbx ]

 **Request Body**

intent This is a key value pair which contains the purpose [ Example: type: PAYMENT_ORDER ]

openOrderRequestId from the share open order requestId [ Example: 059fcb69-****-4789-a049-62db16c7b5a0 ]

ABHA address of the user

Procedures which contains the list of open order

Payment Bundle: which contains payment detail.

```bash
curl --request POST \
  --url {bridgeUrl}/v3/patient/selection \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "intent": "PAYMENT_ORDER",
  "openOrderRequestId": "6c3d4e5c-09d1-4ecc-817b-a0c82d130c53",
  "abhaAddress": "<ABHA_ADDRESS>",
  "procedures": [
    {
      "category": "OPD consultation",
      "services": [
        {
          "name": "consultation",
          "serviceId": "service-12345",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    },
    {
      "category": "Laboratory and Diagnostics",
      "services": [
        {
          "name": "Diagnostics",
          "serviceId": "service-12346",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    },
    {
      "category": "Pharmacy",
      "services": [
        {
          "name": "Pharmacy",
          "serviceId": "service-12347",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    }
  ]
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `intent` (string, required): The intention of share API call
- `openOrderRequestId` (object, required): This is the response request-id which is generated from the share API
- `abhaAddress` (string, required): The abha address of the patient. Should start with Alphanumeric . and _ in the middle and must be ending with @abdm or @sbx
- `procedures` (object[], required)
- `procedures.category` (string, required): The category of the procedure
- `procedures.services` (object[], required)
- `procedures.services.serviceId` (string): Unique identifier for the service
- `procedures.services.name` (string, required): Name of the service
- `procedures.services.description` (string): Description of the service
- `procedures.services.amount` (number, required): Amount for the service

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Share payment bundle alone with procedures of the patient

`POST /api/hiecm/scan-gateway/v3/patient/on-selection`

Share payment bundle alone with procedures of the patient. The HIP will sent the payment bundle to HIU.

 **Header**

AUTHORIZATION will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-CM-ID consent manager ID[ Example: sbx ]

 **Request Body**

intent This is a key value pair which contains the purpose [ Example: type: PAYMENT_ORDER ]

openOrderRequestId from the share open order requestId [ Example: 059fcb69-****-4789-a049-62db16c7b5a0 ]

abhaAddress of the user/patient

error is optional object in case of any error or Failure then only send error object

Procedures which contains the list of open order

paymentBundle which contains payments details

response which contains the requestId [ Example: requestId: 059fcb69-8ad8-4789-a049-62db16c7b5a0 ]

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/scan-gateway/v3/patient/on-selection \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "intent": "PAYMENT_ORDER",
  "openOrderRequestId": "b767614f-153a-4aa3-946f-1622596f0fab",
  "abhaAddress": "<ABHA_ADDRESS>",
  "procedures": [
    {
      "category": "OPD consultation",
      "services": [
        {
          "name": "consultation",
          "serviceId": "service-12345",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    },
    {
      "category": "Laboratory and Diagnostics",
      "services": [
        {
          "name": "Diagnostics",
          "serviceId": "service-12345",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    },
    {
      "category": "Pharmacy",
      "services": [
        {
          "name": "Pharmacy",
          "serviceId": "service-12345",
          "description": "Albumin 24 hrs Urine",
          "amount": 629.12
        }
      ]
    }
  ],
  "paymentBundle": {
    "paymentMode": "GATEWAY",
    "paymentUrl": "string",
    "orderNumber": "string",
    "amount": 1250.55,
    "merchantId": "123465",
    "description": "Testing"
  },
  "response": {
    "requestId": "6c3d4e5c-09d1-***-817b-a0c82d130c53"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `intent` (string, required): The intention of share API call
- `openOrderRequestId` (object, required): This is the request-id which is generated from the share/Open Order Request id api
- `abhaAddress` (string, required): abha address of the user/patient.
- `procedures` (object[], required)
- `procedures.category` (string, required): The category of the procedure
- `procedures.services` (object[], required)
- `procedures.services.serviceId` (string): Unique identifier for the service
- `procedures.services.name` (string, required): Name of the service
- `procedures.services.description` (string): Description of the service
- `procedures.services.amount` (number, required): Amount for the service
- `paymentBundle` (object, required): This should be populated for payments
- `paymentBundle.paymentMode` (string, required): Specifies the mode of payment. For example, “GATEWAY” indicates that the payment is processed through a payment gateway
- `paymentBundle.paymentUrl` (string, required): A URL provided by the payment gateway for processing the payment. This is typically a link where the user can complete the payment transaction.
- `paymentBundle.orderNumber` (string, required): A unique identifier for the order associated with the payment. This helps in tracking and referencing the specific transaction.
- `paymentBundle.amount` (number, required): The total amount to be paid. This is usually a numeric value representing the cost of the transaction.
- `paymentBundle.merchantId` (string, required): A unique identifier for the merchant receiving the payment. This ID is used to identify the merchant in the payment system.
- `paymentBundle.description` (string, required): A brief description of the payment or the transaction. This can include details about what the payment is for or any other relevant information.
- `response` (object, required): This is the response request-id which is generated randomly.
- `response.requestId` (string, required)

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - no mapping found to the resp.requestId cache. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `429`: Too Many Requests
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2429 - Too Many Requests found. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Send the payment status to HIU

`POST /api/hiecm/scan-gateway/v3/patient/scan-pay/notify`

Send the payment status to HIU.

 **Header**

Authorisation will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-CM-ID consent manager ID[ Example: sbx ]

 X-HIP-ID [Example: HIP_ID]

 **Request Body**

acknowledgement This is a key value which contains the payment status abhaAddress transactionId orderNumber paymentRecipetURL[ Example: { status: [SUCCESS, CANCELED, PENDING, FAIL, REFUND_INITIATED, REFUND_SUCCESS] abhaAddress: transactionId: uniqueId orderNumber: 76274**** openOrderRequestId: 939** 800-325d-42c3-****-1******* paymentDate: 2025-01-20T07:47:49.102Z paymentRecipetURL: URL } ]

error is optional object in case of any error or Failure then only send error object

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/scan-gateway/v3/patient/scan-pay/notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "acknowledgement": {
    "status": "SUCCESS/ CANCELED/ PENDING/ FAIL/ REFUND_INITIATED/ REFUND_SUCCESS",
    "abhaAddress": "<username>@sbx",
    "transactionId": "string",
    "orderNumber": "string",
    "openOrderRequestId": "b767614f-153a-4aa3-946f-1622596f0fab",
    "paymentDate": "2025-01-20T07:47:49.102Z",
    "paymentRecipetLink": "PDF URL LINK of RECIPT"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `acknowledgement` (object, required): The intention of share API call
- `acknowledgement.status` (string, required): Indicates the outcome of the transaction. Possible values are: SUCCESS: The transaction was completed successfully. FAIL: The transaction failed. CANCELED: The transaction was cancelled. PENDING: The transaction in pending. REFUND_INITIATED: refund initiated. REFUND_SUCCESS: refunded successfully
- `acknowledgement.abhaAddress` (string, required): The abha addresss of the user, formatted as . This is a unique identifier for the user in the health system.
- `acknowledgement.transactionId` (string, required): A unique identifier for the transaction. This helps in tracking and referencing the specific transaction.
- `acknowledgement.orderNumber` (string, required): A unique identifier for the order associated with the transaction. This helps in tracking and referencing the specific order.
- `acknowledgement.openOrderRequestId` (object, required): This is the response request-id which is generated from the share/openOrder api
- `acknowledgement.paymentDate` (string, required): ISO Timestamp.
- `acknowledgement.paymentRecipetLink` (string, required): This attribute holds the URL link to the payment receipt. It is a string that provides a direct link to a PDF document or other format of the receipt for the transaction.

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - no mapping found to the resp.requestId cache. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `429`: Too Many Requests
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2429 - Too Many Requests found. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Receive the patient scan pay on notify

`POST /v3/patient/scan-pay/on-notify`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This is an callback API for on-notify API need to implement by HIP to received the confirmation of notification.

 **Header**

Authorisation will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-HIP-ID [ Example: HIP ID ]

 **Request Body**

acknowledgement This is a key value which contains the payment status abhaAddress transactionId orderNumber paymentRecipetURL[ Example: { status: [SUCCESS, CANCELED, PENDING, FAIL, REFUND_INITIATED, REFUND_SUCCESS] abhaAddress: transactionId: uniqueId orderNumber: 76274**** paymentRecipetURL: URL } ]

error is optional object in case of any error or Failure then only send error object

response which contains the requestId [ Example: requestId: 059fcb69-8ad8-4789-a049-62db16c7b5a0 ]

```bash
curl --request POST \
  --url {bridgeUrl}/v3/patient/scan-pay/on-notify \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "acknowledgement": {
    "status": "SUCCESS/ CANCELED/ PENDING/ FAIL/ REFUND_INITIATED/ REFUND_SUCCESS",
    "abhaAddress": "<username>@sbx",
    "transactionId": "string",
    "orderNumber": "string",
    "openOrderRequestId": "b767614f-153a-4aa3-946f-1622596f0fab",
    "paymentDate": "2025-01-20T07:47:49.102Z",
    "paymentRecipetLink": "PDF URL LINK of RECIPT"
  },
  "response": {
    "requestId": "b767614f-153a-4aa3-946f-1622596f0fab"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `acknowledgement` (object, required)
- `acknowledgement.status` (string, required): Indicates the outcome of the transaction. Possible values are: SUCCESS: The transaction was completed successfully. FAIL: The transaction failed. CANCELED: The transaction was cancelled. PENDING: The transaction in pending. REFUND_INITIATED: refund initiated. REFUND_SUCCESS: refunded successfully
- `acknowledgement.abhaAddress` (string, required): The abha addresss of the user, formatted as . This is a unique identifier for the user in the health system.
- `acknowledgement.transactionId` (string, required): A unique identifier for the transaction. This helps in tracking and referencing the specific transaction.
- `acknowledgement.orderNumber` (string, required): A unique identifier for the order associated with the transaction. This helps in tracking and referencing the specific order.
- `acknowledgement.openOrderRequestId` (object, required): This is the response request-id which is generated from the share/openOrder api
- `acknowledgement.paymentDate` (string, required): ISO Timestamp.
- `acknowledgement.paymentRecipetLink` (string, required): This attribute holds the URL link to the payment receipt. It is a string that provides a direct link to a PDF document or other format of the receipt for the transaction.
- `response` (object, required): This is the response request-id which is generated from the share api
- `response.requestId` (string, required)

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Receive the patient scan pay order status

`POST /v3/patient/scan-pay/order-status`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This is callback API for the order_status API. This API needs to implement by HIP to receive the request for payment status.

 **Header**

Authorisation will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-HIP-ID [ Example: HIP ID ]

 **Request Body**

 queryStatus which contains the orderNumber and requestId[ Example: { orderNumber: 39413413 abhaAddress: requestId: 059fcb69-8ad8-4789-a049-62db16c7b5a0 } ]

```bash
curl --request POST \
  --url {bridgeUrl}/v3/patient/scan-pay/order-status \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "queryStatus": {
    "orderNumber": "string",
    "abhaAddress": "<ABHA_ADDRESS>",
    "openOrderRequestId": "0d8bd16b-117c-4d07-9916-109fe3a9ab88"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `queryStatus` (object, required): The queryStatus is used to check the status of a specific order and its associated patient-share request.
- `queryStatus.orderNumber` (string, required): A unique identifier for the order. This helps in tracking and referencing the specific order associated with the query.
- `queryStatus.abhaAddress` (string, required): abha address of the user/patient.
- `queryStatus.openOrderRequestId` (string, required): A unique identifier for the patient-share request. This ID is used to track and reference the specific request within the system.

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Check the status of reports

`POST /api/hiecm/scan-gateway/v3/patient/scan-pay/on-order-status`

Check the status of reports.

 **Header**

AUTHORIZATION will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: ]

X-CM-ID consent manager ID[ Example: sbx ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

 **Request Body**

acknowledgement This is a key value which contains the payment status abhaAddress transactionId orderNumber paymentRecipetURL[ Example: { status: [SUCCESS, CANCELED, PENDING, FAIL, REFUND_INITIATED, REFUND_SUCCESS] abhaAddress: transactionId: uniqueId orderNumber: 76274**** paymentRecipetURL: URL } ]

error is optional object in case of any error or Failure then only send error object

response which contains the requestId [ Example: requestId: 059fcb69-8ad8-4789-a049-62db16c7b5a0 ]

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/scan-gateway/v3/patient/scan-pay/on-order-status \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "acknowledgement": {
    "status": "SUCCESS/ CANCELED/ PENDING/ FAIL/ REFUND_INITIATED/ REFUND_SUCCESS",
    "abhaAddress": "<username>@sbx",
    "transactionId": "string",
    "orderNumber": "string",
    "openOrderRequestId": "Queried Request id",
    "paymentDate": "Transaction Date UTC",
    "paymentRecipetLink": "PDF URL LINK of RECIPT"
  },
  "response": {
    "requestId": "b767614f-153a-***-946f-1622596f0fab"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `acknowledgement` (object, required): The intention of share API call
- `acknowledgement.status` (string, required): Indicates the outcome of the transaction. Possible values are: SUCCESS: The transaction was completed successfully. FAIL: The transaction failed. CANCELED: The transaction was cancelled. PENDING: The transaction in pending. REFUND_INITIATED: refund initiated. REFUND_SUCCESS: refunded successfully
- `acknowledgement.abhaAddress` (string, required): The abha Address of the user, formatted as . This is a unique identifier for the user in the health system.
- `acknowledgement.transactionId` (string, required): A unique identifier for the transaction. This helps in tracking and referencing the specific transaction.
- `acknowledgement.orderNumber` (string, required): A unique identifier for the order associated with the transaction. This helps in tracking and referencing the specific order.
- `acknowledgement.openOrderRequestId` (string, required): The unique identifier for the queried request. This ID is used to track and reference the specific request within the system.
- `acknowledgement.paymentDate` (string, required): he date and time when the transaction occurred, formatted in UTC
- `acknowledgement.paymentRecipetLink` (string, required): This attribute holds the URL link to the payment receipt. It is a string that provides a direct link to a PDF document or other format of the receipt for the transaction.
- `response` (object, required): This is the response request-id which is generated from the share api
- `response.requestId` (string, required)

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - no mapping found to the resp.requestId cache. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `429`: Too Many Requests
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2429 - Too Many Requests found. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Get the patient scan pay details

`GET /api/hiecm/scan-gateway/v3/patient/scan-pay/details`

Retrieve the all the details of the user/patient based on the date ranges.

 **Header**

AUTHORIZATION will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-AUTH-TOKEN JWT Authentication token which was issued by ABDM after successful validation of user[ Example: Bearer ]

X-CM-ID consent manager ID [ Example: sbx ]

status [ Example: SUCCESS, CANCELED, PENDING, FAIL, REFUND_INITIATED, REFUND_SUCCESS,ALL ]

limit [ Example: 10]

startDate [ Example: 2024-07-13T07:30:10.186Z]

endDate [ Example: 2025-02-18T08:30:50.189Z]

offset [ Example: 0]

```bash
curl --request GET \
  --url "https://dev.abdm.gov.in/api/hiecm/scan-gateway/v3/patient/scan-pay/details?status=SUCCESS&limit=10&startDate=2024-07-13T07:30:10.186Z&endDate=2025-02-18T08:30:50.189Z&offset=0" \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'X-AUTH-TOKEN: <TOKEN>'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended
- `X-AUTH-TOKEN` (string, required): JWT Authentication token which was issued by ABDM after successful validation of username and password

## Query parameters

- `status` (string, required): Payment status
- `limit` (integer, required): It describes the no. of records.
- `startDate` (string, required): start date of the records.
- `endDate` (string, required): start date of the records.
- `offset` (integer, required): retrieval of records starts from the very first record in the dataset.

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)

Shape of the 200 response, generated from the schema. The values are placeholders, not a captured response:

```json
[
  "<VALUE>"
]
```


---

# Update version to the serviceId

`PATCH /api/hiecm/gateway/v3/scanPay/updateVersion`

This is used by the integrators to update the version for the particular service-ID.

 **Header**

Authorisation will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: Bearer ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-CM-ID [ Example: sbx]

 **Request Body**

recordShareEnabled It describes whether the record share is enabled or not.

scanPayEnabled It describes whether the scan pay is enabled or not.

scanPayVersion This is a key value pair which contains the version [ Example: type: v2 / v3]

serviceId This is a key value pair which contains ServiceId[ Example: SERVICE_ID1,SERVICE_ID2 ]

```bash
curl --request PATCH \
  --url https://dev.abdm.gov.in/api/hiecm/gateway/v3/scanPay/updateVersion \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "recordShareEnabled": true,
  "scanPayEnabled": true,
  "scanPayVersion": "v2",
  "serviceId": [
    "****_HIP, ***_HIU"
  ]
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `recordShareEnabled` (boolean, required): It describes whether the record share is enabled or not.
- `scanPayEnabled` (boolean, required): It describes whether the scan pay is enabled or not.
- `scanPayVersion` (string, required): It describes the version.
- `serviceId` (object[], required)

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-2500 - Unknown error occurred. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-pay/errors
  - `code` (string, required): ABDM-2500 - Service Unavailable. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Scan and Pay errors

Seeing a symptom rather than a code? Start at [Troubleshooting](/docs/hiecm/v3/troubleshooting/).

The Scan and Pay specification records no error code yet. That is a gap in the specification, not a promise that this module cannot fail.

Every code above is recorded in the specification that owns it. The aggregated list across modules is at [error codes](/docs/hiecm/v3/reference/error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# Share HIP patient

`POST /api/v3/hip/patient/share`

**Hosted by the HIP/HIU, not by ABDM.** ABDM calls this endpoint at the callback URL registered for your bridge, so the path below is relative to that URL.
This is an API will be invoked to the **HIP** to share the response of HIECM's /api/hiecm/patient-share/v3/share API.

 **Header**

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-HIP-ID

Authorisation will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: ]

 **Request Body**

intent This is a key value pair which contains the purpose [ Example: {purpose: PROFILE_SHARE } ]

metaData This is a key value pair which contains the location longitude and latitude[ Example: {HIP_ID: ABDM_HIP, context: 123, lat: 20.5937 long: 78.9629} ]

profile which contains user details.

```bash
curl --request POST \
  --url {bridgeUrl}/api/v3/hip/patient/share \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-HIP-ID: IN2810014366' \
  --header 'Content-Type: application/json' \
  --data '{
  "intent": "PROFILE_SHARE",
  "metaData": {
    "hipId": "HIP_1",
    "context": "6",
    "hprId": "<EMAIL>",
    "latitude": 20.5937,
    "longitude": 78.9629
  },
  "profile": {
    "patient": {
      "abhaNumber": "<ABHA_NUMBER>",
      "abhaAddress": "<ABHA_ADDRESS>",
      "name": "<NAME>",
      "gender": "M",
      "dayOfBirth": "<DOB>",
      "monthOfBirth": "<DOB>",
      "yearOfBirth": "9999",
      "address": {
        "line": "Address line 1",
        "district": "Coimbatore",
        "state": "Tamil Nadu",
        "pincode": "<PINCODE>"
      },
      "phoneNumber": "<MOBILE_NUMBER>"
    }
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-HIP-ID` (string, required): Identifier of the health information provider to which the request was intended

## Body

- `intent` (string, required): The intention of share API call One of: PROFILE_SHARE, RECORD_SHARE, PAYMENT_SHARE.
- `metaData` (object, required): A key-value pair carrying the location longitude and latitude.
- `metaData.hipId` (string, required): The service ID of the health information provider. Allows alpha numeric character and special characters like [A-Z a-z 0-9]+[A-Z a-z 0-9 @//_//-]*[A-Z a-z 0-9]
- `metaData.context` (string, required): This is a counter Id. Allows alpha numeric character and special characters like ^(?:[a-zA-Z0-9 ]|[a-zA-Z0-9 ][a-zA-Z0-9.\\-_ ]*[a-zA-Z0-9 ]){1,250}$
- `metaData.hprId` (string): Healthcare Professionals Registry id. Allows alpha numeric character and special characters like [a-zA-Z0-9][a-zA-Z0-9_.]+[a-zA-Z0-9]@(dr.abdm|hpr.abdm)$|^[1-9][0-9]{13}$
- `metaData.latitude` (number, required): The latitude of the location.Allows alpha numeric character and special characters like ^[0-9-.]+$
- `metaData.longitude` (number, required): The longitude of the location.Allows alpha numeric character and special characters like ^[0-9-.]+$
- `profile` (object, required): This should populated only for PROFILE_SHARE
- `profile.patient` (object, required)
- `profile.patient.abhaNumber` (string): The abha number of the patient.It should be passed based on the X-AUTH-TOKEN. Should be only 14 digit. Allows alpha numeric character and special characters like ^(\\d+-?){13}\\d$
- `profile.patient.abhaAddress` (string, required): The abha address of the patient. Should start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx and Allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.\-!]+[a-zA-Z0-9]@(abdm|sbx)$
- `profile.patient.name` (string, required): The name of the patient. Allows alpha numeric character and special characters like ^[a-zA-Z0-9.-_,]+(([',. -][a-zA-Z0-9. ])?[a-zA-Z0-9. ]*)*$
- `profile.patient.gender` (string, required): The gender of the patient One of: M, F, O, D, T, U.
- `profile.patient.dayOfBirth` (string): The day of birth of the patient. Only allows numeric values between 1 abd 31 and ^(?!\\s*$)(0?[1-9]|[12][0-9]|3[01])$
- `profile.patient.monthOfBirth` (string): The month of birth of the patient. Only allows numeric values between 1 abd 12 and ^(?!\\s*$)(0?[1-9]|[1][0-2])$
- `profile.patient.yearOfBirth` (string, required): The month of birth of the patient. Only allows numeric values and must be 4 digit ranging between 1900 and 2200 and ^(?!\\s*$)(19|20|21|22)\\d{2}$
- `profile.patient.address` (object, required)
- `profile.patient.address.line` (string, required): The address line
- `profile.patient.address.district` (string): The district and should only contain alphabets
- `profile.patient.address.state` (string): The state and should only contain alphabets like [A-Z a-z]+[A-Z a-z //' ']*$
- `profile.patient.address.pincode` (string): Should be 5 digits and only contain numbers
- `profile.patient.phoneNumber` (string, required): The mobile number of the patient. Must be 10 digit and contain only 0-9 and it allows only numbers like ^(\+\d{1,3}[- ]?)?\d{10}$

## Responses

- `200`: OK
- `400`: Bad Request. The request could not be processed because it was malformed or failed validation - a missing mandatory field, a value in the wrong format, or a header that did not match the body.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-register/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `error.message` (string, required): Short description of the failure.
- `401`: Unauthorized. The request carried no valid credentials, or the access token has expired. Obtain a fresh token from the session API and retry.
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string): Short description of the failure.
  - `description` (string): Detailed description of the failure.
- `403`: Forbidden. The caller is authenticated but is not permitted to perform this operation on this resource.
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-register/errors
- `408`: Request Timeout
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-register/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1007 - Connection failed due to timeout. May be returned either bare (`ABDM-1007`) or with a trailing ": " separator (`ABDM-1007: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-register/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-register/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Answer the patient share request

`POST /api/hiecm/patient-share/v3/on-share`

Share the response of HIECM's /api/hiecm/patient-share/v3/on-share API.

 **Header**

AUTHORIZATION will be provided by the gateway session API after the successful verification of client ID and Secret [ Example: ]

REQUEST-ID unique UUID[ Example: 18235d89-cb13-479d-ad71-7a57d5f669a8 ]

TIMESTAMP actual time of the requested was initiated[ Example: 2022-10-06T10:10:00.587Z ]

X-CM-ID consent manager ID[ Example: sbx ]

 **Request Body**

Incase of success scenario,acknowledgement is mandatory and error is optional

Incase of failure scenario,error is mandatory and acknowledgment is optional

response is mandatory object in both the cases

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/patient-share/v3/on-share \
  --header 'Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>' \
  --header 'REQUEST-ID: 18235d89-cb13-479d-ad71-7a57d5f669a8' \
  --header 'TIMESTAMP: 2022-10-06T15:10:00.587Z' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "acknowledgement": {
    "status": "SUCCESS",
    "abhaAddress": "<ABHA_ADDRESS>",
    "profile": {
      "context": "43",
      "tokenNumber": "3",
      "expiry": 180
    }
  },
  "error": {
    "code": "ABDM-9999",
    "message": "Unknown exception"
  },
  "response": {
    "requestId": "6f0b4665-a915-4c92-aa36-65afb4a2cd71"
  }
}'
```

## Authorization

- `Authorization` (bearer token, required): The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer ` prefix.

## Headers

- `REQUEST-ID` (string, required): Unique UUID for track the end to end request transaction
- `TIMESTAMP` (string, required): Actual time of the request was initiated, ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds
- `X-CM-ID` (string, required): Suffix of the consent manager to which the request was intended

## Body

- `acknowledgement` (object, required)
- `acknowledgement.status` (string, required): The status of the transaction.Allows like (SUCCESS|FAILED)
- `acknowledgement.abhaAddress` (string, required): The abha address of the patient. Should start with Alphanumeric . and  _  in the middle and must be ending with @abdm or @sbx and Allows alpha numeric character and special characters like ^[a-zA-Z0-9][a-zA-Z0-9_.\-!]+[a-zA-Z0-9]@(abdm|sbx)$
- `acknowledgement.profile` (object, required): Should be populated only if this is a response for PROFILE_SHARE request
- `acknowledgement.profile.context` (string, required): This is a counter Id. Allows alpha numeric character and special characters like ^(?:[a-zA-Z0-9 ]|[a-zA-Z0-9 ][a-zA-Z0-9.\\-_ ]*[a-zA-Z0-9 ]){1,250}$
- `acknowledgement.profile.tokenNumber` (string, required): The token number generated at HIP for the request
- `acknowledgement.profile.expiry` (number, required): The expiry time and should be only numeric value.Allows alpha numeric character and special characters like [\d]*$
- `error` (object, required): error is optional object in case of Sucess response.
- `error.code` (string, required): ABDM-9999 - Unknown exception. May be returned either bare (`ABDM-9999`) or with a trailing ": " separator (`ABDM-9999: `); match on the code itself and tolerate the separator.
- `error.message` (string, required)
- `response` (object, required)
- `response.requestId` (string, required): The requestId that was passed.Allows alpha numeric character and special characters like [0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}

## Responses

- `202`: Accepted
  See The callback never arrives: /docs/hiecm/v3/troubleshooting/callback-never-arrives
- `400`: Bad Request
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-register/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1006 - Bad Request, invalid request Body. May be returned either bare (`ABDM-1006`) or with a trailing ": " separator (`ABDM-1006: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `401`: Unauthorized
  See Everything returns 401: /docs/hiecm/v3/troubleshooting/everything-returns-401
  - `code` (string): 900901 - Invalid Credentials. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `403`: Forbidden
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-register/errors
- `404`: Not Found
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-register/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1001 - No data found. May be returned either bare (`ABDM-1001`) or with a trailing ": " separator (`ABDM-1001: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `408`: Request Timeout
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-register/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1007 - Connection failed due to timeout. May be returned either bare (`ABDM-1007`) or with a trailing ": " separator (`ABDM-1007: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `429`: Too Many Requests
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-register/errors
  - `error` (object): The error code and message, if any occurred.
  - `error.code` (string, required): ABDM-1022 - Too many requests. May be returned either bare (`ABDM-1022`) or with a trailing ": " separator (`ABDM-1022: `); match on the code itself and tolerate the separator.
  - `error.message` (string, required)
- `500`: Internal Server Error
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-register/errors
  - `code` (string): 900900 - Unclassified Authentication Failure. May be returned either bare or with a trailing ": " separator; match on the code itself and tolerate the separator.
  - `message` (string)
  - `description` (string)
- `503`: Service Unavailable
  See Error codes for this module: /docs/hiecm/v3/api/scan-and-register/errors
  - `code` (string, required): ABDM-1024 - Dependent service unavailable. May be returned either bare (`ABDM-1024`) or with a trailing ": " separator (`ABDM-1024: `); match on the code itself and tolerate the separator.
  - `message` (string, required)


---

# Scan and Register errors

Seeing a symptom rather than a code? Start at [Troubleshooting](/docs/hiecm/v3/troubleshooting/).

The Scan and Register specification records no error code yet. That is a gap in the specification, not a promise that this module cannot fail.

Every code above is recorded in the specification that owns it. The aggregated list across modules is at [error codes](/docs/hiecm/v3/reference/error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# Proving a callback came from ABDM

## In short

- Your callback URL is a public address. Anything on the internet can post to it, and a POST arriving there tells you nothing about who sent it.
- ABDM callbacks declare bearer authentication. The gateway publishes the public keys at `/api/hiecm/gateway/v3/certs`, as a JSON Web Key Set, and that endpoint needs an access token.
- Verify every callback before your handler does any work. Pin the algorithm to `RS256` and fail closed.
- The token arrives in the `Authorization` header as a bearer token.

## Why this one matters

To receive callbacks you register a URL that ABDM can reach. Reachable by ABDM means reachable by everyone, because it is an ordinary address on the public internet.

The callbacks you host carry instructions about a named person's health records: a request to discover what you hold, a [consent artefact](/docs/hiecm/v3/concepts/consent) saying somebody agreed, an instruction to transfer records to a given address. A system that acts on whatever arrives will act on whatever an attacker sends.

ABDM callbacks declare bearer authentication, and the gateway publishes the public keys that verify the token. You fetch the keys once, cache them, and check the signature on every callback before your handler does anything.

Two different signatures

The signature inside a [consent artefact](/docs/hiecm/v3/concepts/consent) is a different thing. It signs the artefact's contents and proves the artefact was not altered. The one on this page signs the delivery and proves who sent it. Verifying one does not verify the other.

## Before you start

You need a callback URL registered with ABDM, and an understanding of why a 200 is not an answer, which is on [how a record travels](/docs/hiecm/v3/concepts/data-flow).

You need an access token for this. The certificates endpoint declares bearer authentication and a required `X-CM-ID` header in the specification.

## Fetch the key set

```bash
curl --request GET \  --url https://dev.abdm.gov.in/api/hiecm/gateway/v3/certs \  --header 'Authorization: Bearer <ACCESS_TOKEN>' \  --header 'REQUEST-ID: <REQUEST_ID>' \  --header 'TIMESTAMP: <TIMESTAMP>' \  --header 'X-CM-ID: sbx'
```

Each key carries a `kid` that identifies it, `kty: RSA`, `use: sig`, and an `alg` the specification gives as `RS256`. The `n` and `e` fields are the RSA modulus and exponent, Base64URL encoded, and some keys also carry `x5c`, a certificate chain.

The same key set is discoverable through the OIDC document at `/api/hiecm/gateway/v3/.well-known/openid-configuration`, which names it in `jwks_uri`. Reading the discovery document first survives the key set moving.

Cache the keys rather than fetching them per callback, and key your cache by `kid`. When a callback presents a `kid` you have not seen, refetch once before rejecting it. That is what key rotation looks like from your side.

Verification is then the ordinary JWT check your library already does: signature against the key named by `kid`, algorithm pinned to `RS256`, and the expiry and issuer claims if the token carries them.

## Which header carries the token

The header is declared

Every webhook definition in the M2 and M3 specifications declares bearer authentication. The token arrives in the `Authorization` header as `Bearer <token>`.

Pin the algorithm to `RS256` when you verify, and reject `none`. A verifier that accepts whatever algorithm the token names accepts a token an attacker signed, and that is a defect in the verifier rather than in ABDM.

## How you know it worked

You can fetch the certificates endpoint and get back a `keys` array whose entries carry `kid`, `kty: RSA` and `use: sig`.

Then, on your own handler, both of these hold:

1. A callback carrying a valid signature is processed, and its `response.requestId` matches the `REQUEST-ID` of a request you sent.
2. The same callback body, replayed with the signature altered by one character, is rejected before your handler reads the payload, and the rejection is logged.

The second is the one worth writing a test for. It is the only one that fails loudly when verification is silently skipped.

## When it goes wrong

**The `kid` is not in your cache.** That is key rotation. Refetch the key set once, then reject if it is still absent, rather than refetching on every callback and handing an attacker a way to make you call the gateway.

**You cannot find a token on the request.** The webhook definitions declare bearer authentication, so read the `Authorization` header. Do not fall back to processing unverified requests while you work it out.

**Verification is skipped under load.** A handler that verifies inside a try block and continues on failure is worse than one that never verified, because it reads as safe. Fail closed.

**Nothing arrives at all**, which is a different problem. See [the callback never arrives](/docs/hiecm/v3/troubleshooting/callback-never-arrives).


---

# Care contexts

A Care Context represents a logical grouping of a patient's health records. Each [HMIS](/docs/hiecm/v3/getting-started/glossary#hmis)/[LMIS](/docs/hiecm/v3/getting-started/glossary#lmis) system should define how patient data is organised into one or more care contexts in a meaningful and consistent way.

A care context serves as the unit that is associated with a patient's [ABHA address](/docs/hiecm/v3/getting-started/glossary#abha-address) within the system.

## Key design principles

The [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm) (Health Information Exchange & Consent Manager) is designed to be data-blind.

- This means it does not access or store the actual health record content.
- Instead, it only works with identifiers and metadata related to care contexts.

## Components of a care context

Each care context contains only two pieces of information:

- **Reference ID.** A unique internal identifier assigned by the [HRP](/docs/hiecm/v3/getting-started/glossary#hrp) (HMIS/LMIS). Used to link and retrieve the associated health records.
- **Display Name.** A user-friendly description to help identify the group of records. Must not include any sensitive or confidential information such as test results or diagnoses. Example: "OPD records (X-Ray, Prescription) from 3rd March 2023".

## Recommended approach for structuring care contexts

To ensure clarity and usability, it is recommended to organise patient data as follows:

- Create one care context per outpatient visit (OPD)
- Create one care context per inpatient admission (IPD)

This approach provides a clear and event-based grouping of health records.

## JSON structure of care contexts

```json
{  "patient": {    "referenceNumber": "TMH-PUID-001",    "display": "TMH records for Kiran Kumar",    "careContexts": [      {        "referenceNumber": "2375639",        "display": "OPD records for O3 Oct 2022"      }    ]  }}
```

## Next steps

- [Linking](/docs/hiecm/v3/concepts/linking), how a care context reaches the patient's ABHA address.
- [M2 Attach](/docs/hiecm/v3/milestones/m2), the milestone that links care contexts and shares the records in them.
- [M2 API reference](/docs/hiecm/v3/api/m2), the calls that carry a care context.


---

# Consent

Consent is the permission layer of [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm): a record moves because a patient said yes to a named system, for a named reason, over a date range, for a fixed length of time. The calls that create and read it are in the [M3 guide](/docs/hiecm/v3/api/m3).

## Two objects, not one

| Object                                                                       | What it is                                                                                                                                                     | Who creates it                                                                          | Identifier          |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------- |
| Consent request                                                              | The ask. It names the patient by [ABHA](/docs/hiecm/v3/getting-started/glossary#abha) address, the reason, the record types wanted, and the date range wanted. | The [HIU](/docs/hiecm/v3/getting-started/glossary#hiu), through the gateway             | Consent request id  |
| [Consent artefact](/docs/hiecm/v3/getting-started/glossary#consent-artefact) | The permission itself, created only if the patient grants the request. It is what a record holder checks before sending anything.                              | The [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm), on the patient's decision | Consent artefact id |

One request can produce more than one artefact. A granted request returns the ids of the consent artefacts created against it, plural. Store the request id and every artefact id.

## Who holds what

- **The patient holds the decision**, in their [PHR](/docs/hiecm/v3/getting-started/glossary#phr) app.
- **The HIE-CM holds the artefact.** As [consent manager](/docs/hiecm/v3/getting-started/glossary#consent-manager) it asks the patient, records the answer, and tells requester and record holder.
- **The HIU holds an id, not a right.** It can stop working at any time.
- **The [HIP](/docs/hiecm/v3/getting-started/glossary#hip) holds the check.** Before sending a record it validates that the artefact is active and that the dates asked for sit inside the dates it allows.

## The states a consent moves through

```mermaid
stateDiagram-v2
    [*] --> Requested: HIU raises a consent request
    Requested --> Granted: Patient approves
    Requested --> Denied: Patient refuses
    Requested --> Expired: Patient does not act in time
    Granted --> Revoked: Patient withdraws access
    Granted --> [*]: Validity period ends
```

There are five states, in the two sections a PHR app shows: Requests holds Requested, Denied and Expired; Approved holds Granted and Revoked.

| State     | What it means                                                         | What your system does                                                  |
| --------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Requested | The patient has not acted yet.                                        | Wait. Poll the request status if you need to show progress.            |
| Granted   | The patient approved, and set how long the access lasts.              | Fetch the artefact ids, then request the data.                         |
| Denied    | The patient refused.                                                  | Stop. There is no partial result and no retry that changes the answer. |
| Expired   | The patient did not act inside the window the HIU set on the request. | Raise a new request if the clinical need is still there.               |
| Revoked   | The patient withdrew a consent they had already granted.              | Stop fetching under that artefact from that moment.                    |

Two clocks run here. The **request window** is how long the patient has to answer, set by the HIU, and running out produces Expired. The **consent validity period** is how long access lasts once granted, set by the patient as they grant, with a defined expiry date and time. Neither is the **date range**, which says which records are in scope by when the care happened: a consent granted today can cover records from 2019.

## What the patient sees, and can change

A consent request must display the requesting HIU, the purpose of data access, the data types requested, the date range, the consent validity period and the request status. Where permitted, the patient may modify four of those before approving: access duration, record date range, data categories and validity period. The consent you get back can be narrower than the one you asked for, so read the artefact.

## The five things a PHR app must let a person do

Consent is granted by a person, and the PHR app is where they do it. NHA sets a floor of five capabilities, and an app missing one leaves a person able to give access they cannot inspect, change or withdraw.

1. **See the request**, with the HIU asking, the purpose, the record types, the date range of records, how long the consent would last, and its status.
2. **Change it before allowing it**, where the request permits: the access duration, the record date range, the categories shared, and the validity period. This is the one most often left out, and the one that turns a consent screen into a negotiation rather than a demand.
3. **Allow or refuse it.** The consent flow has three outcomes, not two: approve, reject and ignore. An ignored request expires on the requester's window, and the interface has to show that state.
4. **See what is already allowed**, so the person can tell which organisations hold access right now. A list of past decisions is not the same thing.
5. **Take it back** at any time. Two things follow: the status updates at the consent manager, and sharing under that consent stops immediately, not at the end of the period.

## Purpose of use codes

Why you want the records. See [purpose of use](/docs/hiecm/v3/getting-started/glossary#purpose-of-use). These codes are a subset of the HL7 v3 PurposeOfUse value set at [terminology.hl7.org](http://terminology.hl7.org/ValueSet/v3-PurposeOfUse).

| Code      | Display                              |
| --------- | ------------------------------------ |
| `CAREMGT` | Care Management                      |
| `BTG`     | Break the Glass                      |
| `PUBHLTH` | Public Health                        |
| `HPAYMT`  | Healthcare Payment                   |
| `DSRCH`   | Disease Specific Healthcare Research |
| `PATRQT`  | Self-Requested                       |

The source table prints the header row and the `CAREMGT` row twice. There are six codes. The patient reads this code.

## Health information types

What kind of record you are asking for. See [HI type](/docs/hiecm/v3/getting-started/glossary#hi-type). M3 supports these types as of writing:

| Code                   | Display             |
| ---------------------- | ------------------- |
| `Prescription`         | Prescription        |
| `DiagnosticReport`     | Diagnostic Report   |
| `OPConsultation`       | OP Consultation     |
| `DischargeSummary`     | Discharge Summary   |
| `ImmunizationRecord`   | Immunization Record |
| `HealthDocumentRecord` | Record artifact     |
| `WellnessRecord`       | Wellness Record     |

The M2 error message for an invalid HI type lists these seven and adds `Invoice`. The two disagree by one value, so check the swagger before you send `Invoice`. What each type carries as a [FHIR](/docs/hiecm/v3/getting-started/glossary#fhir) bundle is on [FHIR and health record formats](/docs/hiecm/v3/concepts/fhir).

## Expiry and revocation

**Expiry is predictable.** The artefact carries an end, so you can fetch before it arrives. Past it, the record holder rejects the request: `ABDM-1061` for an expired consent artefact, `ABDM-1112` for an artefact id that is invalid or already expired.

**Revocation is not.** The patient can withdraw at any time, including after you have read the data, and future data sharing under that consent must stop immediately.

So treat every fetch as a fresh permission check, and handle a mid flow revocation. A consent that was live when you sent the health information request can be dead when the record holder validates it. That returns `ABDM-1062`, consent not granted. Decide your retention policy for data you already hold. Sharing stops. What to do with what you already received is not documented yet.

Read every code with the message the gateway returns. The error table lists `ABDM-1061` and `ABDM-1062` against two different messages each, so the code alone does not identify the failure.

## Consent without a person tapping approve

An auto approval policy works like this: the patient authorises the app once, the app registers the policy with the HIE-CM, and later requests under that policy are granted immediately. The patient can disable it, after which each record needs its own request again. This changes who taps the button, not the model. An artefact is still created, still carries an expiry, and can still be revoked. Detail is on [PHR applications](/docs/hiecm/v3/concepts/participants/phr).

## Where this is implemented

- [Hospital, lab and pharmacy systems](/docs/hiecm/v3/concepts/hip-hiu), the facility taking each role.
- [The ABDM gateway](/docs/hiecm/v3/concepts/gateway), which holds every artefact here.
- [M3 Health Information User, Health Information User Services](/docs/hiecm/v3/api/m3), the requesting side.
- [M2 Health Information Provider, Health Information Provider Services](/docs/hiecm/v3/api/m2), what a record holder validates.
- [How a record travels](/docs/hiecm/v3/concepts/data-flow), what happens next.


---

# How a record travels

In [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm) the request goes through the [gateway](/docs/hiecm/v3/getting-started/glossary#gateway) and the [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm), because that is where consent is checked and routing lives. The record itself goes straight from the system that holds it to a URL the requester nominated, encrypted so only the requester can open it.

## The two sides

| Role                                               | Who takes it                               | What it does here                                                                                                                                             | Milestone                   |
| -------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| [HIU](/docs/hiecm/v3/getting-started/glossary#hiu) | The organisation or citizen asking         | Holds a granted [consent artefact](/docs/hiecm/v3/getting-started/glossary#consent-artefact), asks for the records it covers, receives them and decrypts them | [M3](/docs/hiecm/v3/api/m3) |
| [HIP](/docs/hiecm/v3/getting-started/glossary#hip) | The citizen or facility holding the record | Holds the records, validates the consent, packages, encrypts, signs and pushes                                                                                | [M2](/docs/hiecm/v3/api/m2) |

The HIE-CM sits between them for the request and the notifications, and never sees a record.

## The whole path

```mermaid
sequenceDiagram
    autonumber
    participant U as HIU
    participant CM as HIE-CM gateway
    participant P as HIP
    Note over U: Generate a short term key pair and a 32 byte nonce
    U->>CM: Health information request
    Note over U,CM: Consent artefact id, date range, data push URL, HIU public key, HIU nonce
    CM->>CM: Generate a transaction id
    CM-->>U: Transaction id
    CM->>P: Forward the request with the transaction id
    P->>P: Validate consent status, date range, encryption parameters
    P->>P: Assemble the FHIR bundles
    Note over P: Generate a key pair and nonce, derive the session key
    P->>P: Encrypt, then sign with its long term private key
    P->>U: Push the encrypted data to the data push URL
    Note over P,U: Transaction id, HIP public key, HIP nonce, encrypted bundles
    P->>CM: health-information/notify, transfer complete
    U->>U: Derive the same session key, decrypt
    U->>CM: health-information/notify, success or failure
```

## Stage 1: the request

The HIU sends a health information request through the gateway, quoting a consent artefact the patient granted. It carries four things.

- **The consent id**, the artefact that authorises the request.
- **The data push URL**, where the HIP sends the records. It may differ from the HIU's registered gateway URL, which improves privacy and anonymity.
- **The date and time range** of records wanted.
- **The encryption parameters**: the HIU's public key and its nonce.

The HIE-CM generates a transaction id and gives it to both sides, which is how you correlate a push arriving later with a request you sent earlier.

## Stage 2: validation, then transfer

Before the HIP retrieves anything it runs three checks.

1. **The consent id is valid and active.** Not expired, not paused, not revoked.
2. **The requested date and time range falls inside the range the consent artefact permits.** A wider window is refused, not trimmed.
3. **The encryption parameters are correct and compatible.**

Only then does it package the records as [FHIR](/docs/hiecm/v3/getting-started/glossary#fhir) bundles, encrypt, sign with its long term private key, and send with the transaction id to the data push URL.

Two failures land here: `ABDM-1062`, consent not granted, and `ABDM-1063`, date range given is invalid. Both codes also appear against a linking message, so read the code with the message.

## Stage 3: the notifications that close it

Both sides call `health-information/notify`: the HIP to say the data was transmitted, the HIU to report success or failure on its side. Neither carries the record. They carry the fact that a transfer happened, which is what makes the exchange auditable for the patient.

## Timing and size

| Constraint       | Rule                                                                                     |
| ---------------- | ---------------------------------------------------------------------------------------- |
| Timeout          | 20 minutes from the start of the request                                                 |
| Large datasets   | Split into multiple parts, for example CT or MRI images running to hundreds of megabytes |
| Very large files | Stream rather than sending one payload                                                   |

Treat retrieval and encryption as a background job, not work inside a web request.

## The encryption

The scheme is [Elliptic Curve Diffie-Hellman](/docs/hiecm/v3/getting-started/glossary#ecdh) key exchange on Curve25519, with AES-GCM for the payload and HKDF to derive the session key. Only the HIU holding valid consent can read the data, and the design gives perfect forward secrecy: key material compromised later does not expose data exchanged earlier.

### Who holds which key

| Key material                          | Generated by                   | Where it goes                                      |
| ------------------------------------- | ------------------------------ | -------------------------------------------------- |
| Short term private key, DHSK(U)       | HIU                            | Never leaves the HIU                               |
| Short term public key, DHPK(U)        | HIU                            | Sent with the request                              |
| Nonce, RAND(U), 32 bytes              | HIU                            | Sent with the request                              |
| Short term private key, DHSK(P)       | HIP                            | Never leaves the HIP                               |
| Short term public key, DHPK(P)        | HIP                            | Sent with the encrypted data                       |
| Nonce, RAND(P), 32 bytes              | HIP                            | Sent with the encrypted data                       |
| Shared key, DHK(U,P)                  | Computed independently by both | Never transmitted                                  |
| Session key, SK(U,P), 256 bit AES-GCM | Derived independently by both  | Never transmitted                                  |
| Long term private key                 | HIP                            | Never leaves the HIP. Signs the encrypted payload. |

A new key pair per exchange is what buys forward secrecy.

### What the HIP does, step by step

Six steps, once consent has validated.

1. Generate a key pair, DHSK(P) and DHPK(P), in the group the HIU specified.
2. Generate a 32 byte random value, RAND(P).
3. Compute the shared key DHK(U,P) from the HIU's public key DHPK(U) and the HIP's own private key DHSK(P).
4. Derive the salt and IV by XOR of RAND(P) and RAND(U). The first 20 bytes are the salt for HKDF, the last 12 bytes the IV.
5. Compute a 256 bit AES-GCM session key SK(U,P) with HKDF, from the shared key and that salt.
6. Encrypt the data with that key and that IV.

The HIP then sends DHPK(P), RAND(P) and the encrypted data. The HIU derives the same session key from its own private key DHSK(U) and the HIP's public key DHPK(P), with salt and IV from the same XOR.

Build the shared key from the HIU's public key and the HIP's private key. That is the pairing that makes the Diffie-Hellman exchange work.

### Do not write this yourself

Two reference implementations exist. Fidelius, at [github.com/sukreet/fidelius](https://github.com/sukreet/fidelius), and the Fidelius CLI, which is Java, with worked examples for Node.js, Python, Ruby and PHP at [github.com/mgrmtech/fidelius-cli](https://github.com/mgrmtech/fidelius-cli/tree/main/examples) that run the binary as a subprocess. A webinar covers the CLI from both sides, at [youtu.be/rSir2gbkEmk](https://youtu.be/rSir2gbkEmk?t=9232) from 2:33:52.

## Where this is implemented

- [Hospital, lab and pharmacy systems](/docs/hiecm/v3/concepts/hip-hiu), which side the facility you act for is on.
- [M2 Health Information Provider, Health Information Provider Services](/docs/hiecm/v3/api/m2), the sending side.
- [M3 Health Information User, Health Information User Services](/docs/hiecm/v3/api/m3), the receiving side.
- [Consent](/docs/hiecm/v3/concepts/consent), the artefact this flow depends on.
- [FHIR and health record formats](/docs/hiecm/v3/concepts/fhir), what is inside the payload.


---

# Encryption

Several fields in [M1](/docs/hiecm/v3/api/m1) do not carry the value you started with. They carry that value encrypted against the ABDM public key. When an API page shows a placeholder such as `{{encrypted aadhaar number}}`, the field name tells you what the value is and the placeholder tells you it must already be encrypted.

## In short

- Encrypt the Aadhaar number, mobile number, OTP and password with RSA against the published public key, and send the base64 ciphertext.
- M1 calls use the ABHA service's key. PHR calls use the PHR key, which is a different key at a different URL.
- Your system never holds a secret for this: only the current public certificate.

## What must be encrypted

Six kinds of value never travel raw in an M1 request body.

| Value                                                                        | Where it appears                     |
| ---------------------------------------------------------------------------- | ------------------------------------ |
| Aadhaar number                                                               | Enrolment and login by Aadhaar       |
| ABHA number                                                                  | Login and search by ABHA number      |
| Mobile number                                                                | Login, search and mobile update      |
| Email address                                                                | Email verification                   |
| One time password ([OTP](/docs/hiecm/v3/getting-started/glossary#otp)) value | Every call that verifies a challenge |
| Password                                                                     | Password based login                 |

Each is encrypted with RSA using the ABDM public certificate, and the base64 of the ciphertext goes in the field.

## What shape the plaintext must be

The service validates the plaintext after it decrypts, so the shape you encrypt matters and a wrong shape is rejected as though the value were wrong.

| Value          | Plaintext shape                                                      | Example             |
| -------------- | -------------------------------------------------------------------- | ------------------- |
| ABHA number    | 14 digits with dashes, `NN-NNNN-NNNN-NNNN`                           | `91-1234-5678-9015` |
| Aadhaar number | 12 digits, no spaces                                                 | `999999990019`      |
| Mobile number  | 10 digits, first digit 1 to 9, optionally prefixed with `+91` or `0` | `9876543210`        |
| OTP value      | Exactly 6 digits                                                     | `123456`            |

The ABHA number is the one that catches people, because the number is printed and stored both ways. Encrypting the 14 bare digits is rejected: a login OTP request sent that way on the sandbox on 11 September 2026 returned `400 {"loginId": "LoginId is invalid"}`, and the same number encrypted as `91-1234-5678-9015` passed validation and went on to look the account up. Strip the dashes for display if you like, but put them back before you encrypt.

Aadhaar, mobile and OTP values follow the validation patterns given on each call in the [M1 API reference](/docs/hiecm/v3/api/m1).

## How the model works

```mermaid
sequenceDiagram
    autonumber
    participant S as Your system
    participant A as ABHA service
    S->>A: GET /abha/api/v3/profile/public/certificate
    A-->>S: publicKey, encryptionAlgorithm
    S->>S: RSA encrypt the Aadhaar number, mobile number,<br/>OTP or password with that public key
    S->>A: The Base64 result as the field value,<br/>for example loginId or otp.otpValue
    A->>A: Decrypts with its private key
```

We publish the public half of a key pair. You encrypt with it. Only our private half can decrypt. Your system never holds a secret to do this, only the current certificate.

There is nothing ABDM specific in the mechanics. Your platform's standard RSA library does the work. Both keys use `RSA/ECB/OAEPWithSHA-1AndMGF1Padding`. The one thing to confirm is which key you are using.

## Where to do it

**Encrypt inside your own system, against the published ABDM public key.** This is the production path.

## Fetching the public key

A [PHR](/docs/hiecm/v3/getting-started/glossary#phr) application fetches its own key from `GET /abha/api/v3/phr/app/login/public/certificate`, the first call in [P1](/docs/hiecm/v3/api/p1/endpoints/p1-certificate-and-session/01-p1-get-v3-phr-app-login-public-certificate). It is a different key from the ABHA service's, so never encrypt a PHR call with the M1 certificate.

M1 has a `public/certificate` API for fetching the public key. Its URL, headers and response shape are on [the certificate call](/docs/hiecm/v3/api/m1/endpoints/m1-access-tokens-encryption/02-m1-get-v3-profile-public-certificate).

## Where to go next

- [Gateway](/docs/hiecm/v3/concepts/gateway) for the session token every call needs.
- [M1 user journeys](/docs/hiecm/v3/milestones/m1), where the encrypted identifier appears in the search and login steps.


---

# FHIR and health record formats

Every health record that moves inside [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm) travels as a [FHIR](/docs/hiecm/v3/getting-started/glossary#fhir) bundle, not a PDF in an envelope of your own design and not your database rows. This page gives the version, the profiles, the bundle shape and how to validate one; the packaging detail is in the [M2 guide](/docs/hiecm/v3/api/m2).

## R4, with Indian profiles

ABDM uses FHIR release 4. Base FHIR is loose: it says a `MedicationRequest` exists, not which fields an Indian prescription must fill. That second layer is a profile, and for ABDM the profiles are published by the National Resource Centre for EHR Standards, NRCES, at [nrces.in/ndhm/fhir/r4](https://nrces.in/ndhm/fhir/r4/index.html). "ABDM compliant FHIR" means R4 conforming to those profiles. Read the NRCES implementation guide for field level questions. It is not restated here.

## Two ways to build any record

| Shape             | What it is                                                             | When you use it                                          |
| ----------------- | ---------------------------------------------------------------------- | -------------------------------------------------------- |
| Simple bundle     | A FHIR bundle wrapping a PDF or image attachment that holds the detail | Your source document is a scan, a signed PDF or an image |
| Structured bundle | A FHIR bundle with coded health information in FHIR resources          | Your system holds the data as fields, and can code it    |

Both are compliant. A structured bundle is more useful to the receiver, because it can be searched rather than only displayed.

## The record types

There are eight record types. Implementing all of them is mandatory for an [HMIS](/docs/hiecm/v3/getting-started/glossary#hmis).

| Record type              | What it holds                                                                                                                    | [HI type](/docs/hiecm/v3/getting-started/glossary#hi-type) code |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Diagnostic Report Record | Radiology and laboratory reports                                                                                                 | `DiagnosticReport`                                              |
| Discharge Summary Record | The discharge summary for the ABDM health data set                                                                               | `DischargeSummary`                                              |
| Health Document Record   | Unstructured historical records, usually uploaded by patients through a health locker                                            | `HealthDocumentRecord`                                          |
| Immunization Record      | Immunisations, vaccine certificates and next dose recommendations                                                                | `ImmunizationRecord`                                            |
| OP Consult Record        | Outpatient notes: examinations, procedures, medications and clinical advice                                                      | `OPConsultation`                                                |
| Prescription Record      | Medication advice, following Pharmacy Council of India guidelines                                                                | `Prescription`                                                  |
| Wellness Record          | Vitals, physical examination and general health data, often captured in a [PHR](/docs/hiecm/v3/getting-started/glossary#phr) app | `WellnessRecord`                                                |
| Invoice Record           | Pharmacy invoices, consultation invoices and other billing                                                                       | `Invoice`                                                       |

The codes are the eight `hiTypes` values the linking and consent requests accept, `Invoice` included.

## Which resources a record carries

The reference service on the [HIU](/docs/hiecm/v3/getting-started/glossary#hiu) side supports these resources inside a bundle.

- **Clinical content:** `Observation`, `Condition`, `MedicationRequest`, `DocumentReference`, `DiagnosticReport`, `Procedure`.
- **Context and reference entities:** `Medication`, `Practitioner`, `Patient`, `Organization`, `Encounter`.

That is the union across record types, not a mapping. Which resources belong to which record type is not documented here. The NRCES profile for each type is the authority.

## The bundle shape

Every record is a `Bundle` of `type: document`, and the first entry must be a `Composition`.

```json
{  "resourceType": "Bundle",  "id": "bundle01",  "timestamp": "2020-01-01T15:32:26.605+05:30",  "type": "document",  "entry": [    {      "fullUrl": "Composition/1",      "resource": {        "resourceType": "Composition",        "id": "1",        "status": "final",        "type": {          "coding": [            {              "system": "https://ndhm.gov.in/sct",              "code": "440545006",              "display": "Prescription record"            }          ]        }      }    }  ]}
```

That is the skeleton.

### Why the Composition comes first

A bundle on its own is a bag of resources. The Composition turns it into a document: what this is, who it is about, who wrote it, who attests to it, and which resources make up its sections. Without it, a receiving system has a `MedicationRequest` and no idea whether it belongs to a prescription, a discharge summary or a draft.

`Composition.type` carries the SNOMED CT code that answers "what is this". Two are documented: `440545006` for a prescription record and `721981007` for a diagnostic report. The rest have their own codes in the NRCES profiles.

### The rules that fail validation

| Field                         | Rule                                                                                                                                                                                      |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                          | Unique per bundle, and resolvable inside your own system for traceability                                                                                                                 |
| `timestamp`                   | The time the document was issued                                                                                                                                                          |
| `identifier`                  | Traces the document back to your system                                                                                                                                                   |
| `type`                        | Must be `document`                                                                                                                                                                        |
| `meta.versionId`              | Set it on the bundle, so updates can be checked against the latest version                                                                                                                |
| `entry[].fullUrl`             | A logical URL of the form `resource-type/id`, resolvable inside the bundle. Never an absolute URL.                                                                                        |
| `Composition.attester.party`  | References an `Organization` whose `identifier.value` is the facility's [HIP](/docs/hiecm/v3/getting-started/glossary#hip) id as registered in the facility registry. Mode is `official`. |
| `Composition.section.entry[]` | Top level resources only. Referenced resources such as Patient, Encounter and Practitioner belong in the bundle, not in the section entries.                                              |

The attester rule has an environment trap. The organization identifier system is the ABDM facility registry at [nhpr.abdm.gov.in](https://nhpr.abdm.gov.in/nhpr/v4/home) for production and [hspsbx.abdm.gov.in](https://hspsbx.abdm.gov.in/nhpr/v4/home) for sandbox. A bundle that passes in sandbox with the sandbox value is not right in production.

One more thing to watch. `Composition.type.coding.system` is `https://ndhm.gov.in/sct` in the sample above, while `section.code.coding.system` in the same sample is `https://affinitydomain.in/sct`. The two differ in the sample itself. Take the system values from the NRCES profile, not from the sample.

## Validate before you ship

Run this procedure locally. You need JDK 8 or higher.

1. Create a folder and download the FHIR validator CLI, version 6.2.1, from [the HAPI FHIR core release](https://github.com/hapifhir/org.hl7.fhir.core/releases/download/6.2.1/validator_cli.jar). Save `validator_cli.jar` into it.
2. Get a bundle to test: one your own system produced, or an NRCES example from [nrces.in/ndhm/fhir/r4](https://nrces.in/ndhm/fhir/r4/index.html), switching to the JSON tab to download it.
3. Run the validator from that folder:

```shell
java -jar validator_cli.jar <YOUR_BUNDLE_FILENAME>.json -ig https://nrces.in/ndhm/fhir/r4
```

It checks structural correctness, conformance to the NRCES profiles, and required fields and constraints. Editing an NRCES example that already validates towards your own data is faster than starting from an empty file.

## Where this is implemented

- [M2 use cases](/reference/hiecm-m2), the transfer call that carries the encrypted bundle.
- [How a record travels](/docs/hiecm/v3/concepts/data-flow), what happens to the bundle after you build it.
- [Care contexts and linking](/docs/hiecm/v3/concepts/linking), how records are grouped and made findable.
- [Consent](/docs/hiecm/v3/concepts/consent), where the HI type codes above are chosen and read.


---

# The ABDM gateway

The gateway is the routing layer for [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm). You never call a hospital, a lab or a [PHR](/docs/hiecm/v3/getting-started/glossary#phr) app directly. The answer to a call arrives later at an endpoint you expose, and the gateway issues the access token every other call carries.

## Gateway and HIE-CM are not the same thing

[HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm) is the service: patient identity, care context links and consent. Its four modules and who builds which are on [Integration milestones](/docs/hiecm/v3/milestones).

The gateway is its front door. It authenticates you, validates your headers, and routes each call. Your consent request goes to `/api/hiecm/consent/v3/request/init` on the gateway host, and the gateway puts it in front of the patient's consent manager.

## HIE-CM is data blind

It never holds a patient's health record, only identifiers, metadata about where records live, and consent artefacts. Once consent exists the record goes straight from the system that holds it to the system that asked, encrypted. Your system keeps the data. HIE-CM keeps the permission.

## Nothing goes participant to participant

Every request is addressed to the gateway, which forwards it. Two things follow.

- **You get an acknowledgement, not an answer.** In the [M3](/docs/hiecm/v3/getting-started/glossary#m3) consent flow the [HIU](/docs/hiecm/v3/getting-started/glossary#hiu) asks, the HIE-CM returns the consent request id on a callback, and the patient's decision comes back later. Each call's page in the [API reference](/docs/hiecm/v3/api) names the callback it produces.
- **You have to be reachable.** Half of [M2](/docs/hiecm/v3/getting-started/glossary#m2) is endpoints the gateway calls on your system.

One exception. In the health information flow the HIU supplies a data push URL, and the HIP encrypts the records and pushes them there. That URL may differ from the HIU's registered gateway URL, to improve privacy. The permission came through the gateway. The bytes do not.

## What moves through it

| Module                      | What the gateway routes                                                                                                                                                                   | Reference                               |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| [M1](/docs/hiecm/v3/api/m1) | Session tokens, and the calls that create and authenticate an ABHA identity                                                                                                               | [M1 API reference](/reference/hiecm-m1) |
| [M2](/docs/hiecm/v3/api/m2) | [Discovery](/docs/hiecm/v3/getting-started/glossary#discovery), care context linking, health information requests to a HIP                                                                | [M2 API reference](/reference/hiecm-m2) |
| [M3](/docs/hiecm/v3/api/m3) | Consent requests, consent notifications, artefact fetches, data flow requests                                                                                                             | [M3 API reference](/reference/hiecm-m3) |
| [M4](/docs/hiecm/v3/api/m4) | The [HPR](/docs/hiecm/v3/getting-started/glossary#hpr) and [HFR](/docs/hiecm/v3/getting-started/glossary#hfr) registry calls, which carry their own token from `POST /getManagementToken` | [M4 API reference](/reference/hiecm-m4) |

The gateway holds no health record. It routes the permission and the metadata.

## The session endpoint

One endpoint issues the token every other call carries. It is the call [M1](/docs/hiecm/v3/getting-started/glossary#m1) uses. [M4](/docs/hiecm/v3/getting-started/glossary#m4) declares bearer authentication, and its HPID calls publish `POST /getManagementToken`.

**POST** `/api/hiecm/gateway/v3/sessions`

Headers:

| Header         | Example value                          | What it is                                 |
| -------------- | -------------------------------------- | ------------------------------------------ |
| `REQUEST-ID`   | `18235d89-cb13-479d-ad71-7a57d5f669a8` | A fresh UUID for this call                 |
| `TIMESTAMP`    | `2022-10-06T15:10:00.587Z`             | The time you made the call, ISO 8601       |
| `X-CM-ID`      | `sbx`                                  | The consent manager. Use `sbx` for sandbox |
| `Content-Type` | `application/json`                     |                                            |

No `Authorization` header on this call. It is the one call with no token yet.

Body:

```json
{  "clientId": "<CLIENT_ID_FROM_SANDBOX_SIGNUP>",  "clientSecret": "<CLIENT_SECRET_FROM_SANDBOX_SIGNUP>",  "grantType": "client_credentials"}
```

Send the client id you were issued.

Response shape:

```json
{  "accessToken": "<JWT>",  "expiresIn": 1200,  "refreshExpiresIn": 1800,  "refreshToken": "<JWT>",  "tokenType": "bearer"}
```

The response carries the token in `accessToken`.

Send the token back as `Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL>` on every other call. Headers per call, and the second token M1 login issues, are on [authentication](/docs/hiecm/v3/reference/authentication). Interactive: [gateway API reference](/reference/hiecm-gateway).

## Which host

Two hosts serve gateway paths.

| Host                       | Environment |
| -------------------------- | ----------- |
| `https://dev.abdm.gov.in`  | Sandbox     |
| `https://apis.abdm.gov.in` | Production  |

Keep the host in configuration, not in code.

## Limits to code against

- **Callback retries.** Make your endpoint idempotent and assume a repeat.
- **Gateway token lifetime.** Read `expiresIn` from your own response rather than hard coding a value.
- **Rate limits.** Two codes enforce them: `ABDM-1022 Too many requests` and `ABDM-1027 You are blocked. Please try again after 24 hours.` The thresholds are not published, so back off on both.
- **Request signing.** The gateway request itself is not signed. Payload encryption and signing apply to health records, on the [M2](/docs/hiecm/v3/api/m2) side.

## Next

- [Authentication](/docs/hiecm/v3/reference/authentication), credentials and headers.
- [API references](/docs/hiecm/v3/api), every call and the callback it produces.
- [Integration milestones](/docs/hiecm/v3/milestones), the four modules and who builds which.
- [Registries](/docs/hiecm/v3/registries), who and what ABDM identifies.
- [Error codes](/docs/hiecm/v3/reference/error-codes), what a rejection means.


---

# Hospital, lab and pharmacy systems

A facility publishing a record through your software is the [HIP](/docs/hiecm/v3/getting-started/glossary#hip), the health information provider in [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm). Your job has two halves. Identify the patient by their [ABHA](/docs/hiecm/v3/getting-started/glossary#abha) address at registration, which is [M1](/docs/hiecm/v3/api/m1). Make the records the facility creates discoverable and shareable, which is [M2](/docs/hiecm/v3/api/m2).

## Before you start

- **A valid facility ID, registered in the HIP role.** That authorises the facility to create health records and share them with whoever asks to read them as the [HIU](/docs/hiecm/v3/getting-started/glossary#hiu). Registration lives in the [Health Facility Registry](/docs/hiecm/v3/registries).
- **A link to an [HRP](/docs/hiecm/v3/getting-started/glossary#hrp), a health repository provider**, so discovery reaches you. The facility is the HRP in most integrations, and the [HMIS](/docs/hiecm/v3/getting-started/glossary#hmis) or [LMIS](/docs/hiecm/v3/getting-started/glossary#lmis) you run is how it holds the records. Where a facility's records sit with another organisation, that organisation is the HRP.

| Purpose                          | Sandbox                                    | Production                 |
| -------------------------------- | ------------------------------------------ | -------------------------- |
| ABHA identity APIs (M1)          | `https://abhasbx.abdm.gov.in/abha/api/v3/` |                            |
| Gateway and record exchange (M2) | `https://dev.abdm.gov.in`                  | `https://apis.abdm.gov.in` |

## What you build in M1

M1 is the registration desk: create an ABHA for a patient who does not have one, or verify the one they do have. Each capability is mandatory or optional, differently for private and government integrators.

| Capability                                                        | Private integrators | Government integrators                             |
| ----------------------------------------------------------------- | ------------------- | -------------------------------------------------- |
| ABHA creation by Aadhaar OTP                                      | Mandatory           | Mandatory                                          |
| ABHA creation by Aadhaar face authentication                      | Optional            | Optional                                           |
| ABHA creation by Aadhaar biometrics, fingerprint or IRIS          | Optional            | Optional                                           |
| ABHA creation by Aadhaar demographic authentication               | Not required        | Mandatory                                          |
| Child ABHA                                                        | Not available       | Specific integrators, with NHA leadership approval |
| Login by mobile number, Aadhaar number, ABHA number, ABHA address | Mandatory           | Mandatory                                          |
| Fetch user profile                                                | Mandatory           | Mandatory                                          |
| Download ABHA card                                                | Mandatory           | Mandatory                                          |
| Mobile number management                                          | Optional            | Optional                                           |
| Re-KYC                                                            | Optional            | Optional                                           |
| Benefit programme search, link and delink                         | Not available       | Government only                                    |
| Session and refresh token APIs                                    | Mandatory           | Mandatory                                          |

Face authentication runs through the ABHA app and the Aadhaar RD service: your portal generates a QR code, the patient scans it in the ABHA app, and you poll for the result. Biometric creation needs an Aadhaar registered device, and UIDAI publishes the device list at <https://uidai.gov.in/en/ecosystem/authentication-devices-documents/biometric-devices.html>.

Implement two validation algorithms locally before you spend an API call: Luhn for an ABHA number, Verhoeff for an Aadhaar number.

## What you build in M2

Five things have to work.

1. **Health records in the right format.** A [FHIR](/docs/hiecm/v3/getting-started/glossary#fhir) R4 bundle following the NRCES profiles at <https://nrces.in/ndhm/fhir/r4/index.html>, either simple with a PDF or image attachment or structured with coded information. There are eight record types, all mandatory for an HMIS. See [FHIR and health record formats](/docs/hiecm/v3/concepts/fhir).
2. **Care contexts.** The unit that attaches to an ABHA address. The [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm) is data blind and holds two fields per care context: your internal reference ID, and a display name with nothing clinical in it. Use one per outpatient visit and one per inpatient admission.
3. **Linking.** Two routes: HIP initiated with their ABHA address, and discovery when the patient comes looking from their [PHR](/docs/hiecm/v3/getting-started/glossary#phr) app. Linking needs a linking token, stored at registration, valid 6 months, regenerated with the generate link token call. See [Care contexts and linking](/docs/hiecm/v3/concepts/linking).
4. **Answering discovery.** Mandatory for every HIP. Match on the verified identifiers the gateway sends, weight them above the patient declared ones, and return reference ID and display name pairs. The response carries no clinical or sensitive information. Metadata only.
5. **Health information request and data transfer.** Validate the consent ID and the date range against the artefact, then retrieve, encrypt with the HIU's key material, sign with your long term private key, push to the data push URL and notify with `health-information/notify`. The timeout is 20 minutes from the start of the request; split large data such as CT or MRI images into parts, streaming rather than sending one payload. See [How a record travels](/docs/hiecm/v3/concepts/data-flow).

## How linking fits a clinical workflow

1. **Registration.** The patient gives an ABHA address, or scans your counter QR code and shares their profile, or gives only name, mobile, age and gender.
2. **Store the linking token** against that patient record. You need it for every visit for 6 months.
3. **Care happens.** Your system produces a prescription, a report, a discharge summary.
4. **Group the records.** One care context per OPD visit, one per IPD admission.
5. **Link when the record is ready to share**, not when the visit opens.
6. **Wait.** The HIE-CM notifies the patient's PHR app, the app raises a consent request, and when consent is granted a health information request arrives.
7. **Validate, encrypt, push, notify.** Inside 20 minutes.

Steps 1 and 2 are M1 work in your registration module. Steps 4 to 7 are M2 work, and most of it belongs in a background job, not the clinician's screen.

## Testing the loop in sandbox

There is a single end to end check:

1. Log in to a PHR app with a sandbox ABHA address.
2. Register a patient with that same ABHA address in your system.
3. Create a health record for that patient.
4. Link a care context for it using HIP initiated linking.
5. The PHR app requests the record with the appropriate consent.
6. Prepare, encrypt and transfer the record to the data push URL the app supplied.
7. The record appears in the PHR app.

Codes that cover its failures: `ABDM-1038` ABHA address and link token mismatch, `ABDM-1056` care context already linked.

## What you do not need to build

- **Consent screens.** Consent is collected in the patient's PHR app. You validate the artefact.
- **Record storage for other facilities.** You share your own records.
- **Fetching records as the HIU**, unless the facility also reads records from elsewhere. That is [M3](/docs/hiecm/v3/api/m3), a separate integration.
- **[UHI](/docs/hiecm/v3/getting-started/glossary#uhi).** Appointments, ambulances and pharmacy ordering run on a different gateway.
- **[NHCX](/docs/hiecm/v3/getting-started/glossary#nhcx).** Claims exchange runs on a different gateway again, and no endpoint on it has been documented here yet.

## What to read next

- [M1 overview](/docs/hiecm/v3/api/m1) and the [M1 API reference](/reference/hiecm-m1).
- [M2 overview](/docs/hiecm/v3/api/m2) and the [M2 API reference](/reference/hiecm-m2).
- [M2 errors](/docs/hiecm/v3/api/m2/errors), the full ABDM error code list.
- [M2 steps and calls](/reference/hiecm-m2), what sandbox exit asks you to demonstrate.
- [PHR applications](/docs/hiecm/v3/concepts/participants/phr), the other side of every flow here.


---

# How the pieces fit

[ABDM](/docs/hiecm/v3/getting-started/glossary#abdm) has three moving parts: registries that issue identifiers, the [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm) gateway that routes requests and holds consent, and the two roles a record moves between.

## In short

- Two identities come first: the care seeker's ABHA, and the care provider's HPR and HFR.
- There are two integrator roles, IMS or PHR. HIP and HIU are not roles, they are the two ends of one record moving.
- Two configuration levels: your integration is one bridge, and every facility it serves links to that bridge. Neither is set inside the other.
- Records never move to a centre. A pointer and a consent move, then the record goes point to point.

## Two identities come first

Every call carries an identifier issued by a registry, and there are two kinds of entity to identify: the care seeker, and the care provider giving them care. Creating those entries comes before anything else.

| Identity      | Registry                                  | Who it identifies                               | Identifier                                 | Written by                  |
| ------------- | ----------------------------------------- | ----------------------------------------------- | ------------------------------------------ | --------------------------- |
| Care seeker   | [ABHA](/docs/hiecm/v3/registries/abha)    | A patient                                       | 14 digit ABHA number, plus an ABHA address | [M1](/docs/hiecm/v3/api/m1) |
| Care provider | [HPR](/docs/hiecm/v3/registries/nhpr/hpr) | A doctor, nurse, pharmacist or facility manager | HPR ID                                     | [M4](/docs/hiecm/v3/api/m4) |
| Care provider | [HFR](/docs/hiecm/v3/registries/nhpr/hfr) | A hospital, clinic, lab or pharmacy             | Facility ID                                | [M4](/docs/hiecm/v3/api/m4) |

[ABHA](/docs/hiecm/v3/getting-started/glossary#abha) is the care seeker's. [HPR](/docs/hiecm/v3/getting-started/glossary#hpr) and [HFR](/docs/hiecm/v3/getting-started/glossary#hfr) sit together under NHPR and are the care provider's: one for the professional, one for the place. [Registries](/docs/hiecm/v3/registries) has what each one holds.

## The gateway sits in the middle

Apart from the transfer of the record itself, your system never calls another participant directly. You call the gateway, it forwards the request, and the answer arrives at your callback URL as a separate inbound call. That is why every flow here is drawn as a sequence.

HIE-CM is data blind. It holds identifiers, metadata about where records live, and consent artefacts, never the record itself. It does not access or store health record content.

[The ABDM gateway](/docs/hiecm/v3/concepts/gateway) covers the gateway and the session token every call carries.

## Your role is IMS or PHR

There are two integrator roles on HIE-CM, and your product is one of them for its whole life. What decides it is which entity your software acts for.

| Role                                               | It acts for                                                                                             | What you build                                                           |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [IMS](/docs/hiecm/v3/getting-started/glossary#ims) | A care provider. An HMIS in a hospital, an EMR in a clinic, a LIMS in a laboratory, a PMS in a pharmacy | [M1](/docs/hiecm/v3/milestones/m1) to [M4](/docs/hiecm/v3/milestones/m4) |
| [PHR](/docs/hiecm/v3/getting-started/glossary#phr) | A care seeker, who holds their own records and gives consent                                            | [P1](/docs/hiecm/v3/milestones/p1) to [P3](/docs/hiecm/v3/milestones/p3) |

[HIP](/docs/hiecm/v3/getting-started/glossary#hip) and [HIU](/docs/hiecm/v3/getting-started/glossary#hiu) are not a third and a fourth role, and they are not something you register as. They are the two ends of one record moving: whoever publishes it is the HIP for that exchange, and whoever asks to read one they did not create is the HIU.

Both roles are both, and it changes call by call:

- A hospital is the HIP when it shares a discharge summary, and the HIU when it pulls an earlier prescription, through the same IMS.
- A citizen is the HIP when they push a record from their PHR application, and the HIU when they fetch one.

Neither is a thing you can build once and be. See [HIP and HIU](/docs/hiecm/v3/concepts/hip-hiu).

## One bridge, many facilities

Two levels of configuration exist and they are easy to confuse. Your integration registers once, as a bridge. The facilities it serves register separately and are linked to that bridge. One bridge serves every facility linked to it, whether that is one facility or a hundred.

Decide which level a setting belongs to before you build a settings screen for it. Nothing about your integration is configured per facility, and nothing about a facility is configured in your integration's own credentials.

| Setting                       | Level                                      | Where it is set                                                                                 |
| ----------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| Client id and client secret   | Your integration, one of each              | [Sandbox registration](/docs/hiecm/v3/getting-started/sandbox)                                  |
| Bridge callback URL           | Your integration, one                      | [Sandbox registration](/docs/hiecm/v3/getting-started/sandbox#3-register-your-callback-url)     |
| Facility ID                   | Each facility                              | [HFR onboarding](/docs/hiecm/v3/milestones/m4#journey-3-a-facility-onboards-to-the-hfr)         |
| `bridgeId`, `hipName`, `type` | Each facility, once per bridge it links to | [The bridge linkage call](/docs/hiecm/v3/milestones/m4#journey-4-linking-bridges-to-a-facility) |

Every callback for every facility arrives at the one bridge URL. The header says which facility it belongs to: `X-HIP-ID` in [M2](/docs/hiecm/v3/api/m2), and `X-HIU-ID` in [M3](/docs/hiecm/v3/api/m3). That header is what your handler routes a callback on, and the facility ID is what your records key to.

A callback URL kept in a facility's settings is a design error, and so is a client secret. Either survives the first facility and fails on the next. See [the headers](/docs/hiecm/v3/reference/authentication) for what travels on each call.

## Records stay where they were created

ABDM has no central store. A record stays in the system that created it. What moves is smaller:

- A **care context** is a pointer, not content: a reference number and a display name. Putting a diagnosis or a result in that name is not allowed. See [linking](/docs/hiecm/v3/concepts/linking).
- A **consent artefact** is the patient's permission, scoped by purpose, record type and date range. See [consent](/docs/hiecm/v3/concepts/consent).
- The **record** goes point to point, encrypted, from the HIP that holds it to the HIU that asked, once a consent artefact exists. It is packaged as a [FHIR](/docs/hiecm/v3/getting-started/glossary#fhir) R4 bundle. See [data flow](/docs/hiecm/v3/concepts/data-flow) and [FHIR](/docs/hiecm/v3/concepts/fhir).

## One path end to end

1. The patient has an ABHA identity.
2. The facility is listed in the HFR and gets a Facility ID.
3. The facility links its software as a bridge, which makes your system resolvable as that facility.
4. Records created there become care contexts, linked to the patient's ABHA address through HIE-CM, and the patient sees them in a PHR app.
5. Another system asks for those records, and the patient decides whether to allow it.

The doctor's HPR ID sits alongside. It identifies the professional inside a record and authorises facility registration.

## Next

[Your integration path](/docs/hiecm/v3/milestones) for what each role has to build.


---

# Care contexts and linking

A health record your system creates is invisible to [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm) until you link it, which means telling the [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm) that a named group of records exists at your facility for a named person. Until that happens no patient can discover the record and no consent request can reach it; the calls that do it are in the [M2 guide](/docs/hiecm/v3/api/m2).

## The unit that gets linked is a care context

You do not link a record. You link a [care context](/docs/hiecm/v3/concepts/care-context), a logical grouping of a patient's health records that your system defines. It carries a reference ID and a display name, and nothing else. What each field holds, and how to structure care contexts per visit and per admission, is on [Care contexts](/docs/hiecm/v3/concepts/care-context).

## Why the record has to be linked first

The HIE-CM is data blind. It holds a map: which [ABHA address](/docs/hiecm/v3/getting-started/glossary#abha-address) has care contexts at which facilities. Linking puts an entry on that map, and everything downstream reads it.

- A [PHR](/docs/hiecm/v3/getting-started/glossary#phr) app shows a patient their records by reading their linked care contexts.
- A consent request names record types and a date range, and the HIE-CM works out which record holders to notify from the links.
- A health information request arrives quoting a care context you linked.

An unlinked record is not private. It is absent.

## Link when the record is ready to share

Link as soon as the health record is ready to be shared, not when the visit opens and not at the end of the month.

Whenever a care context is linked, or an existing one gains new records, the HIE-CM notifies every PHR application subscribed to that ABHA address. You do not send those notifications. You trigger them by linking.

## Three routes onto the map

Which route applies depends on what the patient gave you at registration.

| Route                                                                   | When it applies                                                     | Who starts it             |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------- |
| [HIP](/docs/hiecm/v3/getting-started/glossary#hip) initiated linking    | The patient shared their ABHA address with you                      | You                       |
| Notification to mobile                                                  | You hold a mobile number, name, age and gender, but no ABHA address | You, and then the patient |
| [Discovery](/docs/hiecm/v3/getting-started/glossary#discovery) and link | The patient goes looking for old records from their PHR app         | The patient               |

**HIP initiated linking.** You know who the patient is, so you assign each new record to a care context and link it against their ABHA address.

**Notification to mobile.** With no ABHA address to link to, you tell ABDM a record is ready. ABDM sends the patient an SMS with a secure deep link, which opens their PHR app or sends them to install one, where they can create an ABHA address, discover the record and link it. This route converts into the third one.

**Discovery and link.** The request comes to you. The patient picks the facility they visited in their PHR app, and the HIE-CM forwards a discovery request to the [HRP](/docs/hiecm/v3/getting-started/glossary#hrp) or HIP behind it. You match against your own patients and reply with care contexts, and the patient picks which to link. Implementing discovery is mandatory for every HIP, even if every patient gives you an ABHA address at the counter, because a patient who visited two years ago did not.

What you are handed splits in two:

- **Verified identifiers**, which you weight higher: ABHA address, mobile number, name, gender and year of birth.
- **Unverified, patient declared information**, typically a facility issued identifier such as a patient ID or a medical registration number.

Use the unverified value to sharpen a match, not to make one. The response carries care context metadata and nothing else: no diagnosis, no test result, no report content. Somebody who has not yet proved they are the patient reads it.

## The link token

Linking is authorised by a [link token](/docs/hiecm/v3/getting-started/glossary#link-token), not by your session token alone. The token ties your facility to one patient's ABHA address.

| Property                       | Rule                                                                                        |
| ------------------------------ | ------------------------------------------------------------------------------------------- |
| When you get it                | Generated and stored at the time the patient registers with you                             |
| Validity                       | Six months                                                                                  |
| Before use                     | Validate it, for example with a tool like JWT.io. Which check to run is not documented yet. |
| If you do not have a valid one | Regenerate it through demographic authentication                                            |

Store it against the patient record, not the visit: you need it for every link you make for that patient over six months. Check it before you link, not after the gateway rejects you.

## What links look like when they go wrong

From the M2 error table. Read the code with the message the gateway returns, because the table reuses some codes against more than one message.

| Code        | Message                                    |
| ----------- | ------------------------------------------ |
| `ABDM-1026` | Invalid Link Token                         |
| `ABDM-1038` | ABHA address and Link token mismatch       |
| `ABDM-1056` | This care contexts has been already linked |
| `ABDM-1057` | Invalid Care Contexts                      |
| `ABDM-1060` | Invalid Patient Reference Number           |
| `ABDM-1090` | Duplicate HIP link request                 |

The full list is on [M2 errors](/docs/hiecm/v3/api/m2/errors).

## Where this is implemented

- [Hospital, lab and pharmacy systems](/docs/hiecm/v3/concepts/hip-hiu), what a facility builds to do the linking.
- [M2 Health Information Provider, Health Information Provider Services](/docs/hiecm/v3/api/m2), the call order for all three routes.
- [Consent](/docs/hiecm/v3/concepts/consent), what happens once somebody asks for a linked care context.
- [How a record travels](/docs/hiecm/v3/concepts/data-flow), what you do when that request arrives.
- [PHR applications](/docs/hiecm/v3/concepts/participants/phr), the patient side of discovery and linking.


---

# Citizen

You are the person the health records are about. You build nothing and call nothing. You hold an identity, and you decide who sees what.

## Who you are in ABDM

Your identity is an [ABHA](/docs/hiecm/v3/getting-started/glossary#abha), the Ayushman Bharat Health Account. It has two parts.

|                | ABHA number                                                                            | ABHA address                               |
| -------------- | -------------------------------------------------------------------------------------- | ------------------------------------------ |
| What it is     | 14 digits, such as `91-XXXX-XXXX-XXXX`                                                 | A readable name, such as `name@abdm`       |
| How you get it | After an Aadhaar based [KYC](/docs/hiecm/v3/getting-started/glossary#kyc) check passes | You choose it, or you are issued a default |
| What it does   | Anchors one person to one number                                                       | Routes records and consent requests to you |

You can hold an address without a number, created from a mobile number, name, year of birth and gender. That profile is self declared and carries no KYC.

A [PHR](/docs/hiecm/v3/getting-started/glossary#phr) app holds your account and acts for you. Hospitals, laboratories and pharmacies address records to your ABHA address.

## What you can do

- Create an ABHA, by Aadhaar [OTP](/docs/hiecm/v3/getting-started/glossary#otp), face authentication, biometrics or a demographic match.
- Share your profile at a counter by scanning the facility's QR code, and see what is being shared before you agree.
- Search for a facility you visited, find records nobody has linked yet, and link them to your address.
- Read a consent request in full: who is asking, why, which record types, which dates, and how long the access lasts.
- Narrow it before you approve. You can change the access duration, the record date range, the data categories and the validity period.
- Grant, deny, or revoke later. Revoking stops sharing under that consent immediately.

## Why it is worth it

Your records stay in the systems that created them. The [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm) holds identifiers, pointers and consent, never the record itself. Nothing central collects your health history.

One address pulls records from many facilities into one app you choose. A permission you give is scoped and time boxed rather than open ended. Both sides of a transfer report it, so an exchange under your consent leaves a trail you can see.

## Next

[Consent](/docs/hiecm/v3/concepts/consent) explains what a request carries and the states it moves through.


---

# Doctor

You are a registered healthcare professional. Your identity in [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm) is personal, it is separate from the facility you work in, and the facility cannot register without someone who holds one.

## Who you are in ABDM

You register on the [HPR](/docs/hiecm/v3/getting-started/glossary#hpr), the Healthcare Professionals Registry, and are issued an [HPID](/docs/hiecm/v3/getting-started/glossary#hpid). It is a 14 digit, Aadhaar authenticated identifier, written as both HPID and HPR ID.

| Form        | Sample              | Sent as                                     |
| ----------- | ------------------- | ------------------------------------------- |
| The number  | `71-2665-5777-XXXX` | `hpid` or `hprIdNumber`                     |
| The address | `name@hpr.abdm`     | `hprId`, with a `domainName` of `@hpr.abdm` |

Three categories can enrol today: doctor, nurse and pharmacist. You also declare a system of medicine. A role code says what you are on the registry: 1 for a healthcare professional, 2 for a facility manager, 3 for both.

Your HPR ID identifies you as a professional. It does not put your software on the network, and it is not the [HFR](/docs/hiecm/v3/getting-started/glossary#hfr) facility ID your hospital holds.

## What you can do

- Create your HPID through Aadhaar authentication, then register the full profile: personal details, communication address, council registration, qualification and current work.
- Upload your degree certificate and registration certificate. Both are mandatory.
- Get a fresh HPR token later, by password, by mobile [OTP](/docs/hiecm/v3/getting-started/glossary#otp) or by Aadhaar OTP.
- With role 2 or role 3, register your facility on the HFR. Both calls take `x-hprid-auth`, and submit also takes `x-hprid-auth-verifier`.

Records themselves carry a `Practitioner` resource inside the [FHIR](/docs/hiecm/v3/getting-started/glossary#fhir) bundle, so the professional behind a record is named in it.

## Why it is worth it

Your registration is a verified national identity, checked against Aadhaar and carrying your council registration and qualifications.

It is also the thing that unblocks your organisation. Nobody can register a facility, and therefore nobody can share or fetch records, until a person with facility manager rights exists. That person is you or a colleague.

No fee, payment or incentive for registering is documented here.

## Next

[HPR, the professional registry](/docs/hiecm/v3/registries/nhpr/hpr) has the call order, the profile blocks and the code lists.


---

# Hospital

You create health records and you want records created elsewhere. That puts you on both sides of every exchange in [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm).

## Who you are in ABDM

You enrol on the [HFR](/docs/hiecm/v3/getting-started/glossary#hfr), the Health Facility Registry, and a verified facility is issued a facility ID. Two formats are documented for it: `IN` followed by 10 characters on bridge linkage and search, and a 6 digit value on deduplicate search.

Registering the facility gives it an identity. Linking a [bridge](/docs/hiecm/v3/getting-started/glossary#bridge) makes your software resolvable as that facility, in the [HIP](/docs/hiecm/v3/getting-started/glossary#hip) or [HIU](/docs/hiecm/v3/getting-started/glossary#hiu) direction.

| Role | When you are it                     | Milestone                   |
| ---- | ----------------------------------- | --------------------------- |
| HIP  | You hold the record and send it     | [M2](/docs/hiecm/v3/api/m2) |
| HIU  | You ask for a record held elsewhere | [M3](/docs/hiecm/v3/api/m3) |

Your clinicians hold their own [HPR](/docs/hiecm/v3/getting-started/glossary#hpr) IDs, and one of them needs facility manager rights before you can register at all.

## What you can do

- Identify the patient at registration by [ABHA](/docs/hiecm/v3/getting-started/glossary#abha) address, or create an ABHA for someone who has none.
- Group each visit into a [care context](/docs/hiecm/v3/getting-started/glossary#care-context) and link it, so the patient can find it.
- Answer [discovery](/docs/hiecm/v3/getting-started/glossary#discovery) when a patient comes looking from their app. This is mandatory for every HIP.
- Validate the consent, then encrypt, sign and push the records inside the 20 minute window.
- Ask for a patient's history from another facility, under a consent they grant.

## Why it is worth it

Enrolling on the HFR gets your facility a trusted identity, a listing in national search results, less paperwork on licence renewals and insurance empanelment, and access to ABDM's digital services.

On the exchange itself, a record you link appears in the patient's own app without you posting anything. Earlier records from other facilities reach your clinicians with the patient's consent instead of arriving as a paper folder. Your records stay in your system throughout. There is no central store to hand them to.

## Next

[Hospital, lab and pharmacy systems](/docs/hiecm/v3/concepts/hip-hiu) is the build guide for this role.


---

# Ecosystem participants

[ABDM](/docs/hiecm/v3/getting-started/glossary#abdm) is one network with several kinds of participant on it. Each holds an identifier issued by a registry, and each plays a role in the exchange. This section has one page per participant, and every page answers the same three questions: who you are, what you can do, and why it is worth taking part.

Two of the eight do not integrate with anything. A citizen carries an identity and makes decisions. We run the network and issue the identifiers. The other six build software.

| Participant                                               | Who they are                                                                                                             |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| [Citizen](/docs/hiecm/v3/concepts/participants/citizen)   | The person the records are about, holding an [ABHA](/docs/hiecm/v3/getting-started/glossary#abha) number and address     |
| [Doctor](/docs/hiecm/v3/concepts/participants/doctor)     | A registered professional holding an [HPID](/docs/hiecm/v3/getting-started/glossary#hpid) from the professional registry |
| [Hospital](/docs/hiecm/v3/concepts/participants/hospital) | A facility that creates records, shares them, and reads records held elsewhere                                           |
| [Diagnostics](/docs/hiecm/v3/concepts/participants/lab)   | A laboratory or imaging centre, sharing reports as a facility                                                            |
| [Pharmacy](/docs/hiecm/v3/concepts/participants/pharmacy) | A pharmacy, sharing prescription and billing records as a facility                                                       |
| [Insurer](/docs/hiecm/v3/concepts/participants/insurer)   | A payer that reads records under consent, and settles claims on a separate gateway                                       |
| [PHR app](/docs/hiecm/v3/concepts/participants/phr)       | The citizen's own app: identity, linking, consent and records                                                            |
| [NHA](/docs/hiecm/v3/concepts/participants/nha)           | The National Health Authority, which runs the gateways and the registries                                                |

## A role belongs to the entity, not the software

[HIP](/docs/hiecm/v3/getting-started/glossary#hip) and [HIU](/docs/hiecm/v3/getting-started/glossary#hiu) are roles an entity takes, not kinds of software and not kinds of company. Whoever holds a record and publishes it is the HIP: a facility publishing through its [HMIS](/docs/hiecm/v3/getting-started/glossary#hmis), or a citizen pushing a record from their PHR app. Whoever asks to read records they did not create is the HIU, and an insurer or a referral service asks while holding neither an ABHA address nor a facility ID. So a hospital, a laboratory and a pharmacy sit in the same position and differ only in the records they hold.

## Next

- [How the pieces fit](/docs/hiecm/v3/concepts/how-it-fits), the registries, the gateway and the roles in one page.
- [Your integration path](/docs/hiecm/v3/milestones), what each role has to build.


---

# Insurer

You sit on two gateways, and they share no API surface. Clinical records move on the [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm). Claims move on [NHCX](/docs/hiecm/v3/getting-started/glossary#nhcx).

## Who you are in ABDM

On the HIE-CM you take the [HIU](/docs/hiecm/v3/getting-started/glossary#hiu) role, health information user. That is a direction, not a category of company. Your organisation is the HIU whenever it asks to read records it did not create, and your software is how it asks.

On NHCX you are a payer, which covers an insurer or a third party administrator acting for one. You onboard as a participant, in sandbox first and then in production.

## Confirm at onboarding

- **Which registry entry your organisation holds on the HIE-CM.** The [HFR](/docs/hiecm/v3/getting-started/glossary#hfr) lists hospitals, clinics, laboratories, imaging centres, pharmacies and blood banks, and does not list insurers. Do not scope your build around a facility ID. [M4](/docs/hiecm/v3/api/m4) is required for an HIU, so ask which entry you register against before you plan that work. Build M1 and M3 meanwhile.

## What you can do

On the HIE-CM you build [M1](/docs/hiecm/v3/api/m1) for identity and [M3](/docs/hiecm/v3/api/m3) for consent and fetching.

- Raise a consent request naming the patient's [ABHA](/docs/hiecm/v3/getting-started/glossary#abha) address, the purpose, the record types and the date range.
- Use the purpose code `HPAYMT`, Healthcare Payment, where payment is the reason you are asking. The patient reads that code.
- Wait. The patient decides, and may narrow the request before granting it, so read the artefact rather than assuming you got what you asked for.
- Fetch under the granted artefact and decrypt.
- Handle revocation. A consent that was live when you sent the request can be dead when the record holder validates it.

## Why it is worth it

You receive structured records from the system that created them, as [FHIR](/docs/hiecm/v3/getting-started/glossary#fhir) bundles, instead of scans collected from the member. The permission behind each one is explicit, scoped and time boxed, and both sides report the transfer.

What this does not give you is claim settlement. That is NHCX work, and a separate integration.

## Next

[Consent](/docs/hiecm/v3/concepts/consent) covers what you may ask for, and [NHCX](/docs/nhcx/v1) covers the claims gateway.


---

# Diagnostics

A diagnostic laboratory or imaging centre publishes records as the [HIP](/docs/hiecm/v3/getting-started/glossary#hip), the same role a hospital takes. The machinery is identical. What changes is the records you hold.

## Who you are in ABDM

You enrol on the [HFR](/docs/hiecm/v3/getting-started/glossary#hfr), which lists diagnostic laboratories and imaging centres alongside hospitals, clinics and pharmacies. A verified facility is issued a facility ID, and linking a [bridge](/docs/hiecm/v3/getting-started/glossary#bridge) makes your software resolvable as that facility.

Two things in the facility record are yours. The additional information layer carries flags for a diagnostic lab and an imaging centre. The detailed information layer asks for diagnostic and imaging services, and an imaging centre or diagnostic laboratory does not have to submit medical infrastructure or bed counts at all.

## What you can do

Everything a hospital does as a HIP, and by the same calls. Group results into a [care context](/docs/hiecm/v3/getting-started/glossary#care-context), link it, answer [discovery](/docs/hiecm/v3/getting-started/glossary#discovery), validate the consent, then encrypt and push. Nothing in [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm) gives diagnostics a separate API surface.

The difference is the record type. Radiology and laboratory reports are the Diagnostic Report Record, code `DiagnosticReport`. Billing is the Invoice Record. All eight record types are mandatory for an [HMIS](/docs/hiecm/v3/getting-started/glossary#hmis), and which of them a diagnostics only system must implement is not documented here.

Large images are the one place your build differs in practice. Split a CT or MRI study into parts and stream it, inside the same 20 minute window.

If you also read a patient's earlier results, that is the [HIU](/docs/hiecm/v3/getting-started/glossary#hiu) direction and a separate integration.

## Why it is worth it

The registry gives your centre a trusted identity, a listing in national search results, less paperwork on licence renewals and insurance empanelment, and access to ABDM's digital services.

A report you link reaches the patient's own app. The doctor who ordered it can ask for it under consent rather than waiting for a printout to travel.

## Next

[Hospital, lab and pharmacy systems](/docs/hiecm/v3/concepts/hip-hiu) is the build guide, and [FHIR](/docs/hiecm/v3/concepts/fhir) has the record formats.


---

# NHA

The National Health Authority runs [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm), operates its gateways, and publishes this portal.

## Who NHA is in ABDM

The National Health Authority is the government body that runs the network. It publishes the specifications, and it operates both the [sandbox](/docs/hiecm/v3/getting-started/glossary#sandbox) and the production gateways.

It is not an integrator. There is no NHA system you exchange records with, and no role you take opposite it. It issues the identifiers you carry, routes your calls, and holds the permission that lets a record move.

## What NHA does

| What it runs                                             | What it gives you                                                                                           |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| [ABHA](/docs/hiecm/v3/registries/abha)                   | A patient's 14 digit ABHA number and their ABHA address                                                     |
| [HPR](/docs/hiecm/v3/registries/nhpr/hpr)                | An [HPID](/docs/hiecm/v3/getting-started/glossary#hpid) for a doctor, nurse, pharmacist or facility manager |
| [HFR](/docs/hiecm/v3/registries/nhpr/hfr)                | A facility ID for a hospital, clinic, laboratory, imaging centre or pharmacy                                |
| [The gateway](/docs/hiecm/v3/concepts/gateway)           | Your session token, header validation, and routing to every other participant                               |
| [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm) | Care context links, consent requests and consent artefacts                                                  |
| The sandbox                                              | Client credentials, test identities, and the milestone certification you submit                             |

One limit is deliberate. The HIE-CM is data blind. It holds identifiers, metadata about where records live, and consent artefacts. It never holds the record. Once consent exists, the record goes straight from the system that holds it to the system that asked, encrypted.

The National Health Authority runs two further gateways alongside the HIE-CM, each with its own specification. [UHI](/docs/hiecm/v3/getting-started/glossary#uhi) carries services such as appointments, and [NHCX](/docs/nhcx/v1) carries insurance claims.

## Why it is worth it

Because one authority runs the middle, you do not have to negotiate with every other participant. One identity works at every facility in the country. One consent model governs every transfer, so you implement it once. One certification path covers going live.

And because the HIE-CM is data blind, joining the network does not mean handing your patients' records to NHA. They stay where they were created, in your system, and they move only to a system the patient has allowed.

## Next

[How the pieces fit](/docs/hiecm/v3/concepts/how-it-fits) puts the registries, the gateway and your role in one page.


---

# Pharmacy

A pharmacy publishes records as the [HIP](/docs/hiecm/v3/getting-started/glossary#hip), the same role a hospital takes. The calls, the linking and the encryption are identical. What changes is the records you hold, and one thing that is not on this gateway at all.

## Who you are in ABDM

You enrol on the [HFR](/docs/hiecm/v3/getting-started/glossary#hfr), which lists pharmacies alongside hospitals, clinics and laboratories. A verified facility is issued a facility ID, and linking a [bridge](/docs/hiecm/v3/getting-started/glossary#bridge) makes your software resolvable as that facility.

Pharmacy appears twice in a facility record: as a facility type, and as a flag in the additional information layer for a facility that runs a pharmacy inside it. A pharmacy does not have to submit medical infrastructure or bed counts.

Your pharmacists can register on the [HPR](/docs/hiecm/v3/getting-started/glossary#hpr) as well. Pharmacist is one of the three professional categories open today.

## What you can do

Everything a hospital does as a HIP, and by the same calls. Group records into a [care context](/docs/hiecm/v3/getting-started/glossary#care-context), link it, answer [discovery](/docs/hiecm/v3/getting-started/glossary#discovery), validate the consent, then encrypt and push.

Two of the eight record types are the ones closest to your work. The Prescription Record holds medication advice and follows Pharmacy Council of India guidelines. The Invoice Record holds pharmacy invoices and other billing.

Whether dispensing has a record type of its own is not documented here. Ordering and fulfilment are not on this gateway: they run on [UHI](/docs/hiecm/v3/getting-started/glossary#uhi), which has a separate specification.

## Why it is worth it

The registry gives your pharmacy a trusted identity, a listing in national search results, less paperwork on licence renewals and insurance empanelment, and access to [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm)'s digital services.

A record you link reaches the patient's own app, so their medication history sits with the rest of their records instead of in a paper bag.

## Next

[Hospital, lab and pharmacy systems](/docs/hiecm/v3/concepts/hip-hiu) is the build guide, and [FHIR](/docs/hiecm/v3/concepts/fhir) has the record formats.


---

# Personal Health Record (PHR) Application

The Personal Health Record ([PHR](/docs/hiecm/v3/getting-started/glossary#phr)) application functions as the primary digital interface for the citizen within the Ayushman Bharat Digital Mission ([ABDM](/docs/hiecm/v3/getting-started/glossary#abdm)) ecosystem. It facilitates digital identity management, provides access to longitudinal health records, and serves as the centralized node for consent artifact management.

## Role and positioning within the ABDM architecture

The PHR application operates on behalf of the citizen and securely connects with healthcare facilities through the [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm). Health data is routed using the citizen's [ABHA address](/docs/hiecm/v3/getting-started/glossary#abha-address). The PHR application acts as an [HIU](/docs/hiecm/v3/getting-started/glossary#hiu) for fetching clinical records and as a [HIP](/docs/hiecm/v3/getting-started/glossary#hip) for sharing user-uploaded health documents and facility linked health documents. It must be listed in the ABDM Application Directory after Sandbox exit with its official name and marketplace URLs.

## Authorized capabilities and milestones

| Integration phase                                  | Functional capabilities                                                                                                                                                                                                 |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Phase 1 (P1)](/docs/hiecm/v3/milestones/p1)       | Facilitation of ABHA number and address creation, multiple authentication (four mandated login routes).                                                                                                                 |
| [Phase 2 (P2)](/docs/hiecm/v3/milestones/p2)       | Execution of facility-level Scan & Share, profile management, ABHA card and QR code generation, legacy record discovery, and standardized [Care Context](/docs/hiecm/v3/getting-started/glossary#care-context) linkage. |
| [Phase 3 (P3)](/docs/hiecm/v3/milestones/p3)       | Management of user locker subscriptions and system notifications, execution of consent decisions (approval/rejection), configuration of auto-approval policies, and the secure retrieval and storage of health records. |
| Health Locker ([M2](/docs/hiecm/v3/milestones/m2)) | Processing direct document uploads necessitates certification as a Health Locker (Health Repository Provider), which requires the successful completion of Milestone 2 (M2) integration.                                |

## Significance and ecosystem value

The PHR application platform empowers citizens by providing a central interface for consent management and control over their health information. Through HIE-CM, users receive notifications on the creation or modification of Care Contexts linked to their ABHA address, enabling aggregation of longitudinal health records based on approved consent policies. In addition, PHR applications and Health Lockers provide secure, long-term, user-managed storage of health records, complementing the statutory record-retention responsibilities of healthcare establishments.

## Next steps

- [P1 Identity and login](/docs/hiecm/v3/milestones/p1): creating an ABHA address and the login routes, with the [P1 API reference](/reference/hiecm-p1).
- [P2 Linking and records](/docs/hiecm/v3/milestones/p2): scan and share, discovery, the profile and the card, with the [P2 API reference](/reference/hiecm-p2).
- [P3 Consent and notifications](/docs/hiecm/v3/milestones/p3): subscriptions, auto approval, consent and fetching records. The subscription calls are in the [P3 API reference](/reference/hiecm-p3), the auto approval and consent calls in the [P2 API reference](/reference/hiecm-p2), and the health locker calls in the [P4 API reference](/reference/hiecm-p4).
- [Get started](/docs/hiecm/v3/getting-started/sandbox) for sandbox signup and your first call.


---

# Build it well

Every call on this site can be made correctly and still leave you with an integration that fails at a busy counter. What separates the two is handling: what you check before you call, what you do with what comes back, and what the person in front of you sees while it happens.

## In short

- Check locally what can be checked locally. A round trip that fails a format rule costs the person thirty seconds and tells them nothing.
- Read the body, not the status. ABDM returns several error shapes and only some carry a code.
- Retry only what is safe to retry. Enrolment and one time password calls are not.
- Say what failed and what the person can do next. A code on its own is not an error message.
- Map every field the profile returns, not the four you need this week.

## Validate before you send

These rules are the service's, and it applies them after it decrypts. Checking them in your own form turns a failed call into an inline message.

| What           | Rule                                                                                                                     | What it costs to skip                             |
| -------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| ABHA number    | 14 digits with dashes, `NN-NNNN-NNNN-NNNN`, before encryption                                                            | `400 {"loginId": "LoginId is invalid"}`           |
| ABHA address   | 8 to 18 characters, letters and digits with an optional `.` or `_`                                                       | A rejected address after the person has chosen it |
| Mobile number  | 10 digits, the first from 1 to 9, with an optional `+91` or `0` in front                                                 | A failed call that reads as a wrong number        |
| Aadhaar number | 12 digits, no spaces                                                                                                     | The same                                          |
| `REQUEST-ID`   | A fresh UUID on every call                                                                                               | Two calls you cannot tell apart later             |
| `TIMESTAMP`    | ISO 8601 in UTC, from a synchronised clock. Every header is in [authentication](/docs/hiecm/v3/reference/authentication) | Every call fails at once                          |

One thing you cannot check locally is whether the account exists. A well formed ABHA number that belongs to nobody returns `404 ABDM-1114 User not found`, and that is a different message to the person than a badly formed one. The plaintext shape for every encrypted field is in [encryption](/docs/hiecm/v3/concepts/encryption).

## Read the error, then decide

ABDM returns [several different error shapes](/docs/hiecm/v3/api/m1/errors), and only some of them carry a code. Parse for all of them before you write any handling, because the shape tells you where the failure came from.

Every code in the [error code reference](/docs/hiecm/v3/reference/error-codes) carries an action. Key your handling to that column rather than to a list of codes you maintain by hand.

| Action         | What your code does                                                           |
| -------------- | ----------------------------------------------------------------------------- |
| Fix request    | Do not retry. Something you sent is wrong, and sending it again will not help |
| Fix auth       | Fetch a fresh token, then retry once                                          |
| New request id | Generate a new `REQUEST-ID`, then retry once                                  |
| Retry          | Back off and retry, with a ceiling on attempts                                |
| Cannot proceed | Stop, and tell the person why in their own terms                              |
| Ask support    | Stop, and collect the ids before the context is lost                          |
| Unclassified   | Treat as Cannot proceed until you have seen it once and know better           |

Symptom first debugging, for the failures that produce no useful code at all, is in [troubleshooting](/docs/hiecm/v3/troubleshooting).

## Retries, and the calls you must not repeat

A retry is safe when repeating the call cannot create a second thing or burn a single use value. Most of M1 fails that test.

| Call                            | Safe to repeat | Why                                                                                               |
| ------------------------------- | -------------- | ------------------------------------------------------------------------------------------------- |
| Session token                   | Yes            | It issues a token and changes nothing else                                                        |
| Profile, card and QR code reads | Yes            | Reads                                                                                             |
| Request an OTP                  | No             | Rate limited. A retry loop is the usual cause of the lockout it is trying to escape               |
| Verify an OTP                   | No             | The OTP and the transaction id are both single use                                                |
| Enrol, or create an ABHA        | No             | A success you did not see still created an account                                                |
| Your callback handler           | It must be     | ABDM repeats callbacks, so deduplicate on the id the callback repeats before you apply any effect |

`REQUEST-ID` is the idempotency key, one fresh UUID per call, and it is what lets you tell a repeat from a new attempt in your own logs. See [authentication](/docs/hiecm/v3/reference/authentication) for the headers and [the gateway](/docs/hiecm/v3/concepts/gateway) for the limits.

## What the screen says when a call fails

The person at the counter cannot act on a code. They can act on what to do next.

| What happened                            | What the screen says                               | What it must not do                      |
| ---------------------------------------- | -------------------------------------------------- | ---------------------------------------- |
| The OTP did not match                    | Say so, keep the field, offer a resend             | Close the form or show a generic failure |
| Rate limited or locked out               | Name the actual wait, for example thirty minutes   | Say something went wrong                 |
| No account found                         | Show it as a result, not as an error               | Turn a normal empty result red           |
| The address already exists               | Offer the login route instead                      | Report a creation failure                |
| ABDM or the other party is not answering | Say it is not answering and to try again           | Imply the person typed something wrong   |
| Anything with no code at all             | Show the reference the person can quote to support | Print the raw response body              |

## The screens themselves

| Rule                                                                              | Why                                                                                                                                                                                                                                                                                                                |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| A step happening on somebody else's device is not a spinner                       | Face authentication waits on a person. Say that is what you are waiting for                                                                                                                                                                                                                                        |
| Show the masked destination before the wait                                       | The OTP request response names the masked mobile the OTP went to, which stops somebody waiting for a message that will never arrive                                                                                                                                                                                |
| Say upfront when the account will be restricted                                   | Otherwise the person meets the limit later, when something unrelated fails                                                                                                                                                                                                                                         |
| Answer scan and share inside thirty seconds                                       | The patient's screen is open for that long, and an acknowledgement after it shows them nothing                                                                                                                                                                                                                     |
| Offer the login methods the account actually has                                  | `authMethods` on the profile says which ones the person can use. A screen offering an Aadhaar OTP to a profile with no Aadhaar behind it fails for a reason nobody can see                                                                                                                                         |
| Put a setting at the level it belongs to                                          | Your credentials and your callback URL belong to the integration, the facility ID and the `hipId` belong to each facility. A settings screen that mixes them works for the first facility and fails on the next. See [one bridge, many facilities](/docs/hiecm/v3/concepts/how-it-fits#one-bridge-many-facilities) |
| Aadhaar numbers, one time passwords and passwords never reach a log or a database | Encrypting a value and then logging the plain one is the same leak, moved. See [encryption](/docs/hiecm/v3/concepts/encryption)                                                                                                                                                                                    |

The first four are journey specific and each is explained where it happens, on [the M1 journeys](/docs/hiecm/v3/milestones/m1).

## Map everything ABHA gives you

The most common M1 defect is a registration form wired to four fields when the profile returned twenty eight. The rest is then either retyped by a person who already gave it to Aadhaar, or lost.

`GET /v3/profile/account` returns the fields below. Map all of them, and decide for each whether your form shows it, locks it or lets a receptionist correct it.

| Profile field                                                        | Goes to                                                               | Editable in your form                                    |
| -------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------- |
| `ABHANumber`, `preferredAbhaAddress`                                 | The patient's ABDM identity, and the key you match on later           | Never                                                    |
| `name`, `firstName`, `middleName`, `lastName`                        | Patient name. Keep the parts, not only the joined string              | Only when `kycVerified` is false                         |
| `dayOfBirth`, `monthOfBirth`, `yearOfBirth`                          | Date of birth, assembled by you                                       | Only when `kycVerified` is false                         |
| `gender`                                                             | Gender, for example `M` or `F`                                        | Only when `kycVerified` is false                         |
| `mobile`                                                             | Contact number                                                        | Yes, it is the communication number and people change it |
| `address`, `pincode`, `stateName`, `districtName`, `subdistrictName` | Address. The `*Code` twins are the machine values, keep both          | Yes                                                      |
| `stateCode`, `districtCode`                                          | Your own reporting, which should key on codes rather than names       | Never                                                    |
| `kycVerified`, `verificationStatus`, `verificationType`              | Whether this identity was proved, and by what                         | Never                                                    |
| `authMethods`                                                        | What the person can log in with next time, so you offer the right one | Never                                                    |
| `kycPhoto`, `profilePhoto`                                           | Identity photo. Decide whether you store it at all before you do      | Never                                                    |
| `status`                                                             | Whether the account is active                                         | Never                                                    |
| `localizedDetails`                                                   | The same details in the person's own language, where NHA holds them   | Never                                                    |

`kycVerified` is the field the form design hangs off. A [profile with `kycVerified` true](/docs/hiecm/v3/milestones/m1#abha-with-aadhaar) was proved against Aadhaar, so its demographics are better evidence than anything typed at a desk and your form should lock them. A [profile with `kycVerified` false](/docs/hiecm/v3/milestones/p1) was not proved against Aadhaar, so it is correctable.

Two traps. Several of these fields can come back null, so a form that renders a blank labelled row for each is worse than one that hides them. And the profile comes back in more than one shape across M1: the update response types `yearOfBirth` as an integer where this one types it as a string, and the patient share payload and the PHR profile carry different names again. Map from one named endpoint and say which, rather than writing one mapper for something called the ABHA profile.

## Where to go next

- [Build with AI](/docs/hiecm/v3/getting-started/build-with-ai) for setting an agent up, and for how to prompt it against these rules.
- [Troubleshooting](/docs/hiecm/v3/troubleshooting) when something is already broken.
- [Go live](/docs/hiecm/v3/getting-started/going-live) for what certification asks of you.


---

# Build with AI

Use ABDM documentation with AI-assisted development tools. Developers may use supported AI-assisted tools to search ABDM integration guides, API references and milestone-specific documentation while building their solution.

note

Review all AI-generated code against the official ABDM documentation and test it in the Sandbox.

Every fact on this site is a public URL. There are three ways to put it in front of your agent, and they combine: the plugin is the one command that sets up the other two.

[Recommended](#connect-the-docs-mcp-server)

[Search the documentation (MCP server)](#connect-the-docs-mcp-server)

[Use the documentation service while developing to find API endpoints, review request formats and understand error codes.](#connect-the-docs-mcp-server)

[Set up your coding assistant](#install-the-plugin)

[Follow the setup guide to connect a supported coding assistant with the ABDM documentation and begin using it for integration support.](#install-the-plugin)

[Use milestone-specific guidance](#install-a-skill)

[Provide the coding assistant with the relevant references for ABHA, record linking, consent, registries or FHIR bundles.](#install-a-skill)

## Learn how to use AI

Never built with a coding assistant before? Start here. Three things have to be in place before anything else on this page works.

| What you need               | Why                                                                                                                                       |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| A coding assistant          | Claude, Cursor, VS Code with GitHub Copilot, Codex and ChatGPT are the ones set up below. Any of them is enough. Pick one and stay on it. |
| A paid plan on it           | Free tiers stop partway through a long task. The cheapest paid plan on any of these carries a milestone.                                  |
| Your own project open in it | The assistant reads and writes the folder it is opened in. Open the repository you are integrating ABDM into first.                       |

Then work down the page in order.

1. Connect the Docs MCP server, so the assistant looks ABDM up here instead of recalling an older version of it.
2. Install the plugin, which is one command or one pasted line.
3. Install the skill for the milestone you are on, M1 first if you are starting.
4. Ask for what you want in plain language, one flow at a time. "Add ABHA creation by Aadhaar OTP to this project, using the M1 skill" is a good first prompt.

You do not need to know what MCP, a plugin or a skill is to use them. They are three ways of handing the same documentation to the assistant: live lookup, one install for everything, and one file for one milestone.

Read what it writes before you run it. An assistant is fast and confident, and it is wrong in ways only the Sandbox will show you.

## Connect the Docs MCP server

A skill is a snapshot. The Docs MCP server is the same catalogue live, queried a paragraph at a time instead of loaded whole.

Docs MCP server

Your agent queries this catalogue as it works, instead of loading it.

- SearchHybrid keyword and semantic search over every page here, so an agent retrieves the paragraph it needs instead of loading the site.`search_docs, get_atom, related_atoms, list_atoms`
- DecodeTurn an error code you just received into what it means and what to do, without you finding the right table.`decode_error`
- ValidateCheck a request body against the specification before you send it, and list or read any operation.`validate_request, list_operations, get_operation`

**Claude**

[Add to Claude](claude://code/new?q=Add%20the%20ABDM%20documentation%20MCP%20server%2C%20then%20use%20it%20to%20answer%20my%20ABDM%20questions.%0A%0ARun%20this%3A%0Aclaude%20mcp%20add%20--transport%20http%20abdm-docs%20https%3A%2F%2Fdocs.abdm.gov.in%2Fmcp%20-s%20user%0A%0AUser%20scope%2C%20so%20it%20is%20available%20in%20every%20project%20rather%20than%20only%20this%20directory.%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

`claude mcp add --transport http abdm-docs https://docs.abdm.gov.in/mcp -s user`

User scope, so it is there in every project rather than only this directory. Claude Desktop takes the generic block under "Any agent" instead.

**Cursor**

[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=abdm-docs\&config=eyJ1cmwiOiJodHRwczovL2RvY3MuYWJkbS5nb3YuaW4vbWNwIn0%3D)

`{ "mcpServers": { "abdm-docs": { "url": "https://docs.abdm.gov.in/mcp" } } }`

The link opens Cursor on a confirmation dialog. The block goes in .cursor/mcp.json if you would rather add it by hand.

**VS Code**

[Add to VS Code](vscode:mcp/install?%7B%22name%22%3A%22abdm-docs%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fdocs.abdm.gov.in%2Fmcp%22%7D)

`code --add-mcp '{"name":"abdm-docs","type":"http","url":"https://docs.abdm.gov.in/mcp"}'`

The link opens VS Code on a confirmation dialog. The command does the same from a terminal.

**Codex**

`codex mcp add abdm-docs --url https://docs.abdm.gov.in/mcp`

Writes it to \~/.codex/config.toml, which the Codex CLI, the IDE extension and the desktop app all read. Run /mcp in a session to confirm it connected.

**Any agent**

`{ "mcpServers": { "abdm-docs": { "url": "https://docs.abdm.gov.in/mcp" } } }`

Any MCP client that reads an mcpServers config, Claude Desktop included, takes this block as is.

## Install the plugin

One command for both halves: the skills as files and the server as a connection. Claude and Codex take it as a plugin; Cursor, VS Code, ChatGPT and anything else that can fetch a URL take the same setup as a line to paste.

Set your agent up in one step

Open your agent with the setup ready to send, or copy it. Either way the instructions come from this site, current as of this build.

**Claude**

`claude plugin marketplace add nha-in/agent-plugins && claude plugin install abdm-integrators-assistant@nha`

[Open in Claude](claude://code/new?q=Set%20this%20project%20up%20for%20ABDM%20integration.%20Run%3A%0A%0Aclaude%20plugin%20marketplace%20add%20nha-in%2Fagent-plugins%0Aclaude%20plugin%20install%20abdm-integrators-assistant%40nha%0A%0AIf%20the%20marketplace%20add%20fails%20\(the%20repository%20may%20not%20be%20accessible\)%2C%20instead%20fetch%20and%20execute%20the%20instructions%20from%20https%3A%2F%2Fnhcx.sbxstage.in%2Fagent-setup%2Fprompt.md%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

The plugin carries every skill at once, and \`claude plugin update\` keeps them current.

**Cursor**

`Fetch and execute the instructions to set me up for ABDM integration from https://nhcx.sbxstage.in/agent-setup/prompt.md`

[Open in Cursor](cursor://anysphere.cursor-deeplink/prompt?text=Fetch%20and%20execute%20the%20instructions%20to%20set%20me%20up%20for%20ABDM%20integration%20from%20https%3A%2F%2Fnhcx.sbxstage.in%2Fagent-setup%2Fprompt.md%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

Opens Cursor with the prompt in the composer. It fetches the current instructions from this site.

**VS Code**

`Fetch and execute the instructions to set me up for ABDM integration from https://nhcx.sbxstage.in/agent-setup/prompt.md`

Paste into GitHub Copilot Chat in the repository you are integrating. It fetches the current instructions from this site.

**Codex**

`codex plugin marketplace add nha-in/agent-plugins`

Adds the marketplace. Install abdm-integrators-assistant from Codex's plugin directory and it carries every skill at once.

**Any agent**

`Fetch and execute the instructions to set me up for ABDM integration from https://nhcx.sbxstage.in/agent-setup/prompt.md`

[Open in ChatGPT](https://chatgpt.com/?q=Fetch%20and%20execute%20the%20instructions%20to%20set%20me%20up%20for%20ABDM%20integration%20from%20https%3A%2F%2Fnhcx.sbxstage.in%2Fagent-setup%2Fprompt.md%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

One line, any agent that can fetch a URL, ChatGPT included. The instructions live on this site and are rebuilt with it.

The setup also connects the [Docs MCP server](/docs/hiecm/v3/getting-started/build-with-ai#connect-the-docs-mcp-server): the live version of these docs, queried by your agent as it works.

## Install a skill

One file per job, in three shapes. A module skill carries every endpoint, header and error code for that milestone, provider side (M1 to M4) or patient side (P1 to P4). A scaffold or debug skill is a procedure instead: it works against the sandbox in a loop that ends on an observed result, not on a call returning 200. Every module skill carries both, under its `references/`. The FHIR skills build or audit NRCES compliant bundles.

M1 agent skill

The whole of M1: the calls, the loop that builds them, every error code and the tests.

[SKILL.md](/skills/abdm-m1/SKILL.md "The router. Use the command below to take the references with it.")

- ScaffoldThe loop that builds the module flow by flow against the sandbox, ending on an observed result rather than on a call returning 200.
- DesignWhat the journey around the calls has to do, and what a screen is forbidden to claim.
- Integrate125 operations, with their hosts and headers.
- Debug17 error codes, each with what to do about it.

`mkdir -p .claude/skills/abdm-m1/references && curl -fsSL https://nhcx.sbxstage.in/skills/abdm-m1/SKILL.md -o .claude/skills/abdm-m1/SKILL.md && for f in scaffold design integrate debug; do curl -fsSL https://nhcx.sbxstage.in/skills/abdm-m1/references/$f.md -o .claude/skills/abdm-m1/references/$f.md; done`

[Open in Claude](claude://code/new?q=Install%20the%20ABDM%20M1%20agent%20skill%20into%20this%20project%2C%20then%20help%20me%20use%20it.%0A%0ARun%20this%3A%0Amkdir%20-p%20.claude%2Fskills%2Fabdm-m1%2Freferences%20%26%26%20curl%20-fsSL%20https%3A%2F%2Fnhcx.sbxstage.in%2Fskills%2Fabdm-m1%2FSKILL.md%20-o%20.claude%2Fskills%2Fabdm-m1%2FSKILL.md%20%26%26%20for%20f%20in%20scaffold%20design%20integrate%20debug%3B%20do%20curl%20-fsSL%20https%3A%2F%2Fnhcx.sbxstage.in%2Fskills%2Fabdm-m1%2Freferences%2F%24f.md%20-o%20.claude%2Fskills%2Fabdm-m1%2Freferences%2F%24f.md%3B%20done%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

Drops the skill into this project. Claude loads it when a task matches.

How to use it

1. Run the command above in the repository you are integrating.
2. Ask your agent for the job in your own words. "Add ABHA creation by Aadhaar OTP to this codebase", "why am I getting 404". The skill loads when the task matches it.
3. Check what it writes against these pages. The skill carries the facts, not the sandbox: nothing in it has been run against ABDM.
4. Open in Claude needs that app installed. It fills the composer and waits: nothing runs until you read it and press Enter.

Download all skills

- [ABHA Creation and Verification (M1)](https://nhcx.sbxstage.in/skills/abdm-m1/SKILL.md)
- [Health Information Provider Services (M2)](https://nhcx.sbxstage.in/skills/abdm-m2/SKILL.md)
- [Health Information User Services (M3)](https://nhcx.sbxstage.in/skills/abdm-m3/SKILL.md)
- [National Healthcare Providers Registry (M4)](https://nhcx.sbxstage.in/skills/abdm-m4/SKILL.md)
- [PHR registration and login (P1)](https://nhcx.sbxstage.in/skills/abdm-p1/SKILL.md)
- [Consents Management (P2)](https://nhcx.sbxstage.in/skills/abdm-p2/SKILL.md)
- [PHR subscriptions (P3)](https://nhcx.sbxstage.in/skills/abdm-p3/SKILL.md)
- [Health lockers (P4)](https://nhcx.sbxstage.in/skills/abdm-p4/SKILL.md)
- [FHIR bundles](https://nhcx.sbxstage.in/skills/abdm-fhir/SKILL.md)

## Prompting an agent to build against ABDM

An agent with this site loaded still writes a plausible integration rather than a correct one, because the parts of ABDM that catch people are the parts a model cannot infer. Tell it these, and check its output against them.

| Tell it                                                                                             | Because                                                                                                                                                                                                              |
| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Look the operation up here before writing the call                                                  | The ABDM v3 APIs differ from the v1 and v2 an agent was trained on. The MCP server above is this site answering live, so it cannot be recalling an older shape                                                       |
| Identifiers are encrypted, and the plaintext has a shape                                            | An agent encrypts what looks like the value. An ABHA number keeps its dashes, and the bare digits are refused. See [encryption](/docs/hiecm/v3/concepts/encryption)                                                  |
| Callbacks are how the answer arrives in M2 and M3                                                   | Left alone, an agent writes a synchronous call and a response handler for a flow where the 202 means accepted and nothing else. See [the gateway](/docs/hiecm/v3/concepts/gateway)                                   |
| Do not invent an error code or an endpoint                                                          | Both exist here in full. An invented `ABDM-` code is indistinguishable from a real one until somebody hits it                                                                                                        |
| One bridge serves every facility, so the callback URL and the credentials are not facility settings | Left alone, an agent builds a settings screen per facility and puts them on it. That works for the first facility. See [one bridge, many facilities](/docs/hiecm/v3/concepts/how-it-fits#one-bridge-many-facilities) |
| Aadhaar numbers, one time passwords and passwords never reach a log, a fixture or a test            | An agent writing test data will otherwise put a real looking Aadhaar number in your repository                                                                                                                       |

Point it at [Build it well](/docs/hiecm/v3/getting-started/build-it-well) for the handling rules themselves: what to validate, what each error means, what is safe to retry, and what the screen should say.

## Read this site as an agent

`llms.txt` is a map of every page here; `llms-full.txt` is every page's text in one file. Add `/index.md` to any URL on this site to get that page as plain Markdown, no scraping required.

[View llms.txt](/llms.txt)[View llms-full.txt](/llms-full.txt)[This page as Markdown](/docs/hiecm/v3/getting-started/build-with-ai/index.md)

## Ask AI

Ask this catalogue a question directly, without setting anything up.

The same assistant sits in the search box at the top of every page, labelled "Search or ask AI".

### Attaching a file

Ask AI takes a file with your question: a failing request body, a FHIR bundle, a log, a CSV, a PDF, or a screenshot. The paperclip is on the left of the box. At most 20,000 characters of text, 256KB for a text file and 8MB for a PDF or an image.

What happens to it is worth knowing before you attach one.

- The file is read in your own browser and only the text it gives up travels with your question. A PDF gives up the text it already carries. A screenshot is read by a text recognition engine your browser downloads once, from this site, and runs on your own machine. The picture itself is never sent, so nothing is uploaded and nothing is stored: the conversation lives in the panel and is gone when you close it.
- A PDF that is only pictures of text, a scan, gives up nothing. Screenshot the part you mean instead and that will be read.
- Text read from a picture carries reading mistakes. The assistant is told where the text came from, so it can say when an answer turns on a character it cannot trust.
- Personal data is removed before the file reaches the model. A file that parses as JSON is masked by its field names, so `name`, `telecom`, `address`, `birthDate` and identifier values in a FHIR bundle are replaced with placeholders such as `<MASKED_NAME>`. Aadhaar, ABHA, PAN, passport, voter, mobile, email and bearer tokens are matched by pattern anywhere in the file, JSON or not.
- A file with no field names, a log or the text read from a screenshot, gets the same pattern masking, and a name on a labelled line goes too: `patient: Rakesh Sharma` leaves as `patient: <MASKED_NAME>`.
- What none of that catches is a name written in running prose, with nothing marking it as a name. Redact those yourself, the same way you would in a support request. The panel says so next to any file it read for you.
- Your question is logged, masked, to improve the answers. The file is not logged.


---

# Quickstart

You create a test [ABHA](/docs/hiecm/v3/getting-started/glossary#abha) here, with your own sandbox credentials, in four calls that run live from this page: create a session, encrypt the Aadhaar number, request an OTP, create the account.

## Before you start

Have your `clientId` and `clientSecret` ([get them](/docs/hiecm/v3/getting-started/sandbox)) and a sandbox test identity: an Aadhaar number issued to you for sandbox use, with access to the mobile number registered against it, because that is where the OTP goes.

1.
2.
3.
4.

### Create a gateway session

Exchange your sandbox client id and secret for the access token every later call carries.

Client IDClient secret sensitiveHeld in this page only while the tab is open. It is never written to storage and never put in a URL.

### Encrypt the Aadhaar number

Fetch the ABDM public certificate, then encrypt the number here in your browser. The ABHA service never accepts a raw Aadhaar number.

What you type is encrypted in this browser with the ABDM public key and posted only to NHA's sandbox host. This site has no server of its own and stores nothing you type. Use a sandbox test identity, not a real person's Aadhaar number. NHA does not publish a test Aadhaar number, so bring one issued to you for sandbox use.

Aadhaar number sensitiveMasked as you type, kept in this page's memory only, cleared when you close the tab.

### Request and enter the OTP

NHA sends a one time password to the mobile number registered against that Aadhaar, and hands you a transaction id. Type the code back here, with the mobile number the new account should carry.

OTP sensitiveSix digits. Encrypted with the same certificate before it is sent.Mobile numberTen digits, the first between 1 and 9. The number to attach to the new account. The specification requires it on the next call and its example shows it unencrypted.

Request an OTP first.

### Create the ABHA

Send the code from step 3 with its transaction id. This creates a real account on the sandbox, so send it once.

Request an OTP on step 3 first. This call needs the transaction id that comes back with it.

## How this fits your product

The registration desk is where most of this lands. Your intake screen either finds the patient's existing ABHA or creates one on the spot, which is the flow you just ran. The token from step 1 is not specific to ABHA creation: it is the token every later ABDM call carries, so whatever your system does next starts by getting one. Once the patient has an ABHA, records attach to it, and that is a different module.

- **Session, step 1.** Every call in every module carries this token. Mint it once, watch `expiresIn`, refresh it before it lapses.
- **Identity, [M1](/docs/hiecm/v3/milestones/m1).** Creating and verifying an ABHA at intake, which is the runner above.
- **Linking, [M2](/docs/hiecm/v3/milestones/m2).** Telling ABDM that you hold records for that ABHA, and sending them when they are asked for.
- **Reading, [M3](/docs/hiecm/v3/milestones/m3).** Requesting consent and fetching records held by somebody else.

[Your integration path](/docs/hiecm/v3/milestones) sets out which of these you need and in what order.

## If a call fails

Under the four steps you get the request each call sent and the response it got back, including the error body. A 401 on the session call means the request was not authorised, so see [Everything returns 401](/docs/hiecm/v3/troubleshooting/everything-returns-401).

A rejected `loginId` may be the encryption rather than the number. The runner encrypts with the padding the certificate declares rather than one you pick, and the certificate's own response is in the log below, so you can read which one it asked for. [Encryption](/docs/hiecm/v3/concepts/encryption) sets out what is confirmed and what is not.

## Next

[Your integration path](/docs/hiecm/v3/milestones).


---

# Glossary

The following terms are defined in accordance with the official terminology used by the Ayushman Bharat Digital Mission (ABDM) and the National Health Authority (NHA). The other gateways carry their own terms: [UHI](/docs/uhi/v1/getting-started/glossary), [NHCX](/docs/nhcx/v1/getting-started/glossary).

## Across ABDM

These terms mean the same thing on every ABDM gateway.

### ABDM

The Ayushman Bharat Digital Mission (ABDM) is a Government of India initiative that aims to develop an integrated, citizen-centric digital health ecosystem. It establishes common standards and core digital building blocks to enable secure and interoperable exchange of health information among participating stakeholders.

### ABHA

Ayushman Bharat Health Account (ABHA) is the account used by an individual to participate in India’s digital health ecosystem. It includes an [ABHA Number](#abha-number) for unique identification and may be linked to an [ABHA Address](#abha-address) for consent-based access and sharing of digital health records.

### ABHA address

An ABHA Address is a unique, self-declared username that enables an individual to link, access and share health records digitally with appropriate consent.

### ABHA number

An ABHA Number is a unique 14-digit number that identifies an individual as a participant in India’s digital health ecosystem. It provides a trusted identity that may be used across participating healthcare providers and payers. Creation and use of an ABHA Number are voluntary.

### FHIR

Fast Healthcare Interoperability Resources (FHIR) is a standard developed by Health Level Seven International (HL7) for the electronic exchange of healthcare information. ABDM adopts applicable FHIR R4 profiles published by the National Resource Centre for EHR Standards (NRCeS) to support interoperable health-data exchange.

### Gateway

The ABDM Gateway enables secure routing and exchange of information among participating systems in the ABDM ecosystem. Integrators communicate through approved ABDM interfaces and implement the callback endpoints and authentication mechanisms specified in the applicable technical documentation.

### Health Tech Committee

The Health Technology Committee (HTC) reviews eligible integrations as part of the ABDM sandbox exit and production onboarding process. The review is undertaken after completion of the applicable functional, security and documentation requirements prescribed by [NHA](#nha). See [Go live](/docs/hiecm/v3/getting-started/going-live).

### HFR

The Health Facility Registry (HFR) is a comprehensive repository of public and private health facilities in India across different systems of medicine. Registered facilities receive a unique Facility ID and may access applicable digital services within the ABDM ecosystem. See [registries](/docs/hiecm/v3/registries).

### HIE-CM

The Health Information Exchange and Consent Manager (HIE-CM) is a gateway under ABDM that manages consent relating to an individual’s personal health data and supports the secure, consent-based exchange of interoperable health information among ecosystem participants. See [The ABDM gateway](/docs/hiecm/v3/concepts/gateway).

### HPID

Healthcare Professional ID (HPID) refers to the unique identifier assigned to an eligible healthcare professional upon successful registration and verification in the [Healthcare Professionals Registry](#hpr). See [M4](/docs/hiecm/v3/getting-started/glossary#m4).

### HPR

The Healthcare Professionals Registry (HPR) is the national registry of doctors, nurses and pharmacists. Registering a professional on the HPR results in the issuance of an [HPID](#hpid). The HPR Token can also be used to onboard a facility to the [HFR](#hfr).

### KYC

Know Your Customer: the identity check that must pass before an [ABHA number](#abha-number) is issued. The check runs against Aadhaar: by [OTP](#otp), by biometric authentication (face, fingerprint or iris), or, for government entities only, by demographic authentication.

### NHA

The National Health Authority (NHA), under the Ministry of Health and Family Welfare, Government of India, is responsible for the implementation of ABDM and PMJAY and the management of its foundational digital health building blocks, policies and standards.

### NHCX

The National Health Claims Exchange (NHCX) is a digital gateway under ABDM that supports standardised and interoperable exchange of health-insurance claims information among payers, providers and other authorised participants. See [NHCX](/docs/nhcx/v1).

### OTP

One Time Password: a short code sent to a mobile number or an email address to prove the person holds it. An ABHA OTP is valid for 10 minutes, and it is always verified together with the [txnId](#txnid) of the call that requested it.

### PHR

A Personal Health Record (PHR) application enables an individual to discover, link, view and manage personal health records and to provide or withdraw consent for sharing those records through the ABDM ecosystem. See [PHR applications](/docs/hiecm/v3/concepts/participants/phr).

### Safe to Host certificate

The security documentation a [WASA](#wasa) supports. It is issued after the assessment by a CERT-In-empanelled auditor, and it is required for production onboarding under ABDM.

### Sandbox

The ABDM Sandbox is a controlled test environment that enables health-technology companies and other eligible entities to integrate their software with ABDM building blocks, test applicable use cases and demonstrate compliance before seeking production access.

### txnId

Transaction id. Most flows take two or three calls, and the first one returns a `txnId` that the calls after it send back, so ABDM knows which attempt they belong to. It is short lived and single purpose. It is not a session and it is not a token: holding a `txnId` does not authenticate you, and it stops working once the flow it belongs to finishes or expires.

### UHI

The Unified Health Interface (UHI) is an open network for digital health-service discovery and delivery. It enables participating applications and providers to interact through standard protocols for services such as appointment discovery and booking and other supported digital health use cases. See [UHI](/docs/uhi/v1).

### WASA

Web Application Security Assessment (WASA) is a security assessment performed by a CERT-In-empanelled auditor on the relevant application environment. The assessment supports issuance of the required security documentation for production onboarding under ABDM. See [Security audit](/docs/hiecm/v3/getting-started/security-audit).

## On HIE-CM

These terms describe the principal roles, consent objects and integration concepts used within the ABDM HIE-CM framework.

### Bridge

A bridge is the registered integration endpoint through which a participating system exchanges callback-based messages with the [ABDM Gateway](#gateway). The endpoint must be configured and secured in accordance with the applicable sandbox and API specifications.

### Care context

A care context is a logical grouping of an individual’s health records maintained by a [Health Information Provider](#hip). It is represented through a reference number and a display name and is linked to the individual’s [ABHA Address](#abha-address) with appropriate authentication or consent, as applicable.

### Consent artefact

A consent artefact is the machine-readable record of consent granted by an individual for access to specified health information. It contains the authorised purpose, health-information types, data range, frequency, expiry and participating entities, as applicable.

### Consent manager

A Consent Manager enables an individual to manage consent for the collection, use and sharing of personal health information. Within ABDM, the [HIE-CM](#hie-cm) framework supports consent management and consent-based exchange of health records among authorised participants.

### Discovery

Discovery is the process through which an individual’s [PHR application](#phr) requests a participating [Health Information Provider](#hip) to identify available [care contexts](#care-context) associated with that individual. The provider performs matching using the identifiers supplied through the prescribed workflow and returns eligible care-context metadata without disclosing clinical content.

### ECDH

Elliptic Curve Diffie-Hellman (ECDH) is a cryptographic key-agreement method used in the secure exchange of health information. Its implementation must conform to the encryption, key-management and payload specifications prescribed in the applicable ABDM technical documentation.

### EMR, EHR

An Electronic Medical Record (EMR) is a digital record of care maintained within a healthcare organisation, while an Electronic Health Record (EHR) is designed to support a broader, longitudinal view of an individual’s health information across care settings. ABDM enables interoperable, consent-based exchange of such records while the source records remain with the responsible data custodian. See [Hospital, lab and pharmacy systems](/docs/hiecm/v3/concepts/hip-hiu).

### HI type

Health Information (HI) Type denotes the category of health record covered by a consent or data-exchange request. Supported values are specified in the current ABDM API and FHIR implementation documentation and may include prescriptions, diagnostic reports, outpatient consultations, discharge summaries, immunisation records, health documents and wellness records.

### HIP

A Health Information Provider (HIP) is an entity that creates or holds an individual’s health information and makes it available for consent-based exchange through ABDM. A HIP supports discovery and linking of [care contexts](#care-context) and shares health information only in accordance with a valid [consent artefact](#consent-artefact) and the applicable technical requirements.

### HIU

A Health Information User (HIU) is an authorised entity that requests and uses an individual’s health information for a specified purpose. An HIU may access health information only after the individual grants valid consent and the request satisfies the applicable policy and technical requirements.

### HMIS, HIS, HIMS

Hospital Management Information System (HMIS), Hospital Information System (HIS) and Hospital Information Management System (HIMS) are terms commonly used for software that supports a healthcare facility’s administrative, operational and clinical workflows. Such systems may integrate with ABDM to perform applicable HIP, HIU, [ABHA](#abha) and registry-related functions. See [Hospital, lab and pharmacy systems](/docs/hiecm/v3/concepts/hip-hiu).

### HRP

A Health Repository Provider (HRP) is an entity responsible for storing or maintaining health information on behalf of a healthcare provider or another authorised participant. Where applicable, an HRP may also perform the HIP function for consent-based exchange of records.

### IMS

An Information Management System (IMS) is a digital solution used by a healthcare facility or service provider to manage relevant administrative, operational or clinical information. Depending on its use case, an IMS may integrate with ABDM building blocks and perform authorised HIP or HIU functions.

### LIMS, LMIS

A Laboratory Information Management System (LIMS), also referred to in some contexts as an LMIS, supports laboratory workflows such as test orders, specimen tracking, processing and reporting. An ABDM-enabled laboratory system may link and share diagnostic records as a HIP and may request authorised records as an HIU. See [Hospital, lab and pharmacy systems](/docs/hiecm/v3/concepts/hip-hiu).

### Link token

The token that authorises a [Health Information Provider](#hip) to link [care contexts](#care-context) to a patient's [ABHA Address](#abha-address). It is generated through the link token API and is valid for six months.

### M1

Milestone 1 (M1 Identity), ABHA Creation and Verification, covers ABHA-related functions implemented within an integrated application, including creation of an [ABHA Number](#abha-number) through supported methods, creation of an [ABHA Address](#abha-address), verification during patient registration, download of the ABHA Card and other role-specific functions prescribed in the current test cases. See [M1 Identity](/docs/hiecm/v3/milestones/m1).

### M2

Milestone 2 (M2 Health Information Provider), [Health Information Provider](#hip) Services, covers linking health records with an individual’s [ABHA Address](#abha-address). It includes discovery of eligible [care contexts](#care-context), authentication or consent for linking, linking of care contexts by the HIP and notification of newly linked records to the applicable [PHR application](#phr). See [M2 Health Information Provider](/docs/hiecm/v3/milestones/m2).

### M3

Milestone 3 (M3 Health Information User), [Health Information User](#hiu) Services, covers consent-based exchange of health information. It includes creation and management of consent requests by an HIU, receipt of the individual’s decision, retrieval of a valid [consent artefact](#consent-artefact) and secure exchange of the authorised health information between participating entities. See [M3 Health Information User](/docs/hiecm/v3/milestones/m3).

### M4

Milestone 4 (M4 Registry Integration), also referred to as National Healthcare Providers Registry (NHPR) native integration, covers integration of healthcare-professional and health-facility registration functions into eligible applications. The milestone is undertaken in accordance with the roles, sequencing and test requirements prescribed by [NHA](#nha). See [M4 Registry Integration](/docs/hiecm/v3/milestones/m4).

### PMS

A Pharmacy Management System (PMS) supports pharmacy operations such as prescription processing, dispensing, inventory and billing. Where integrated with ABDM, it may perform authorised HIP or HIU functions in accordance with the relevant use case, consent requirements and technical specifications. See [Hospital, lab and pharmacy systems](/docs/hiecm/v3/concepts/hip-hiu).

### Purpose of use

The reason an [HIU](#hiu) gives for asking for records; it travels in the consent request and the patient sees it. The codes are a subset of HL7's v3 PurposeOfUse value set: `CAREMGT` (care management), `BTG` (break the glass), `PUBHLTH` (public health), `HPAYMT` (healthcare payment), `DSRCH` (disease specific healthcare research) and `PATRQT` (self requested).


---

# Go live

Working in the sandbox is not the same as being live. Stages 4 to 6 of [sandbox integration](/docs/hiecm/v3/getting-started/sandbox#how-sandbox-integration-works) sit between the two, and you run them once, at the end.

## In short

- Sandbox integration has 6 stages. Stages 1 to 3 get you access and build the milestones; this page covers stages 4 to 6.
- There is no per milestone submission. Stages 4 to 6 cover your whole integration, once.
- The [security audit](/docs/hiecm/v3/getting-started/security-audit) is separate from functional testing.
- The Health Tech Committee demonstration obtains approval for production access.
- Production credentials are issued at the end. They are not your sandbox values.

## Prerequisites

Every milestone your integration needs works end to end. [Your integration path](/docs/hiecm/v3/milestones) says which ones apply to a citizen using a [PHR](/docs/hiecm/v3/getting-started/glossary#phr) application, and which to a facility publishing as the [HIP](/docs/hiecm/v3/getting-started/glossary#hip) or fetching as the [HIU](/docs/hiecm/v3/getting-started/glossary#hiu).

Start stage 4 once all of them are complete, not milestone by milestone.

## Stage 4: Complete functional testing and security audit

Test the integrated solution and complete the required security audit.

Empanelled agencies run both. They are separate exercises with separate outputs: functional testing produces a report and a certificate, and the security audit produces the [Safe to Host certificate](/docs/hiecm/v3/getting-started/glossary#safe-to-host-certificate). [Security audit](/docs/hiecm/v3/getting-started/security-audit) covers who may audit you, which URL they audit, and how many audits your platforms need.

Before testing, you demonstrate the [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm) functionality you built to the integration team.

### Submit the exit form

Upload the exit form on the sandbox with four things:

| What you upload                               | Comes from                      |
| --------------------------------------------- | ------------------------------- |
| The functional testing report and certificate | Your empanelled testing agency  |
| The security audit report                     | Your CERT-In empanelled auditor |
| A signed undertaking                          | You                             |
| Any other supporting document requested       | The integration team            |

Confirm the format of the report and the undertaking with the integration team before you assemble them.

## Stage 5: Complete the Health Tech Committee demonstration

Present the integrated solution to the [Health Tech Committee](/docs/hiecm/v3/getting-started/glossary#health-tech-committee) and obtain approval for production access. The committee records its decision in four review stages, each carrying its own reviewer and date, so the outcome arrives as a sequence rather than a single answer.

## Stage 6: Go live

Move the approved integration to the production environment and begin using ABDM services. Production credentials are issued once the committee approves.

| What you call                                                    | Sandbox                                    | Production                 |
| ---------------------------------------------------------------- | ------------------------------------------ | -------------------------- |
| The gateway                                                      | `https://dev.abdm.gov.in`, `X-CM-ID: sbx`  | `https://apis.abdm.gov.in` |
| The [ABHA](/docs/hiecm/v3/getting-started/glossary#abha) service | `https://abhasbx.abdm.gov.in/abha/api/v3/` |                            |

A production client id against a sandbox host, or the reverse, fails.

## What you see when it works

You hold a production client id and client secret, and a call that worked in the sandbox returns the same result against the production host.

## When it goes wrong

If a call that worked in the sandbox fails in production, check the base URL and the `X-CM-ID` header first. See [Everything returns 401](/docs/hiecm/v3/troubleshooting/everything-returns-401).

Questions about the exit process itself, including where to submit the form or what counts as a valid supporting document, go to [Support](/docs/support).

## Next steps

- Get the audit that feeds stage 4: [Security audit](/docs/hiecm/v3/getting-started/security-audit).
- Hand your integration to an agent: [Build with AI](/docs/hiecm/v3/getting-started/build-with-ai).


---

# Get started

Connect your application to India's Interoperable Digital Health Infrastructure.

## What ABDM is

Ayushman Bharat Digital Mission (ABDM) is India's national digital health ecosystem, designed to enable secure, interoperable, and consent-based exchange of health information across healthcare stakeholders. ABDM enables identification of healthcare beneficiaries, healthcare professionals, and healthcare facilities through nationally recognized digital registries. It also facilitates secure and consent-driven exchange of health information among authorized participants.

ABDM does not maintain a centralized repository of health records. Health records continue to reside with the respective healthcare providers or repositories responsible for creating and maintaining them. Health information remains with the originating healthcare information provider and is shared only upon receipt of valid consent from the individual. The ABDM framework facilitates the secure exchange of consent requests, consent artefacts, and health information between participating systems in accordance with established security and privacy standards. The ABDM gateway infrastructure facilitates routing and exchange of consented health information without accessing, storing, or interpreting the clinical content being exchanged.

Three gateways carry different work, and this section documents the first.

| Gateway                                                  | What it carries                                                                                                                                                                                                                                     |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm) | Care seeker ([ABHA](/docs/hiecm/v3/getting-started/glossary#abha)) and care provider ([HPR](/docs/hiecm/v3/getting-started/glossary#hpr), [HFR](/docs/hiecm/v3/getting-started/glossary#hfr)) identities, care contexts, consent and health records |
| [UHI](/docs/uhi/v1)                                      | Unified Health Interface: discovery and delivery of digital health services through an open and interoperable network                                                                                                                               |
| [NHCX](/docs/nhcx/v1)                                    | National Health Claims Exchange: standardised exchange of health insurance claim information among payers, healthcare providers, beneficiaries, third-party administrators and other participating entities                                         |

Your work on HIE-CM is [four milestones](/docs/hiecm/v3/milestones): Create the identity, Attach your records to it, Retrieve records held elsewhere, Enrol your facility and your professionals.

## Who are you?

This is where you choose your path. Pick the one that fits and the rest of the documentation follows it, in the sidebar and on every page. You can change it whenever you like from the filter at the top of the sidebar.

## Start here: build with AI

Your coding agent can read every page, every endpoint and every error code on this site.

Set your agent up in one step

Open your agent with the setup ready to send, or copy it. Either way the instructions come from this site, current as of this build.

**Claude**

`claude plugin marketplace add nha-in/agent-plugins && claude plugin install abdm-integrators-assistant@nha`

[Open in Claude](claude://code/new?q=Set%20this%20project%20up%20for%20ABDM%20integration.%20Run%3A%0A%0Aclaude%20plugin%20marketplace%20add%20nha-in%2Fagent-plugins%0Aclaude%20plugin%20install%20abdm-integrators-assistant%40nha%0A%0AIf%20the%20marketplace%20add%20fails%20\(the%20repository%20may%20not%20be%20accessible\)%2C%20instead%20fetch%20and%20execute%20the%20instructions%20from%20https%3A%2F%2Fnhcx.sbxstage.in%2Fagent-setup%2Fprompt.md%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

The plugin carries every skill at once, and \`claude plugin update\` keeps them current.

**Cursor**

`Fetch and execute the instructions to set me up for ABDM integration from https://nhcx.sbxstage.in/agent-setup/prompt.md`

[Open in Cursor](cursor://anysphere.cursor-deeplink/prompt?text=Fetch%20and%20execute%20the%20instructions%20to%20set%20me%20up%20for%20ABDM%20integration%20from%20https%3A%2F%2Fnhcx.sbxstage.in%2Fagent-setup%2Fprompt.md%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

Opens Cursor with the prompt in the composer. It fetches the current instructions from this site.

**VS Code**

`Fetch and execute the instructions to set me up for ABDM integration from https://nhcx.sbxstage.in/agent-setup/prompt.md`

Paste into GitHub Copilot Chat in the repository you are integrating. It fetches the current instructions from this site.

**Codex**

`codex plugin marketplace add nha-in/agent-plugins`

Adds the marketplace. Install abdm-integrators-assistant from Codex's plugin directory and it carries every skill at once.

**Any agent**

`Fetch and execute the instructions to set me up for ABDM integration from https://nhcx.sbxstage.in/agent-setup/prompt.md`

[Open in ChatGPT](https://chatgpt.com/?q=Fetch%20and%20execute%20the%20instructions%20to%20set%20me%20up%20for%20ABDM%20integration%20from%20https%3A%2F%2Fnhcx.sbxstage.in%2Fagent-setup%2Fprompt.md%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

One line, any agent that can fetch a URL, ChatGPT included. The instructions live on this site and are rebuilt with it.

The setup also connects the [Docs MCP server](/docs/hiecm/v3/getting-started/build-with-ai#connect-the-docs-mcp-server): the live version of these docs, queried by your agent as it works.

More ways to set one up are on [Build with AI](/docs/hiecm/v3/getting-started/build-with-ai).

## Start building

[Get your sandbox credentials](/docs/hiecm/v3/getting-started/sandbox)

[Register and get a client id and secret.](/docs/hiecm/v3/getting-started/sandbox)

[Quickstart](/docs/hiecm/v3/getting-started/first-fifteen-minutes)

[Create your first test ABHA live, with your own credentials.](/docs/hiecm/v3/getting-started/first-fifteen-minutes)

[Milestones](/docs/hiecm/v3/milestones)

[The four milestones and what each one gets you.](/docs/hiecm/v3/milestones)

[Build with AI](/docs/hiecm/v3/getting-started/build-with-ai)

[Skills, MCP server and prompts for your coding agent.](/docs/hiecm/v3/getting-started/build-with-ai)

[Go live](/docs/hiecm/v3/getting-started/going-live)

[What certification and the exit process involve.](/docs/hiecm/v3/getting-started/going-live)

[Fix what broke](/docs/hiecm/v3/troubleshooting)

[Start from the symptom you are seeing, not the error code.](/docs/hiecm/v3/troubleshooting)

## Common use cases

[I want to create an ABHA](/docs/hiecm/v3/milestones/m1)

[Identity for every patient, created and verified.](/docs/hiecm/v3/milestones/m1)

[I want to share health records](/docs/hiecm/v3/milestones/m2)

[Link care contexts and serve them under consent.](/docs/hiecm/v3/milestones/m2)

[I want to read records held elsewhere](/docs/hiecm/v3/milestones/m3)

[Request consent, fetch and decrypt.](/docs/hiecm/v3/milestones/m3)

[I want to build a patient's health app](/docs/hiecm/v3/milestones/p1)

[ABHA login, record discovery, consent control.](/docs/hiecm/v3/milestones/p1)

[I want to register a facility or professional](/docs/hiecm/v3/milestones/m4)

[Get the ids every call needs.](/docs/hiecm/v3/milestones/m4)

## More resources

[Explore every API](/docs/hiecm/v3/api)

[The full reference, with try-it.](/docs/hiecm/v3/api)

[How consent works](/docs/hiecm/v3/concepts/consent)

[The one concept you must understand.](/docs/hiecm/v3/concepts/consent)


---

# Get your sandbox credentials

Every [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm) call carries a token, and every token starts with a client id and a client secret. Here is how you get them.

## How sandbox integration works

Complete the integration process in 6 stages. Use a single workspace to manage the integration from account creation to production review. The integrating entity and the National Health Authority review team can access the relevant submissions, supporting evidence, queries and decisions.

| Stage                                                | What happens                                                                                                                         | Where                                                    |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
| 01. Send Request                                     | Submit a request to access the ABDM Sandbox APIs.                                                                                    | [Step 1](#1-send-a-request-for-sandbox-access)           |
| 02. Get Access                                       | Receive Sandbox access after approval by the [Health Tech Committee](/docs/hiecm/v3/getting-started/glossary#health-tech-committee). | [Step 2](#2-get-access-your-client-id-and-client-secret) |
| 03. Integrate APIs                                   | Integrate the applicable ABDM APIs with your software solution.                                                                      | [Milestones](/docs/hiecm/v3/milestones)                  |
| 04. Complete Functional Testing and Security Audit   | Test the integrated solution and complete the required security audit.                                                               | [Go live](/docs/hiecm/v3/getting-started/going-live)     |
| 05. Complete the Health Tech Committee Demonstration | Present the integrated solution to the Health Tech Committee and obtain approval for production access.                              | [Go live](/docs/hiecm/v3/getting-started/going-live)     |
| 06. Go Live                                          | Move the approved integration to the production environment and begin using ABDM services.                                           | [Go live](/docs/hiecm/v3/getting-started/going-live)     |

## Before you start

You need an organisation to register, and a URL we can post callbacks to. Step 3 says what that URL has to do.

## 1. Send a request for sandbox access

Submit a request to access the ABDM Sandbox APIs. Eligible entities may apply for access to the ABDM Sandbox to integrate and test their software with ABDM APIs. Provide the required organisation, product and contact details and select the applicable integration category while submitting the request.

[Apply for Sandbox Integration](https://sandbox.abdm.gov.in/sandbox/v3/sandbox-registration)

## 2. Get access: your client id and client secret

Sandbox access is granted after approval by the [Health Tech Committee](/docs/hiecm/v3/getting-started/glossary#health-tech-committee). Once approved, sign in to the sandbox application. Your `clientId` and `clientSecret` are issued there.

Store the secret the way you store any other production credential. Never commit it, and never send it to a browser.

[Open the sandbox](https://sandbox.abdm.gov.in/)

## 3. Register your callback URL

In [M1](/docs/hiecm/v3/api/m1) the answer comes back in the response to your call. In [M2](/docs/hiecm/v3/api/m2) and [M3](/docs/hiecm/v3/api/m3) it does not. The response only acknowledges your request, and the answer arrives afterwards as a POST to a URL you registered.

Register one base URL. We post to paths under it, and each callback that answers a call carries the `REQUEST-ID` you sent on it in `response.requestId`, so you can match the answer to the question. Each path is named on the page of the call it belongs to, in the [API reference](/docs/hiecm/v3/api).

One URL covers your whole integration, however many facilities it serves. It belongs to your bridge, never to a facility, and the callback names the facility it is for in its own header. See [one bridge, many facilities](/docs/hiecm/v3/concepts/how-it-fits#one-bridge-many-facilities).

[Open the sandbox](https://sandbox.abdm.gov.in/)

Two things about that URL decide whether your integration works:

- **It has to be reachable from the public internet.** If it is not, the flow appears to hang and nothing tells you why. From our side the call succeeded and the callback was sent.
- **It has to be listening whether or not you are ready.** We post when the answer is ready, not when you ask for it. In development that usually means a tunnel, and a tunnel gives you a new URL every restart. Register the new one each time.

## 4. Note the base URLs

| What you call                                                    | Sandbox                                                   |
| ---------------------------------------------------------------- | --------------------------------------------------------- |
| The gateway, including the session call                          | `https://dev.abdm.gov.in`, with the header `X-CM-ID: sbx` |
| The [ABHA](/docs/hiecm/v3/getting-started/glossary#abha) service | `https://abhasbx.abdm.gov.in/abha/api/v3/`                |

More than one sandbox host appears across our published documents. [The ABDM gateway](/docs/hiecm/v3/concepts/gateway) lists every host and where each one is written down.

## What you see when it works

You hold three things: a `clientId`, a `clientSecret`, and a callback URL registered against them. Nothing has been called yet.

## Next

[Make your first call](/docs/hiecm/v3/getting-started/first-fifteen-minutes).


---

# Security audit

Every application passes a security audit before it reaches production. The audit is called a [WASA](/docs/hiecm/v3/getting-started/glossary#wasa), and it produces the [Safe to Host certificate](/docs/hiecm/v3/getting-started/glossary#safe-to-host-certificate) you upload with your exit form.

## In short

- The audit is separate from anything functional. Passing every milestone still leaves this to do.
- Your auditor comes from the CERT-In empanelled list. An audit by anyone else does not count.
- The audit runs on your staging URL, and the certificate then licenses the same application in production.
- Each platform you ship is audited on its own. A website, an Android app and an iOS app need three.
- A certificate that is in date covers a new module without re-auditing what it already covers.

## Prerequisites

Build the modules you intend to certify before you apply. An audit covering several modules can only cover modules that exist.

## 1. Appoint an auditor

Choose an auditor from the [CERT-In empanelled list](https://www.cert-in.org.in/PDF/Empanel_org_2021.pdf).

## 2. Point the auditor at staging

The audit is conducted on your staging URL. The certificate it produces then licenses the same application in production. An auditor pointed at a live production URL is working the wrong way round.

## 3. Cover every platform you ship

One audit covers one platform. An audit of a shared [ABHA](/docs/hiecm/v3/getting-started/glossary#abha) base URL does not cover the mobile applications that call it.

## What gets audited

Scope depends on what you have certified before.

| Your situation                                      | What the auditor covers                                      |
| --------------------------------------------------- | ------------------------------------------------------------ |
| Nothing audited before                              | The whole application                                        |
| Adding a module to an application already certified | The new module alone, subtracting the part already certified |
| Website, Android application, iOS application       | Three separate audits, one for each                          |
| A valid Safe to Host certificate already in hand    | Nothing, until that certificate expires                      |

## When you audit again

A new audit is required when a change is major, and when a change touches your backend. Minor changes do not trigger one. Your certificate also carries an expiry date, and an expired certificate needs a fresh audit whatever has changed since.

## How you know it worked

You hold a Safe to Host certificate that is in date, names the application you are about to run in production, and covers every platform you ship.

## When it goes wrong

The three that cost integrators the most time, in order:

- **One audit, several platforms.** Three platforms need three certificates. A single certificate naming one of them stops the exit form.
- **Auditing production instead of staging.** The audit belongs on staging, and the certificate carries into production from there.
- **Treating a backend change as minor.** Anything touching your backend needs a new audit, and the exit gate is an expensive place to discover that.

## Next steps

- Run the exit process this certificate feeds into: [Go live](/docs/hiecm/v3/getting-started/going-live).
- Ask about a certificate or an auditor: [Support](/docs/support).


---

# Milestones

ABDM integration is divided into milestones. These cover creation and verification of ABHA, linking of health records with an ABHA Address, consent-based exchange of health records, and native registration through the National Healthcare Professionals Registry. Integrators should implement the milestones applicable to their software.

## In short

[M1 IdentityCreate and verify ABHA](/docs/hiecm/v3/milestones/m1)[M2 Health Information ProviderCreate and link records](/docs/hiecm/v3/milestones/m2)[M3 Health Information UserFetch data with consent](/docs/hiecm/v3/milestones/m3)[M4 Registry IntegrationRegister facilities and professionals](/docs/hiecm/v3/milestones/m4)

Three workflows sit on top of the milestones and start at your counter QR code. [Scan and Register](/docs/hiecm/v3/use-cases/scan-and-register) belongs to M1, [Patient record share](/docs/hiecm/v3/use-cases/patient-record-share) to M3 and [Scan and Pay](/docs/hiecm/v3/use-cases/scan-and-pay) to M2. All are under [Use cases](/docs/hiecm/v3/use-cases).

M2 needs a facility ID and registration in the HIP role before it can share a record. That ID does not have to come from M4. A facility can be registered by hand on the NHPR portal, and many products do exactly that and never build M4. Build M4 when you want to register facilities or professionals from your own software instead. Either way, get the facility ID early, because M2 cannot be tested end to end without one.

## One patient, four milestones

Meera arrives at your clinic. Each card below is one thing your system has to be able to do for her, and one milestone that gives you it.

1. Milestone 1 · IdentityRegister Meera's ABHA

   Meera walks in without a health ID. Create her ABHA so every record from today onwards links to one identity.

   [Build M1](/docs/hiecm/v3/milestones/m1)

2. Milestone 2 · Health Information ProviderAttach today's visit to her ABHA

   Her consultation note and her blood test are yours to hold. Group them into care contexts, link them to her ABHA address, and answer when her app comes looking.

   [Build M2](/docs/hiecm/v3/milestones/m2)

3. Milestone 3 · Health Information UserRetrieve the scan from another hospital

   Meera mentions a scan done last year, somewhere else. Ask her for consent, wait for her answer, then fetch and decrypt what she granted.

   [Build M3](/docs/hiecm/v3/milestones/m3)

4. Milestone 4 · Registry IntegrationEnrol the clinic and its doctors

   None of the above leaves sandbox until the clinic is a registered facility and its doctors hold professional IDs. Enrol both, then link your software to the facility.

   [Build M4](/docs/hiecm/v3/milestones/m4)

## The same story from Meera's own app

Building the patient's app ([PHR](/docs/hiecm/v3/getting-started/glossary#phr))? Implement the applicable ABHA and PHR services to allow individuals to manage their ABHA details, discover and link health records, and manage consent for sharing health information. The work splits into three, and each part mirrors a milestone on the provider side.

1. PHR 1 · Identity and profileMeera signs up and holds her own profile

   She registers with a mobile number or an existing ABHA number, logs in four different ways, and manages her card, her QR code and her family members.

   [Build P1](/docs/hiecm/v3/milestones/p1)

2. PHR 2 · Linking and recordsShe finds records she never linked

   She searches for the hospital she visited last year, sees what it holds, verifies by one time password, and pulls those care contexts onto her ABHA address.

   [Build P2](/docs/hiecm/v3/milestones/p2)

3. PHR 3 · Consent and notificationsShe decides who sees what

   A clinic asks for her records. She reads the request, narrows it, grants or denies it, and revokes it later. Your app tells her each time.

   [Build P3](/docs/hiecm/v3/milestones/p3)

## Select milestones based on the requirement of your software

The milestones required for integration depend on the role of the software. A Health Information Provider holds health records and makes them available for consent-based sharing. A Health Information User requests access to health records after obtaining the individual's consent. A software application may perform one or both roles. Applicable milestones depend on the functions and services offered.

| Who you build for                                                                                                                                                                                 | M1                                                   | M2                                                   | M3                                                   | M4                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **Health Facility or Health Facility Software.** May create and verify ABHA, link and share health records, access records with consent, and support NHPR registration.                           | Required                                             | The bulk of your build                               | Where it also reads records it did not create        | Required                                                                                    |
| **Health Information User**, such as an insurer, a referral service or an analytics service. May request and view health records held by another entity after receiving the individual's consent. | Required                                             | Not needed                                           | The bulk of your build                               | [Confirm at onboarding](/docs/hiecm/v3/concepts/participants/insurer#confirm-at-onboarding) |
| **Personal Health Record Application.** Enables individuals to manage their ABHA details, discover and link health records, and control consent for sharing them.                                 | [P1](/docs/hiecm/v3/milestones/p1), the patient side | [P2](/docs/hiecm/v3/milestones/p2), the patient side | [P3](/docs/hiecm/v3/milestones/p3), the patient side | Not needed                                                                                  |

## What each milestone gets you

| Milestone                                                                                            | What you get                                | Who needs it                                                   |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------- |
| [M1 Identity: ABHA Creation and Verification](/docs/hiecm/v3/milestones/m1)                          | Identity and the session token              | Everyone                                                       |
| [M2 Health Information Provider: Health Information Provider Services](/docs/hiecm/v3/milestones/m2) | Linking and sharing records                 | A facility publishing records, and a citizen pushing their own |
| [M3 Health Information User: Health Information User Services](/docs/hiecm/v3/milestones/m3)         | Consent and record fetching                 | Anyone reading records they did not create, and every PHR app  |
| [M4 Registry Integration: National Healthcare Providers Registry](/docs/hiecm/v3/milestones/m4)      | A facility ID and professional registration | Anyone going live as a facility                                |

These pages give the steps, the order to build them in and the failure modes. Every request URL, header and body sits on the [API reference](/docs/hiecm/v3/api) pages, one page per call.

## Next

Start with [M1 Identity](/docs/hiecm/v3/milestones/m1), or read [Go live](/docs/hiecm/v3/getting-started/going-live) for what happens after the fourth certificate.


---

# M1 Identity: Create and verify ABHA

Milestone 1 focuses on the creation and management of [ABHA](/docs/hiecm/v3/getting-started/glossary#abha), the unique health identifier under [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm). This milestone enables the creation of ABHA, authentication of users, and retrieval or updating of ABHA profile information through ABDM-compliant workflows. ABHA is a 14-digit unique health identifier issued to an individual upon successful completion of the prescribed verification process. ABHA serves as a foundational component for several ABDM services and workflows. Organizations implementing these services may be required to support ABHA creation and management capabilities, as applicable to their use case.

[Try the M1 APIs](/docs/hiecm/v3/api/m1)

[Every call in M1, one page each: the headers it needs, the payload it takes, the callback it triggers, and a request builder you can fire at the sandbox.](/docs/hiecm/v3/api/m1)

[Error codes](/docs/hiecm/v3/api/m1/errors)

[What each code M1 returns actually means, and the first thing to check when you see one.](/docs/hiecm/v3/api/m1/errors)

## In short

Milestone 1 focuses on ABHA creation, authentication, and profile management functionalities within the ABDM ecosystem. No health information exchange or health record sharing is performed as part of this milestone.

- ABDM gateway interactions require successful session establishment and the receipt of a valid access token before invoking protected APIs.
- The framework uses distinct gateway and user access tokens, each serving a specific authentication purpose and requiring usage in accordance with the applicable API specifications.
- Applications should use token validity and expiry parameters returned in API responses and implement appropriate token refresh mechanisms to ensure uninterrupted service continuity.
- Sensitive information, including Aadhaar numbers, mobile numbers, [OTPs](/docs/hiecm/v3/getting-started/glossary#otp), and passwords, must be transmitted using RSA encryption in accordance with ABDM security and data protection requirements.

## Capabilities enabled under Milestone 1 (M1)

| Capability                                                      | What it enables                                                                                                                                                                  |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Session and tokens                                              | Establish gateway sessions, manage access and refresh tokens, and retrieve public key certificates required for secure ABDM interactions.                                        |
| ABHA creation                                                   | Support creation of ABHA and associated identifiers in accordance with ABDM onboarding and verification workflows.                                                               |
| ABHA login                                                      | Authenticate an ABHA holder using approved identifiers and authentication mechanisms, including mobile number, ABHA number, or ABHA address, as applicable.                      |
| Profile management                                              | Retrieve and manage ABHA profile information, display ABHA credentials and QR codes, update eligible profile attributes, and support re-verification workflows where applicable. |
| [Scan and Register](/docs/hiecm/v3/use-cases/scan-and-register) | Support patient registration through QR-based workflows and generate service or queue identifiers in accordance with organization-specific processes.                            |

## Use cases

| Use case                                                        | What it does                                                                                                                                                                                              |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Scan and Register](/docs/hiecm/v3/use-cases/scan-and-register) | A patient scans the QR code at your counter and shares their ABHA profile. Registration needs no typing, every record from the visit links to the right ABHA address, and the patient gets a queue token. |

All use cases, and the milestone each belongs to: [Use cases](/docs/hiecm/v3/use-cases).

## Building blocks you use

- The [ABHA registry](/docs/hiecm/v3/registries), which holds the ABHA number, address and profile.
- The [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm) gateway, which issues your session token. See [The ABDM gateway](/docs/hiecm/v3/concepts/gateway).

## Build M1 with an AI coding assistant

The M1 skill gives an AI coding assistant this milestone as one file: every M1 call, its error codes and its test cases. Install it, or open it in your assistant in one click.

M1 agent skill

Every M1 call, one per use case, with its error codes in one file: 132 operations, 17 codes.

[SKILL.md](/skills/abdm-m1/SKILL.md "The router. Use the command below to take the references with it.")

- ScaffoldThe loop that builds the module flow by flow against the sandbox, ending on an observed result rather than on a call returning 200.
- DesignWhat the journey around the calls has to do, and what a screen is forbidden to claim.
- Integrate125 operations, with their hosts and headers.
- Debug17 error codes, each with what to do about it.

`mkdir -p .claude/skills/abdm-m1/references && curl -fsSL https://nhcx.sbxstage.in/skills/abdm-m1/SKILL.md -o .claude/skills/abdm-m1/SKILL.md && for f in scaffold design integrate debug; do curl -fsSL https://nhcx.sbxstage.in/skills/abdm-m1/references/$f.md -o .claude/skills/abdm-m1/references/$f.md; done`

[Open in Claude](claude://code/new?q=Install%20the%20ABDM%20M1%20agent%20skill%20into%20this%20project%2C%20then%20help%20me%20use%20it.%0A%0ARun%20this%3A%0Amkdir%20-p%20.claude%2Fskills%2Fabdm-m1%2Freferences%20%26%26%20curl%20-fsSL%20https%3A%2F%2Fnhcx.sbxstage.in%2Fskills%2Fabdm-m1%2FSKILL.md%20-o%20.claude%2Fskills%2Fabdm-m1%2FSKILL.md%20%26%26%20for%20f%20in%20scaffold%20design%20integrate%20debug%3B%20do%20curl%20-fsSL%20https%3A%2F%2Fnhcx.sbxstage.in%2Fskills%2Fabdm-m1%2Freferences%2F%24f.md%20-o%20.claude%2Fskills%2Fabdm-m1%2Freferences%2F%24f.md%3B%20done%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

Drops the skill into this project. Claude loads it when a task matches.

How to use it

1. Run the command above in the repository you are integrating.
2. Ask your agent for the job in your own words. "Add ABHA creation by Aadhaar OTP to this codebase", "why am I getting 404". The skill loads when the task matches it.
3. Check what it writes against these pages. The skill carries the facts, not the sandbox: nothing in it has been run against ABDM.
4. Open in Claude needs that app installed. It fills the composer and waits: nothing runs until you read it and press Enter.

## ABHA creation

### ABHA creation by an Aadhaar OTP

```mermaid
sequenceDiagram
    autonumber
    actor P as Person
    participant S as Your system
    participant A as ABHA service
    Note over S: Holds the gateway access token and the<br/>public key from GET /abha/api/v3/profile/public/certificate
    P->>S: Aadhaar number and consent
    S->>A: POST /abha/api/v3/enrollment/request/otp<br/>scope [abha-enrol], loginHint aadhaar,<br/>loginId (encrypted Aadhaar), otpSystem aadhaar
    A-->>S: txnId
    A-)P: OTP by SMS to the Aadhaar linked mobile
    P->>S: OTP, and the mobile number for ABHA communication
    S->>A: POST /abha/api/v3/enrollment/enrol/byAadhaar<br/>authData.authMethods [otp], otp {txnId,<br/>otpValue (encrypted), mobile}, consent
    A-->>S: ABHAProfile (ABHANumber, name, dob, gender, photo),<br/>tokens.token, isNew
    S->>A: POST /abha/api/v3/enrollment/request/otp<br/>scope [abha-enrol, mobile-verify], loginHint mobile,<br/>loginId (encrypted mobile), txnId
    A-->>S: txnId
    A-)P: OTP by SMS to the communication mobile
    P->>S: Mobile OTP
    S->>A: POST /abha/api/v3/enrollment/auth/byAbdm<br/>scope [abha-enrol, mobile-verify],<br/>authData.authMethods [otp], otp {txnId,<br/>otpValue (encrypted)}
    A-->>S: authResult success, accounts [ABHANumber]
    S->>A: GET /abha/api/v3/enrollment/enrol/suggestion<br/>header TRANSACTION_ID txnId
    A-->>S: abhaAddressList
    P->>S: Picks or types an ABHA address
    S->>A: POST /abha/api/v3/enrollment/enrol/abha-address<br/>txnId, abhaAddress, preferred 1
    A-->>S: healthIdNumber, preferredAbhaAddress
```

The individual provides their Aadhaar number. The ABHA service sends a one time password ([OTP](/docs/hiecm/v3/getting-started/glossary#otp)) to the mobile number registered against that Aadhaar. Upon successful verification, the individual selects an ABHA address, and the ABHA number is issued.

### ABHA creation by face authentication

```mermaid
sequenceDiagram
    autonumber
    actor P as Person (ABHA app)
    participant S as Your system
    participant A as ABHA service
    S->>A: POST /abha/api/v3/enrollment/enrol/auth/init<br/>scope [abha-enrol]
    A-->>S: txnId
    S->>P: QR code carrying the txnId
    P->>P: Scans the QR code in the ABHA app<br/>Face authentication through the Aadhaar RD service
    S->>A: POST /abha/api/v3/enrollment/enrol/capturePID<br/>txnId, scope [abha-enrol]
    A-->>S: status of the face authentication
    S->>A: POST /abha/api/v3/enrollment/enrol/byAadhaar<br/>authData.authMethods [face], face {txnId,<br/>aadhaar (encrypted), rdPidData, mobile}, consent
    A-->>S: ABHAProfile (ABHANumber, name, dob, gender, photo),<br/>tokens.token, isNew
    S->>A: POST /abha/api/v3/enrollment/request/otp<br/>scope [abha-enrol, mobile-verify], loginHint mobile,<br/>loginId (encrypted mobile), txnId
    A-)P: OTP by SMS to the communication mobile
    P->>S: Mobile OTP
    S->>A: POST /abha/api/v3/enrollment/auth/byAbdm<br/>scope [abha-enrol, mobile-verify],<br/>authData.authMethods [otp], otp {txnId,<br/>otpValue (encrypted)}
    A-->>S: authResult success
    S->>A: GET /abha/api/v3/enrollment/enrol/suggestion<br/>header TRANSACTION_ID txnId
    A-->>S: abhaAddressList
    S->>A: POST /abha/api/v3/enrollment/enrol/abha-address<br/>txnId, abhaAddress, preferred 1
    A-->>S: healthIdNumber, preferredAbhaAddress
```

Individuals who are unable to use OTP-based authentication, including cases where the mobile number linked to Aadhaar is unavailable or inaccessible, may use face authentication as an alternative verification mechanism, subject to ABDM and UIDAI guidelines. Face authentication is performed through authorized Aadhaar Registered Device (RD) services using approved authentication workflows.

ABDM documentation references biometric-based ABHA creation workflows, including face authentication and other supported biometric modalities where applicable. Organizations should implement authentication methods in accordance with the officially published specifications and follow them before proceeding with production deployment.

### ABHA creation by fingerprint or iris

Aadhaar Biometric-Based ABHA Creation enables users to create an Ayushman Bharat Health Account (ABHA) by securely verifying their identity using biometric authentication through an Aadhaar Registered Device (RD). The RD Service captures the user's biometric data and generates an encrypted, digitally signed PID block, which is submitted along with the Aadhaar details for verification. Upon successful authentication and user consent, the user's profile is validated and a unique ABHA number is generated, enabling secure onboarding into the ABDM digital health ecosystem.

The Registered Device (RD) List and information can be found on the following link: [uidai.gov.in](https://uidai.gov.in/en/ecosystem/authentication-devices-documents/biometric-devices.html).

The calls, in order, are on the [M1 API reference](/docs/hiecm/v3/api/m1) under ABHA creation, fingerprint and ABHA creation, iris.

### ABHA creation by demographic authentication

```mermaid
sequenceDiagram
    autonumber
    actor P as Person
    participant S as Your system
    participant A as ABHA service
    Note over S: Holds the gateway access token and the<br/>public key from GET /abha/api/v3/profile/public/certificate
    P->>S: Aadhaar number, name as per Aadhaar, date of birth,<br/>gender, consent
    S->>S: Encrypts the Aadhaar number with the public key
    S->>A: POST /abha/api/v3/enrollment/enrol/byAadhaar<br/>authData.authMethods [demo_auth],<br/>demo_auth {aadhaar (encrypted), name, dob, gender,<br/>mobile}, consent
    A-->>S: ABHAProfile (ABHANumber,<br/>phrAddress issued by default), tokens.token, isNew
    S->>A: GET /abha/api/v3/profile/account<br/>header X-token tokens.token
    A-->>S: ABHANumber, preferredAbhaAddress, profile fields
```

This onboarding pathway is intended for eligible government programme integrations in accordance with ABDM guidelines. Unlike OTP-based or biometric authentication workflows, demographic authentication relies on validation of Aadhaar demographic information, including name, date of birth, and gender, through the prescribed verification process.

The `enrol/byAadhaar` API is invoked with the appropriate authentication method and encrypted demographic details as specified in the implementation guidelines. Implementers should account for the response structure defined for this workflow, including user token handling and ABHA address generation behaviour. A system-generated ABHA address may be assigned during account creation, and organizations may provide users with the option to configure a more user-friendly ABHA address where permitted. Any demographic verification failures should be handled in accordance with the error codes and response specifications published by ABDM.

### Create a child ABHA

ABDM supports guardian-based management of ABHA accounts for eligible children in accordance with applicable policies and implementation guidelines. This functionality is currently made available only to select government integrators, subject to approval by the National Health Authority (NHA). The workflow includes creation of a child ABHA linked to a verified parent or guardian account, updating child profile information, and retrieval of child accounts associated with the parent or guardian.

## ABHA login via mobile number

```mermaid
sequenceDiagram
    autonumber
    actor P as Person
    participant S as Your system
    participant A as ABHA service
    P->>S: Mobile number
    S->>A: POST /abha/api/v3/profile/login/request/otp<br/>scope [abha-login, mobile-verify], loginHint mobile,<br/>loginId (encrypted mobile), otpSystem abdm
    A-->>S: txnId
    A-)P: OTP by SMS
    P->>S: OTP
    S->>A: POST /abha/api/v3/profile/login/verify<br/>scope [abha-login, mobile-verify],<br/>authData.authMethods [otp], otp {txnId,<br/>otpValue (encrypted)}
    A-->>S: authResult success, token (T-token),<br/>accounts [ABHANumber, name, preferredAbhaAddress]
    P->>S: Picks the account to use
    S->>A: POST /abha/api/v3/profile/login/verify/user<br/>header T-token, ABHANumber, txnId
    A-->>S: token (X-token), expiresIn, refreshToken,<br/>refreshExpiresIn
```

ABHA login using a registered mobile number enables individuals to securely access their ABHA-linked profile and services through a mobile OTP-based authentication process. Since a single mobile number may be associated with multiple ABHA accounts, the user may be required to select the appropriate ABHA account after successful verification. Upon completion of the authentication process, authorized access is granted to the individual's ABHA profile and associated services in accordance with ABDM guidelines.

## Find ABHA from mobile number

```mermaid
sequenceDiagram
    autonumber
    actor P as Person
    participant S as Your system
    participant A as ABHA service
    P->>S: Mobile number
    S->>S: Encrypts the mobile number with the public key
    S->>A: POST /abha/api/v3/profile/account/abha/search<br/>scope [search-abha], mobile (encrypted)
    A-->>S: txnId, ABHA list (masked ABHA number, name, gender)
    P->>S: Confirms the account to prove
    S->>A: POST /abha/api/v3/profile/login/request/otp<br/>scope [abha-login, mobile-verify], loginHint mobile,<br/>loginId index, otpSystem abdm, txnId
    A-->>S: txnId
    A-)P: OTP by SMS to the registered mobile
    P->>S: OTP
    S->>A: POST /abha/api/v3/profile/login/verify<br/>scope [abha-login, mobile-verify],<br/>authData.authMethods [otp], otp {txnId,<br/>otpValue (encrypted)}
    A-->>S: authResult success, token (X-token), accounts
```

This workflow enables discovery of an existing ABHA using a registered mobile number when an individual does not readily know their ABHA details. Upon successful verification of the mobile number, the system may return limited, non-sensitive information such as the individual's name, gender, and masked ABHA number, allowing confirmation of whether an ABHA has already been created.

Access to complete profile information and sensitive account details requires successful authentication through approved mechanisms such as OTP, biometric authentication, or face authentication. All identifiers and personal information must be encrypted and processed within the integrating system in accordance with ABDM security, privacy, and data protection requirements. See [encryption](/docs/hiecm/v3/concepts/encryption) for how to do it locally.

## ABHA Profile Management

```mermaid
sequenceDiagram
    autonumber
    participant S as Your system
    participant A as ABHA service
    Note over S: Holds the X-token from a login or enrolment response
    S->>A: GET /abha/api/v3/profile/account<br/>header X-token
    A-->>S: ABHANumber, preferredAbhaAddress, name, dob, gender,<br/>mobile, kycVerified
    S->>A: GET /abha/api/v3/profile/account/abha-card<br/>header X-token
    A-->>S: ABHA card image
    S->>A: GET /abha/api/v3/profile/account/qrCode<br/>header X-token
    A-->>S: QR code image
```

This functionality enables retrieval and management of an individual's ABHA profile following successful authentication. Authorized users can access profile information, view their ABHA card, and retrieve the associated Quick Response (QR) code, which serves as a digital representation of the ABHA identifier for use across ABDM-enabled healthcare services.

The workflow also supports profile updates in accordance with applicable ABDM guidelines, ensuring that health identity information remains accurate and up to date while complying with prescribed security, privacy, and authentication requirements.

## Next

- Register a patient who scanned your counter QR code: [Scan and Register](/docs/hiecm/v3/use-cases/scan-and-register).
- The calls, base URLs and error shapes: [M1 API reference](/docs/hiecm/v3/api/m1).
- Certification runs once, for the whole integration: [Go live](/docs/hiecm/v3/getting-started/going-live).
- The next milestone: [M2 Health Information Provider](/docs/hiecm/v3/milestones/m2).


---

# M2 Health Information Provider: Create and link records

Milestone 2 enables a [Health Information Provider](/docs/hiecm/v3/getting-started/glossary#hip) (HIP) to create digital health records and link them with a patient's [ABHA Address](/docs/hiecm/v3/getting-started/glossary#abha-address), facilitate record [discovery](/docs/hiecm/v3/getting-started/glossary#discovery) through a Personal Health Record ([PHR](/docs/hiecm/v3/getting-started/glossary#phr)) application, and securely share encrypted health information across the ABDM ecosystem.

[Try the M2 APIs](/docs/hiecm/v3/api/m2)

[Every call in M2, one page each: the headers it needs, the payload it takes, the callback it triggers, and a request builder you can fire at the sandbox.](/docs/hiecm/v3/api/m2)

[Error codes](/docs/hiecm/v3/api/m2/errors)

[What each code M2 returns actually means, and the first thing to check when you see one.](/docs/hiecm/v3/api/m2/errors)

## In short

Health Information Provider (HIP) links a patient's health records with the patient's ABHA Address and makes such records available within the ABDM ecosystem. The linkage of records may be carried out through either HIP-Initiated Linking or User-Initiated Linking.

## M2 functionalities

**Care Context:** A [Care Context](/docs/hiecm/v3/concepts/care-context) represents a patient's visit to a healthcare facility and contains the health records generated during that visit. The healthcare facility links the Care Context with the patient's ABHA Address.

The records may be linked through either HIP-Initiated Linking or User-Initiated Linking.

**HIP-Initiated Linking:** In this workflow, an ABDM-enabled healthcare facility generates a link token to authenticate the patient and links the care contexts with the patient's ABHA Address. The linked care contexts are subsequently made available in the patient's [PHR application](/docs/hiecm/v3/concepts/participants/phr).

**User-Initiated Linking:** This flow allows a patient to find and link health records created earlier without an ABHA Address. The records are stored in the [HMIS](/docs/hiecm/v3/getting-started/glossary#hmis) using the patient's registered details. When the patient selects the fetch option in the [PHR application](/docs/hiecm/v3/concepts/participants/phr), the healthcare facility matches the respective demographic details and shows the available records for linking with the patient's ABHA Address.

**Data Transfer:** In this flow, each health record is converted into the prescribed [FHIR](/docs/hiecm/v3/getting-started/glossary#fhir) format, packaged as a FHIR bundle, encrypted, and securely transmitted through the ABDM ecosystem.

## Prerequisites

Before implementing Milestone 2 (M2), ensure that the following prerequisites are fulfilled:

1. The healthcare facility must be registered in the Health Facility Registry ([HFR](/docs/hiecm/v3/getting-started/glossary#hfr)) and have a valid HFR ID (facility ID).
2. The HIP ID (Facility ID) must be linked to the corresponding Client ID to receive callbacks through the NHPR Portal or [M4](/docs/hiecm/v3/milestones/m4) APIs using software linkage.
3. A valid callback URL must be configured for the Client ID using the [Update Bridge API](/docs/hiecm/v3/api/gateway/endpoints/gateway-abdm-gateway/03-gateway-patch-gateway-v3-bridge-url).

## FHIR-based health records

In the ABDM ecosystem, every health record is created and shared in a standardized format called FHIR (Fast Healthcare Interoperability Resources) to enable secure and interoperable exchange of health information.

FHIR is a globally recognized standard for structuring and exchanging digital health records.

FHIR Implementation Guide (ABDM): [nrces.in/ndhm/fhir/r4](https://nrces.in/ndhm/fhir/r4/index.html)

### Health information types

ABDM has defined 08 Health Information (HI) Types, comprising 07 Clinical and 01 Billing artefact.

| Name                                                                                                    | Definition                                                                                                                                                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [DiagnosticReportRecord](https://nrces.in/ndhm/fhir/r4/StructureDefinition-DiagnosticReportRecord.html) | The Clinical Artifact represents diagnostic reports including Radiology and Laboratory reports that can be shared across the health ecosystem.                                                                                                                                                      |
| [DischargeSummaryRecord](https://nrces.in/ndhm/fhir/r4/StructureDefinition-DischargeSummaryRecord.html) | Clinical document used to represent the discharge summary record for ABDM HDE data set.                                                                                                                                                                                                             |
| [HealthDocumentRecord](https://nrces.in/ndhm/fhir/r4/StructureDefinition-HealthDocumentRecord.html)     | The Clinical Artifact represents the unstructured historical health records as a single of multiple Health Record Documents generally uploaded by the patients through the Health Locker and can be shared across the health ecosystem.                                                             |
| [ImmunizationRecord](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ImmunizationRecord.html)         | The Clinical Artifact represents the Immunization records with any additional documents such as vaccine certificate, the next immunization recommendations, etc. This can be further shared across the health ecosystem.                                                                            |
| [OPConsultRecord](https://nrces.in/ndhm/fhir/r4/StructureDefinition-OPConsultRecord.html)               | The Clinical Artifact represents the outpatient visit consultation note which may include clinical information on any OP examinations, procedures along with medication administered, and advice that can be shared across the health ecosystem.                                                    |
| [PrescriptionRecord](https://nrces.in/ndhm/fhir/r4/StructureDefinition-PrescriptionRecord.html)         | The Clinical Artifact represents the medication advice to the patient in compliance with the Pharmacy Council of India (PCI) guidelines, which can be shared across the health ecosystem.                                                                                                           |
| [WellnessRecord](https://nrces.in/ndhm/fhir/r4/StructureDefinition-WellnessRecord.html)                 | The Clinical Artifact represents regular wellness information of patients typically through the Patient Health Record (PHR) application covering clinical information such as vitals, physical examination, general wellness, women wellness, etc., that can be shared across the health ecosystem. |
| [InvoiceRecord](https://nrces.in/ndhm/fhir/r4/StructureDefinition-InvoiceRecord.html)                   | The billing artifact represents the invoice details such as pharmacy invoice, consultation invoice etc. along with the support for scanned documents attached for the patient which can be shared across the health ecosystem.                                                                      |

**Note:** Each applicable Health Information Type is represented as a FHIR Document Bundle in accordance with ABDM standards.

## Build M2 with an AI coding assistant

The M2 skill gives an AI coding assistant this milestone as one file: every M2 call and callback, its error codes and its test cases. Install it, or open it in your assistant in one click.

M2 agent skill

Every M2 call and callback, its error codes and its certification cases in one file: 31 operations, 120 codes, 46 cases.

[SKILL.md](/skills/abdm-m2/SKILL.md "The router. Use the command below to take the references with it.")

- ScaffoldThe loop that builds the module flow by flow against the sandbox, ending on an observed result rather than on a call returning 200.
- DesignWhat the journey around the calls has to do, and what a screen is forbidden to claim.
- Integrate24 operations, with their hosts and headers.
- Debug120 error codes, each with what to do about it.

`mkdir -p .claude/skills/abdm-m2/references && curl -fsSL https://nhcx.sbxstage.in/skills/abdm-m2/SKILL.md -o .claude/skills/abdm-m2/SKILL.md && for f in scaffold design integrate debug; do curl -fsSL https://nhcx.sbxstage.in/skills/abdm-m2/references/$f.md -o .claude/skills/abdm-m2/references/$f.md; done`

[Open in Claude](claude://code/new?q=Install%20the%20ABDM%20M2%20agent%20skill%20into%20this%20project%2C%20then%20help%20me%20use%20it.%0A%0ARun%20this%3A%0Amkdir%20-p%20.claude%2Fskills%2Fabdm-m2%2Freferences%20%26%26%20curl%20-fsSL%20https%3A%2F%2Fnhcx.sbxstage.in%2Fskills%2Fabdm-m2%2FSKILL.md%20-o%20.claude%2Fskills%2Fabdm-m2%2FSKILL.md%20%26%26%20for%20f%20in%20scaffold%20design%20integrate%20debug%3B%20do%20curl%20-fsSL%20https%3A%2F%2Fnhcx.sbxstage.in%2Fskills%2Fabdm-m2%2Freferences%2F%24f.md%20-o%20.claude%2Fskills%2Fabdm-m2%2Freferences%2F%24f.md%3B%20done%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

Drops the skill into this project. Claude loads it when a task matches.

How to use it

1. Run the command above in the repository you are integrating.
2. Ask your agent for the job in your own words. "Link a care context for this patient", "why am I getting ABDM-1000". The skill loads when the task matches it.
3. Check what it writes against these pages. The skill carries the facts, not the sandbox: nothing in it has been run against ABDM.
4. Open in Claude needs that app installed. It fills the composer and waits: nothing runs until you read it and press Enter.

## Workflow overview

This section explains the key Milestone 2 (M2) workflows using sequence diagrams. These diagrams provide a high-level view of how different systems interact before the detailed API specifications are discussed.

## Journey 1: HIP initiated linking

```mermaid
sequenceDiagram
    autonumber
    participant S as Your system (HIP)
    participant G as ABDM Gateway
    participant P as ABHA / PHR app
    Note over S,G: Step 1: generate link token
    S->>G: POST /api/hiecm/v3/token/generate-token<br/>abhaNumber, abhaAddress, name, gender, yearOfBirth
    G-->>S: 202 Accepted
    Note over S,G: Step 2: ABDM responds asynchronously with token details
    G-)S: POST /api/v3/hip/token/on-generate-token<br/>abhaAddress, linkToken
    S-->>G: 202 Accepted
    Note over S,G: Step 3: push care contexts
    S->>G: POST /api/hiecm/hip/v3/link/carecontext<br/>Authorization: Bearer accessToken, X-Link-Token: linkToken<br/>abhaNumber, abhaAddress, patient [referenceNumber, display,<br/>careContexts [referenceNumber, display], hiType, count]
    G-->>S: 202 Accepted, care contexts queued
    Note over S,G: Step 4: ABDM responds asynchronously with the status of linking
    G-)S: POST /api/v3/link/on_carecontext<br/>status
    S-->>G: 202 Accepted
    G-)P: Push notification, record linked
    P->>P: Patient sees a new record linked
```

The HIP generates a linking token using the patient's ABHA address and demographic details for authentication. After successful verification, a linking token valid for 6 months is created, and the patient's care context is linked to the ABHA Address.

The steps, as drawn:

1. Your system calls `POST /api/hiecm/v3/token/generate-token` with the patient's ABHA number or ABHA address, name, gender and year of birth.
2. The gateway answers 202 Accepted.
3. The gateway calls `POST /api/v3/hip/token/on-generate-token` on your bridge with the ABHA address and the link token.
4. Your system answers 202 Accepted and stores the link token against the patient.
5. Your system calls `POST /api/hiecm/hip/v3/link/carecontext` with the gateway access token, the link token in `X-Link-Token`, and the patient's care contexts: for each, a reference number and a display name, the HI type and the count of records.
6. The gateway answers 202 Accepted and queues the care contexts.
7. The gateway calls `POST /api/v3/link/on_carecontext` on your bridge with the status of the linking.
8. Your system answers 202 Accepted.
9. The gateway pushes a notification to the patient's ABHA or PHR app that a record is linked.
10. The patient sees the new record linked in the app.

## Journey 2: user initiated linking

```mermaid
sequenceDiagram
    autonumber
    actor U as User
    participant P as ABHA / PHR app
    participant G as ABDM Gateway
    participant B as HIP bridge URL
    participant S as HIP system
    Note over U,S: Phase 1: patient triggers discovery
    U->>P: Search for records at a specific HIP
    P->>G: Initiate discovery, patient demographics and HIP ID
    G->>B: POST callback_url/api/v3/hip/patient/care-context/discover<br/>transactionId, patient {id, name, gender, dob, verifiedIdentifiers}
    B->>S: Look up matching records
    S->>G: POST /api/hiecm/user-initiated-linking/v3/patient/care-context/on-discover<br/>Authorization: Bearer accessToken<br/>transactionId, patient [referenceNumber, display,<br/>careContexts [referenceNumber, display], hiType, count],<br/>response {requestId}
    G-->>S: 202 Accepted
    G->>P: Forward discovered records to the PHR app
    P->>U: Display discovered care contexts
    U->>P: Select care contexts to link
    Note over U,S: Phase 2: patient initiates link
    P->>G: POST /api/hiecm/user-initiated-linking/v3/link/care-context/init<br/>selected care contexts
    G->>B: POST callback_url/api/v3/hip/link/care-context/init<br/>transactionId, patient {id, referenceNumber, careContexts}
    B->>S: Prepare OTP verification
    S->>G: POST /api/hiecm/user-initiated-linking/v3/link/care-context/on-init<br/>Authorization: Bearer accessToken<br/>transactionId, link {referenceNumber, authenticationType DIRECT,<br/>meta {communicationMedium MOBILE, communicationHint OTP,<br/>communicationExpiry}}, response {requestId}
    G-->>S: 202 Accepted
    G->>P: OTP sent to the patient's mobile
    Note over U,S: Phase 3: patient enters OTP, link confirm
    U->>P: Enter the OTP received on mobile
    P->>G: POST /api/hiecm/user-initiated-linking/v3/link/care-context/confirm<br/>OTP and linkRefNumber
    G->>B: POST callback_url/api/v3/hip/link/care-context/confirm<br/>transactionId, confirmation {linkRefNumber, token}
    B->>S: Validate the OTP, confirm the link
    S->>G: POST /api/hiecm/user-initiated-linking/v3/link/care-context/on-confirm<br/>Authorization: Bearer accessToken<br/>patient [referenceNumber, display,<br/>careContexts [referenceNumber, display], hiType, count],<br/>response {requestId}
    G-->>S: 202 Accepted
    G->>P: Linking confirmed
    P->>U: Care contexts linked successfully
```

ABDM enables users to discover their health records from healthcare facilities they have visited through a PHR application. The discovery request is sent by the HIE-CM to the respective HRP/HIP, which searches for and returns the user's available care contexts.

If matching records are found, all relevant care contexts are shared with the user. The user can then select and link these care contexts to their ABHA Address.

The steps, as drawn:

1. The user searches for records at a specific HIP in the PHR app.
2. The PHR app initiates discovery with the patient's demographics and the HIP ID.
3. The gateway calls `POST /api/v3/hip/patient/care-context/discover` on your bridge with the transaction ID and the patient's id, name, gender, date of birth and verified identifiers.
4. Your system looks up the matching records.
5. Your system calls `POST /api/hiecm/user-initiated-linking/v3/patient/care-context/on-discover` with the transaction ID, the matching care contexts and the request ID it answers.
6. The gateway answers 202 Accepted.
7. The gateway forwards the discovered records to the PHR app.
8. The PHR app displays the discovered care contexts.
9. The user selects the care contexts to link.
10. The PHR app calls `POST /api/hiecm/user-initiated-linking/v3/link/care-context/init` with the selected care contexts.
11. The gateway calls `POST /api/v3/hip/link/care-context/init` on your bridge with the transaction ID, the patient's id and reference number, and the care contexts.
12. Your system prepares OTP verification.
13. Your system calls `POST /api/hiecm/user-initiated-linking/v3/link/care-context/on-init` with the transaction ID, a link reference number, authentication type DIRECT, and the communication medium, hint and expiry.
14. The gateway answers 202 Accepted.
15. An OTP is sent to the patient's mobile.
16. The user enters the OTP received on the mobile.
17. The PHR app calls `POST /api/hiecm/user-initiated-linking/v3/link/care-context/confirm` with the OTP and the link reference number.
18. The gateway calls `POST /api/v3/hip/link/care-context/confirm` on your bridge with the transaction ID, the link reference number and the token.
19. Your system validates the OTP and confirms the link.
20. Your system calls `POST /api/hiecm/user-initiated-linking/v3/link/care-context/on-confirm` with the linked care contexts and the request ID it answers.
21. The gateway answers 202 Accepted.
22. The gateway tells the PHR app the linking is confirmed.
23. The PHR app shows the user that the care contexts are linked.

## Journey 3: data transfer flow

```mermaid
sequenceDiagram
    autonumber
    actor U as Patient
    participant H as HIU system (data requester)
    participant CM as Consent manager (ABDM Gateway)
    participant B as HIP bridge URL
    participant S as HIP system
    participant G as ABDM Gateway
    Note over U,G: Phase 1: HIU requests consent
    H->>CM: POST /api/hiecm/consent/v3/request/init<br/>patient ABHA, HI types, date range
    CM->>U: Notify the patient in the ABHA app, consent request pending
    U->>CM: Approve consent in the ABHA app
    Note over U,G: Phase 2: consent artefact delivery to the HIP
    CM->>B: POST callback_url/api/v3/consent/request/hip/notify<br/>notification {consentId, status GRANTED,<br/>consentDetail {hiTypes, dateRange, careContexts},<br/>signature, grantAcknowledgement}
    S->>G: POST /api/hiecm/consent/v3/request/hip/on-notify<br/>Authorization: Bearer accessToken<br/>acknowledgement {status OK, consentId}, response {requestId}
    G-->>S: 202 Accepted, acknowledgement recorded
    Note over U,G: Phase 3: HIU requests health data
    H->>G: POST /api/hiecm/data-flow/v3/health-information/request<br/>consent {id: consentId}, dateRange,<br/>dataPushUrl, keyMaterial {publicKey}
    G->>B: POST callback_url/api/v3/hip/health-information/request<br/>transactionId, hiRequest {consent, dateRange,<br/>dataPushUrl, keyMaterial}
    S->>G: POST /api/hiecm/data-flow/v3/health-information/hip/on-request<br/>Authorization: Bearer accessToken<br/>hiRequest {transactionId, sessionStatus ACKNOWLEDGED},<br/>response {requestId}
    G-->>S: 202 Accepted
    Note over U,G: Phase 4: HIP prepares and pushes encrypted data
    S->>S: Fetch matching records for the consent date range
    S->>S: Encrypt FHIR bundles with the HIU public key (ECDH)
    loop For each page of records
        S->>H: POST dataPushUrl<br/>pageNumber, pageCount, transactionId,<br/>entries [{content: encrypted FHIR+JSON, media application/fhir+json,<br/>checksum, careContextReference}], keyMaterial {publicKey, nonce}
        H-->>S: 202 Accepted
    end
    Note over U,G: Phase 5: HIP notifies the gateway that the transfer is complete
    S->>G: POST /api/hiecm/data-flow/v3/health-information/notify<br/>Authorization: Bearer accessToken<br/>notification {consentId, transactionId, doneAt,<br/>notifier {type HIP, id HIP_ID},<br/>statusNotification {sessionStatus TRANSFERRED, hipId,<br/>statusResponses [{careContextReference, hiStatus OK, description}]}}
    G-->>S: 202 Accepted
    G->>H: Notify the HIU, data transfer complete
    H->>H: Decrypt and process the FHIR records
```

The HIP sends structured and unstructured health information types in accordance with the NRCES FHIR standards. The FHIR bundle is encrypted and securely exchanged through the ABDM ecosystem.

The steps, as drawn:

1. The HIU calls `POST /api/hiecm/consent/v3/request/init` with the patient's ABHA address, the HI types and the date range.
2. The consent manager notifies the patient in the ABHA app that a consent request is pending.
3. The patient approves the consent in the ABHA app.
4. The consent manager calls `POST /api/v3/consent/request/hip/notify` on your bridge with the consent ID, status GRANTED, the consent detail (HI types, date range, care contexts), the signature and the grant acknowledgement.
5. Your system calls `POST /api/hiecm/consent/v3/request/hip/on-notify` with the acknowledgement (status OK, consent ID) and the request ID it answers.
6. The gateway answers 202 Accepted and records the acknowledgement.
7. The HIU calls `POST /api/hiecm/data-flow/v3/health-information/request` with the consent ID, the date range, its data push URL and its key material.
8. The gateway calls `POST /api/v3/hip/health-information/request` on your bridge with the transaction ID and the request: consent, date range, data push URL and key material.
9. Your system calls `POST /api/hiecm/data-flow/v3/health-information/hip/on-request` with the transaction ID, session status ACKNOWLEDGED and the request ID it answers.
10. The gateway answers 202 Accepted.
11. Your system fetches the matching records for the consent date range.
12. Your system encrypts the FHIR bundles with the HIU's public key ([ECDH](/docs/hiecm/v3/getting-started/glossary#ecdh)).
13. For each page of records, your system posts to the HIU's data push URL: the page number and count, the transaction ID, the entries (encrypted FHIR+JSON content, media type application/fhir+json, checksum, care context reference) and your key material (public key, nonce).
14. The HIU answers 202 Accepted for each page.
15. Your system calls `POST /api/hiecm/data-flow/v3/health-information/notify` with the consent ID, the transaction ID, the completion time, the notifier (type HIP, your HIP ID), session status TRANSFERRED and a status response per care context.
16. The gateway answers 202 Accepted.
17. The gateway notifies the HIU that the data transfer is complete.
18. The HIU decrypts and processes the FHIR records.

## Error codes

The codes an M2 integration may meet across discovery, linking, consent, encryption and data exchange are listed in one place: [M2 error codes](/docs/hiecm/v3/api/m2/errors).

## Next

- The calls, callbacks and error codes: [M2 API reference](/docs/hiecm/v3/api/m2).
- The next milestone: [M3 Health Information User](/docs/hiecm/v3/milestones/m3).


---

# M3 Health Information User: Fetch data with consent

Milestone 3 (M3) enables a [Health Information User](/docs/hiecm/v3/getting-started/glossary#hiu) (HIU) to request, receive and view a patient's health records from [Health Information Providers](/docs/hiecm/v3/getting-started/glossary#hip) (HIPs) in a secure and consent-based manner. The HIU initiates a consent request, and upon approval by the patient, the requested health records are securely transferred in the prescribed [FHIR](/docs/hiecm/v3/getting-started/glossary#fhir) format for access by the authorised healthcare professional.

[Try the M3 APIs](/docs/hiecm/v3/api/m3)

[Every call in M3, one page each: the headers it needs, the payload it takes, the callback it triggers, and a request builder you can fire at the sandbox.](/docs/hiecm/v3/api/m3)

[Error codes](/docs/hiecm/v3/api/m3/errors)

[What each code M3 returns actually means, and the first thing to check when you see one.](/docs/hiecm/v3/api/m3/errors)

## In short

The HIU initiates a consent request using the patient's [ABHA Address](/docs/hiecm/v3/getting-started/glossary#abha-address). The [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm) notifies the patient and communicates the consent status to the HIU through the ABDM Gateway. Upon approval, the HIU fetches the generated [consent artefact](/docs/hiecm/v3/getting-started/glossary#consent-artefact)(s) and initiates a request for the authorised health information. The concerned HIP validates the request, encrypts the authorised health information and transfers it to the data-push URL specified by the HIU. The HIU receives and decrypts the information and submits the prescribed receipt-status notification.

## M3 functionality

- **Consent Request:** Enables the HIU to initiate a consent request using the patient's ABHA Address. The patient may approve or deny the request through the [PHR](/docs/hiecm/v3/getting-started/glossary#phr) application.
- **Status of Consent:** Enables the HIU to track the consent status as Requested, Granted, Denied, Revoked or Expired and fetch the consent artefact(s) generated upon approval.
- **Request Data:** Enables the HIU to request health information against a valid consent artefact, receive and decrypt the FHIR bundle, and display the authorised records in a readable format.

## Use cases

| Use case                                                              | What it does                                                                                                                                                                                                                   |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Patient record share](/docs/hiecm/v3/use-cases/patient-record-share) | A patient scans the QR code at your counter and pushes chosen records from their PHR app to your system. You raise no consent request: you reply with a data push URL and a key, receive the records, and report what arrived. |

All use cases, and the milestone each belongs to: [Use cases](/docs/hiecm/v3/use-cases).

## Applicable for

Milestone 3 applies to entities or applications performing the Health Information User (HIU) role and requiring access to health information held by one or more Health Information Providers. These may include healthcare facilities, insurers, referral-service providers, clinical decision-support applications and [PHR](/docs/hiecm/v3/getting-started/glossary#phr) applications acting on behalf of the patient.

## Prerequisites

Before implementing Milestone 3, the healthcare facility must complete [Milestone 1](/docs/hiecm/v3/milestones/m1) requirements and should be registered as an HIU.

## Consent management flow

```mermaid
sequenceDiagram
    autonumber
    participant H as HIU
    participant CM as HIE-CM (consent manager and gateway)
    actor P as Patient (PHR app)
    participant HIP as HIP (one per artefact)
    H->>CM: Requests the patient's data
    CM-)P: Notifies the patient of the consent request,<br/>creates the consent request id
    P->>CM: Grants consent
    CM-)H: Generates the consent artefact id(s),<br/>one per HIP when data is requested from several
    H->>CM: Data push URL where the information can be shared
    CM-)HIP: Forwards the request against a transaction id
    HIP->>HIP: Checks the artefact is not expired, paused or revoked,<br/>the date-time range, and the encryption parameters
    HIP-)H: Transfers the data against the transaction id
    HIP->>CM: Notifies that the requested information is transmitted
    H->>CM: Notifies that the information is received, or that the request failed
```

The Consent Management Flow facilitates the secure and consent-based exchange of a patient's health information between the HIU and the concerned HIP through the HIE-CM.

- **Health-Information Request:** The HIU initiates a request for the patient's health information through the HIE-CM.
- **Patient Notification:** The HIE-CM generates a Consent Request ID and notifies the patient regarding the consent request through the PHR application.
- **Consent Approval:** The patient grants consent through the PHR application.
- **Consent Artefact Generation:** The HIE-CM generates the consent artefact ID(s) and communicates them to the HIU. Separate consent artefacts are generated where data is requested from multiple HIPs.
- **Data-Push URL:** A data-push URL is generated for receiving the requested health information.
- **Request Validation:** The concerned HIP validates the consent status, applicable date-time range and encryption parameters.
- **Data Transfer:** The requested health information is transferred to the HIU against the Transaction ID assigned by the HIE-CM.
- **Transfer and Receipt Notification:** Upon completion of the transfer, the HIP notifies the HIE-CM that the requested information has been transmitted, and the HIU notifies the HIE-CM regarding successful receipt or failure of the request.

## Build M3 with an AI coding assistant

The M3 skill gives an AI coding assistant this milestone as one file: every M3 call and callback with its error codes. Install it, or open it in your assistant in one click.

M3 agent skill

Every M3 call and callback with its error codes in one file: 25 operations, 95 codes.

[SKILL.md](/skills/abdm-m3/SKILL.md "The router. Use the command below to take the references with it.")

- ScaffoldThe loop that builds the module flow by flow against the sandbox, ending on an observed result rather than on a call returning 200.
- DesignWhat the journey around the calls has to do, and what a screen is forbidden to claim.
- Integrate16 operations, with their hosts and headers.
- DebugNo error code is recorded yet.

`mkdir -p .claude/skills/abdm-m3/references && curl -fsSL https://nhcx.sbxstage.in/skills/abdm-m3/SKILL.md -o .claude/skills/abdm-m3/SKILL.md && for f in scaffold design integrate debug; do curl -fsSL https://nhcx.sbxstage.in/skills/abdm-m3/references/$f.md -o .claude/skills/abdm-m3/references/$f.md; done`

[Open in Claude](claude://code/new?q=Install%20the%20ABDM%20M3%20agent%20skill%20into%20this%20project%2C%20then%20help%20me%20use%20it.%0A%0ARun%20this%3A%0Amkdir%20-p%20.claude%2Fskills%2Fabdm-m3%2Freferences%20%26%26%20curl%20-fsSL%20https%3A%2F%2Fnhcx.sbxstage.in%2Fskills%2Fabdm-m3%2FSKILL.md%20-o%20.claude%2Fskills%2Fabdm-m3%2FSKILL.md%20%26%26%20for%20f%20in%20scaffold%20design%20integrate%20debug%3B%20do%20curl%20-fsSL%20https%3A%2F%2Fnhcx.sbxstage.in%2Fskills%2Fabdm-m3%2Freferences%2F%24f.md%20-o%20.claude%2Fskills%2Fabdm-m3%2Freferences%2F%24f.md%3B%20done%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

Drops the skill into this project. Claude loads it when a task matches.

How to use it

1. Run the command above in the repository you are integrating.
2. Ask your agent for the job in your own words. "Raise a consent request and fetch the records it covers". The skill loads when the task matches it.
3. Check what it writes against these pages. The skill carries the facts, not the sandbox: nothing in it has been run against ABDM.
4. Open in Claude needs that app installed. It fills the composer and waits: nothing runs until you read it and press Enter.

## Journey 1: raising a consent request

```mermaid
sequenceDiagram
    autonumber
    participant S as Application/System
    participant CM as HIE-CM
    actor P as Patient (PHR app)
    Note over S: Every call carries REQUEST-ID, TIMESTAMP,<br/>X-CM-ID, X-HIU-ID and the gateway access token
    S->>CM: POST /api/hiecm/consent/v3/request/init<br/>consent {purpose.code, patient.id (ABHA address),<br/>hiu.id, requester {name, identifier}, hiTypes,<br/>permission {accessMode, dateRange, dataEraseAt,
    CM-->>S: 202 Accepted
    CM-)S: callback POST {bridgeUrl}/api/v3/hiu/consent/request/on-init<br/>consentRequest.id, response.requestId
    Note over S: Store consentRequest.id against<br/>the requester and the patient
    CM-)P: Consent request shown in the PHR app
    S->>CM: POST /api/hiecm/consent/v3/request/status<br/>consentRequestId, to poll while the patient decides
    CM-)S: callback POST {bridgeUrl}/api/v3/hiu/consent/request/on-status<br/>consentRequest {id, status REQUESTED, GRANTED,<br/>DENIED, REVOKED or EXPIRED}
```

- An HIU requests access to a patient's health data by sending a consent request with the patient's ABHA address via the HIE-CM.
- The HIE-CM acknowledges the request and returns a Consent Request ID through the Gateway.
- The patient is notified by the HIE-CM and can review, approve, or deny the consent request.
- The HIE-CM then communicates the patient's consent status back to the HIU through the Gateway.

The consent request ID is the handle for everything that follows. Store it against the requester and the patient.

## Journey 2: the patient grants or denies

```mermaid
sequenceDiagram
    autonumber
    actor P as Patient (PHR app)
    participant CM as HIE-CM
    participant S as Application/System
    P->>CM: Reviews the request, sets the date range and expiry
    alt Patient grants
        P->>CM: Grants
        CM->>CM: Creates one consent artefact per HIP covered
        CM-)S: callback POST {bridgeUrl}/api/v3/hiu/consent/request/notify<br/>notification {consentRequestId, status GRANTED,<br/>consentArtefacts [id]}
        S->>CM: POST /api/hiecm/consent/v3/request/hiu/on-notify<br/>acknowledgement [{status OK,<br/>consentId} per artefact], response.requestId
        Note over CM: The HIP is notified on its own bridge<br/>at /api/v3/consent/request/hip/notify
    else Patient denies
        P->>CM: Denies
        CM-)S: callback POST {bridgeUrl}/api/v3/hiu/consent/request/notify<br/>notification {consentRequestId, status DENIED}
        S->>CM: POST /api/hiecm/consent/v3/request/hiu/on-notify<br/>acknowledgement, response.requestId
    end
    Note over P,S: Revocation or expiry arrives later on the same<br/>callback, status REVOKED or EXPIRED. Stop using the data.
```

- If the request is approved, the HIE-CM shares the consent artefact IDs generated for that request with the HIU.
- If the request is denied, the HIE-CM notifies the HIU that the consent request has been rejected.

* A consent grant is valid for a specific period decided by the patient.
* One consent grant may generate multiple consent artefacts, so all consent artefact IDs should be stored.
* If the patient revokes consent or it expires, access to the health information must be stopped.

## Journey 3: fetching the records

```mermaid
sequenceDiagram
    autonumber
    participant S as Application/System
    participant CM as HIE-CM
    participant H as HIP
    S->>CM: POST /api/hiecm/consent/v3/fetch<br/>consentId
    CM-)S: callback POST {bridgeUrl}/api/v3/hiu/consent/on-fetch<br/>consent {status, consentDetail {hip, careContexts,<br/>hiTypes, permission.dateRange}, signature}
    S->>S: Generates an ECDH key pair on Curve25519<br/>and a 32 byte nonce for this transaction
    S->>CM: POST /api/hiecm/data-flow/v3/health-information/request<br/>hiRequest {consent.id, dateRange {from, to},<br/>dataPushUrl, keyMaterial {cryptoAlg ECDH,<br/>curve Curve25519, dhPublicKey {expiry, parameters,
    CM-)S: callback POST {bridgeUrl}/api/v3/hiu/health-information/on-request<br/>hiRequest {transactionId, sessionStatus REQUESTED},<br/>response.requestId
    CM->>H: Forwards the request to the HIP on its bridge
    H->>S: POST dataPushUrl<br/>pageNumber, pageCount, transactionId,<br/>entries [content (encrypted FHIR bundle), checksum,<br/>careContextReference],
    S->>S: Derives the shared key from the HIP keyMaterial,<br/>decrypts and verifies each entry
    S->>CM: POST /api/hiecm/data-flow/v3/health-information/notify<br/>notification {consentId, transactionId,<br/>notifier {type HIU, id},<br/>statusNotification {sessionStatus DELIVERED or ERRORED,
    S->>CM: GET /api/hiecm/data-flow/v3/health-information/request/status/{transaction-id}<br/>to check a transfer that has not arrived
```

Using the consent artefact ID, the HIU fetches the consent artefact and requests the health information covered under that consent. The requested health data is then securely delivered to the data push URL provided by the HIU.

## Next

- The calls, callbacks and error codes: [M3 API reference](/docs/hiecm/v3/api/m3).
- The cases M3 is tested against: the certification pack NHA issues. Certification runs once, for the whole integration: [Go live](/docs/hiecm/v3/getting-started/going-live).
- Receive records a patient pushes from their app: [Patient record share](/docs/hiecm/v3/use-cases/patient-record-share).
- The next milestone: [M4 Registry Integration](/docs/hiecm/v3/milestones/m4).


---

# Milestone 4 (M4): Register Healthcare Professionals and Facilities

Milestone 4 is the Registries milestone, commonly referred to as NHPR (National Healthcare Professionals and Facilities Registry). It establishes the identity of healthcare professionals and the details of healthcare facilities within the ABDM ecosystem.

[Try the M4 APIs](/docs/hiecm/v3/api/m4)

[Every call in M4, one page each: the headers it needs, the payload it takes, the callback it triggers, and a request builder you can fire at the sandbox.](/docs/hiecm/v3/api/m4)

The Healthcare Professionals Registry (HPR) is a comprehensive repository of registered and verified healthcare professionals. It includes doctors from various Systems of Medicine, including Modern Medicine, Dentistry, Ayurveda, Unani, Siddha, Sowa-Rigpa and Homeopathy, as well as Nurses and Pharmacists delivering healthcare services across India. A healthcare professional registers on the Healthcare Professionals Registry (HPR) and is issued a unique [HPID](/docs/hiecm/v3/getting-started/glossary#hpid).

Health Facility Registry (HFR) is a comprehensive repository of health facilities across the country, covering both modern and traditional systems of medicine. It includes public and private health facilities such as hospitals, clinics, diagnostic laboratories, imaging centres, pharmacies, and other healthcare establishments. A healthcare facility is onboarded to the Health Facility Registry (HFR) and is issued a unique Facility ID.

Neither [HPR](/docs/hiecm/v3/getting-started/glossary#hpr) nor [HFR](/docs/hiecm/v3/getting-started/glossary#hfr) is responsible for moving health records. Instead, these registries establish who the healthcare professional is and what the healthcare facility is, providing a verified identity and facility layer for subsequent ABDM transactions and health-record flows.

## Relationship with M2 and M3

M2 and M3 require a Facility ID in the production environment. Milestone 4 provides the registry layer through which this Facility ID can be obtained. There are two primary routes for facility onboarding:

- **NHPR Portal:** Facilities can be registered directly through the NHPR portal.
- **M4 APIs:** Products can integrate with the M4 APIs to register.

## HPR and HFR dependency

The HP-ID registration comes first for the API-based facility onboarding flow. Facility onboarding requires an HPR token, which is associated with a healthcare professional having a valid HPID.

Key identifiers include:

- **HPID:** 14-digit identifier issued to a registered healthcare professional.
- **Facility ID:** 12-character identifier beginning with `IN`, issued to a registered healthcare facility.

## M4 scope and capabilities

| Capability             | Key output                                                                                                                                                                          | Target user                                                                                             |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| HPID creation          | A 14 digit HPID, issued after Aadhaar authentication                                                                                                                                | Doctors, nurses, pharmacists, and facility managers                                                     |
| Register professional  | A complete HPR profile, including qualifications, council registration, and current work details                                                                                    | Healthcare professionals after HP-ID creation                                                           |
| Facility onboarding    | A 12 character unique Facility ID for registration in the HFR                                                                                                                       | Hospitals, clinics, laboratories, imaging centres, pharmacies, blood banks, and other health facilities |
| Bridge linkage         | A link between a Facility ID and one or more bridges, each identified as a [HIP](/docs/hiecm/v3/getting-started/glossary#hip) or [HIU](/docs/hiecm/v3/getting-started/glossary#hiu) | A facility whose software is going live                                                                 |
| Search and master data | Facility search and nearby search                                                                                                                                                   | Anyone building either of the above                                                                     |

## Intended users

- **Facilities going live.** A facility must be registered in the HFR and have a bridge linked to it to share health information as a HIP or retrieve it as an HIU. For facilities that have implemented [M2 (Attach)](/docs/hiecm/v3/milestones/m2) or [M3 (Retrieve)](/docs/hiecm/v3/milestones/m3), M4 is the next step towards production readiness.
- **Professionals registering.** An HPR ID provides a verified professional identity within ABDM. Currently, registration is available for three categories: doctors, nurses and pharmacists.
- **Software acting for others.** An [HMIS](/docs/hiecm/v3/getting-started/glossary#hmis) or practice management product can drive these calls for its own customers.

## How HPR and HFR work together

HPR and HFR represent two connected parts of the healthcare ecosystem. HPR enables healthcare professionals to register and maintain their professional identity and profile, while HFR enables hospitals, clinics, laboratories, pharmacies, and other healthcare facilities to register and maintain their facility information.

Once a facility is registered in the HFR, healthcare professionals can link their professional profile to that facility as their place of work. Similarly, an HPR-registered professional can declare the HFR facility where they currently work. This creates a connection between who provides healthcare and where healthcare is provided, allowing professionals and facilities to be linked within the ABDM ecosystem.

## Build M4 with an AI coding assistant

The M4 skill gives an AI coding assistant this milestone as one file: every M4 call with its fields and identifiers. Install it, or open it in your assistant in one click.

M4 agent skill

Every M4 call in one file: 100 operations.

[SKILL.md](/skills/abdm-m4/SKILL.md "The router. Use the command below to take the references with it.")

- ScaffoldThe loop that builds the module flow by flow against the sandbox, ending on an observed result rather than on a call returning 200.
- Integrate104 operations, with their hosts and headers.
- DebugNo error code is recorded yet.

`mkdir -p .claude/skills/abdm-m4/references && curl -fsSL https://nhcx.sbxstage.in/skills/abdm-m4/SKILL.md -o .claude/skills/abdm-m4/SKILL.md && for f in scaffold integrate debug; do curl -fsSL https://nhcx.sbxstage.in/skills/abdm-m4/references/$f.md -o .claude/skills/abdm-m4/references/$f.md; done`

[Open in Claude](claude://code/new?q=Install%20the%20ABDM%20M4%20agent%20skill%20into%20this%20project%2C%20then%20help%20me%20use%20it.%0A%0ARun%20this%3A%0Amkdir%20-p%20.claude%2Fskills%2Fabdm-m4%2Freferences%20%26%26%20curl%20-fsSL%20https%3A%2F%2Fnhcx.sbxstage.in%2Fskills%2Fabdm-m4%2FSKILL.md%20-o%20.claude%2Fskills%2Fabdm-m4%2FSKILL.md%20%26%26%20for%20f%20in%20scaffold%20integrate%20debug%3B%20do%20curl%20-fsSL%20https%3A%2F%2Fnhcx.sbxstage.in%2Fskills%2Fabdm-m4%2Freferences%2F%24f.md%20-o%20.claude%2Fskills%2Fabdm-m4%2Freferences%2F%24f.md%3B%20done%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

Drops the skill into this project. Claude loads it when a task matches.

How to use it

1. Run the command above in the repository you are integrating.
2. Ask your agent for the job in your own words. "Onboard this facility to the HFR and link its HIP bridge". The skill loads when the task matches it.
3. Check what it writes against these pages. The skill carries the facts, not the sandbox: nothing in it has been run against ABDM.
4. Open in Claude needs that app installed. It fills the composer and waits: nothing runs until you read it and press Enter.

## Certification

M4 does not have a separate certification process. A single exit process covers the complete integration and is conducted once all the required milestones for your role are working end to end.

The [Going live](/docs/hiecm/v3/getting-started/going-live) process outlines the four steps involved and the requirements for each step. The cases used for certification are covered under the M4 testing use cases, in [Developer resources](/docs/hiecm/v3/resources).

## The journey, step by step

Milestone 4 (M4) of [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm) covers the following key journeys:

- **HP-ID Creation and Role Selection.** A healthcare professional completes Aadhaar authentication and creates an HP-ID ([HPID](/docs/hiecm/v3/getting-started/glossary#hpid)). The professional then selects the required role: [HPR](/docs/hiecm/v3/getting-started/glossary#hpr), [HFR](/docs/hiecm/v3/getting-started/glossary#hfr), or Both.
- **HPR Registration.** If HPR is selected, the professional completes the required details, including personal details, qualification details, registration details and work details.
- **HFR Registration.** If HFR is selected, the professional completes the Health Facility Registry (HFR) registration form with the required facility details.
- **HPR + HFR Registration.** If Both is selected, the professional completes the HFR registration followed by the HPR registration.
- **Facility Software Integration.** A registered facility can link its Bridge to the Facility ID, enabling it to publish health records as a [HIP](/docs/hiecm/v3/getting-started/glossary#hip) and retrieve records as an [HIU](/docs/hiecm/v3/getting-started/glossary#hiu) through its software.

| Journey      | Sequence                                                                                                                                                    |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HPR Journey  | Aadhaar Authentication → Role Selection → HP-ID Creation → HPR Registration                                                                                 |
| HFR Journey  | Aadhaar Authentication → Role Selection → HP-ID Creation → HFR Registration → Facility Software Integration as HIP/HIU, where applicable                    |
| Both Journey | Aadhaar Authentication → Role Selection → HP-ID Creation → HFR Registration → HPR Registration → Facility Software Integration as HIP/HIU, where applicable |

## Journey 1: creating an HPID for a professional

### Aadhaar authentication

```mermaid
sequenceDiagram
    autonumber
    actor P as Professional
    participant S as Your system
    participant H as HPR service
    Note over S: Base URL https://apihspsbx.abdm.gov.in/v4/int,<br/>with Authorization Bearer from POST /api/hiecm/gateway/v3/sessions
    S->>H: POST /aadhaar/generateLink<br/>scopes, source
    H-->>S: txnId, redirect URL (valid five minutes)
    S->>P: Redirect to the hosted Aadhaar page
    P->>H: Enters the Aadhaar number, verifies the Aadhaar OTP
    loop Until authenticated or the URL expires
        S->>H: POST /aadhaar/isAuthenticated<br/>txnId
        H-->>S: true or false
    end
    S->>H: POST /v2/registration/aadhaar/verifyOTP<br/>txnId
    H-->>S: name, gender, birthdate, photo,<br/>mobileNumber (masked), pincode
    S->>H: POST /v1/registration/aadhaar/checkHpIdAccountExist<br/>txnId
    H-->>S: hprIdNumber and token if an HP-ID exists, else none
```

The professional authenticates using Aadhaar. The integrating system does not handle the Aadhaar number or [OTP](/docs/hiecm/v3/getting-started/glossary#otp). Instead, it handles the transaction ID and redirects the user to the URL returned by the HPR service.

The URL is valid for five minutes. If it expires before authentication is completed, call Generate Aadhaar Link again to obtain a new authentication URL. After authentication the professional selects the role to register for: HPR, HFR, or both.

### Login using Mobile number and OTP or credentials

```mermaid
sequenceDiagram
    autonumber
    participant S as Your system
    participant H as HPR service
    alt An HP-ID exists for this Aadhaar
        S->>H: POST /api/v1/auth/authPassword, or<br/>POST /api/v2/auth/loginViaMobileSendOTP
        H-->>S: Token, the professional is logged in
    else No HP-ID yet
        S->>H: POST /v2/registration/aadhaar/demographicAuthViaMobile<br/>txnId, mobileNumber (encrypted with the key<br/>from GET /api/v1/auth/cert)
        H-->>S: verified true or false
        opt verified is false
            S->>H: POST /v1/registration/aadhaar/generateMobileOTP<br/>mobile, txnId
            H-->>S: txnId, OTP sent
            S->>H: POST /v1/registration/aadhaar/verifyMobileOTP<br/>otp, txnId
            H-->>S: Mobile number verified
        end
        S->>H: POST /v1/registration/aadhaar/hpid/suggestion<br/>txnId
        H-->>S: Suggested HP-IDs
        S->>H: POST /v2/registration/aadhaar/createHprIdWithPreVerified<br/>txnId, idType hpr_id, domainName, email,<br/>name, password
        H-->>S: HP-ID created, hprToken
        S->>H: POST /profile/updateRole<br/>hprId, category and sub-category:<br/>the role, HPR, HFR or Both
        H-->>S: Role recorded. HPR continues in Journey 2,<br/>HFR in Journey 3, Both does HFR then HPR
    end
```

If an HP-ID already exists, the professional is already registered. The system should authenticate the professional and proceed directly to login, skipping the HP-ID creation journey.

A returning professional can also log in without Aadhaar authentication using either a Mobile OTP, or a Password. Both login mechanisms are covered under the M4 Operations and Fields: see [HPR authentication](/docs/hiecm/v3/api/m4/endpoints/m4-authentication/01-m4-post-v1-auth-authpassword) in the M4 API reference.

If no HP-ID exists, the mobile number must be verified before creating the HP-ID.

1. Fetch the public certificate from `/v4/int/api/v1/auth/cert`.
2. Encrypt the mobile number using `RSA/ECB/PKCS1Padding`.
3. Send the encrypted value in the API request.

Create HPID returns a `token`. The register professional call carries an `hprToken` in its payload.

## Journey 2: registering a professional on HPR

```mermaid
sequenceDiagram
    autonumber
    participant S as Your system
    participant H as HPR service
    Note over S: Holds the HPR token from Journey 1
    S->>H: GET /apis/v1/masters/medical-councils, courses,<br/>colleges, universites, states, district, languages
    H-->>S: Code lists
    S->>H: POST /apis/v1/doctors/register-professional-new<br/>hprToken, practitioner {healthProfessionalType,<br/>officialMobile, officialEmail, personal,<br/>qualification,
    H-->>S: hprId, referenceNumber, status
    S->>H: POST /apis/v1/doctors/fetch-documents-list<br/>hprid
    H-->>S: documentList {profileDetails, qualificationDetails,<br/>registrationDetails}
    S->>H: POST /apis/v1/uploads/upload-document<br/>hpr_token, document [document_id, document_type,<br/>fileType, data]
    H-->>S: degreeCertificate, registrationCertificate,<br/>proofOfWorkCertificate {status, msg}
    S->>H: POST /apis/v1/doctors/fetch-professional-info<br/>practitioner {id}
    H-->>S: practitioners [identifier, registrations,<br/>qualifications, hpr_id]
```

The HP-ID is an identity, not a professional profile. The professional profile is created through the registration process, which captures details such as qualifications, council registration, and current work information. Professional registration requires the HPR Token returned from Journey 1.

The following documents are mandatory for upload: the qualification degree certificate, and the registration certificate. A proof of work certificate is mandatory for professionals working in government, or in both government and private settings.

The registration API requires codes rather than names. Therefore, the application must first fetch the relevant master data through the respective master APIs and use the corresponding codes during registration. Master data includes council, course, college, university, state, district and language.

## Journey 3: onboarding a facility to the HFR

```mermaid
sequenceDiagram
    autonumber
    actor M as Facility manager (HP-ID)
    participant S as Your system
    participant H as HFR service
    M->>S: Logs in with HPR credentials
    Note over S: Holds the HPR token, sent as x-hprid-auth
    S->>H: POST /search/address/filter/deduplicate<br/>name, address, district, subDistrict, village,<br/>geolocation
    H-->>S: Matching facilities, if any
    Note over S,H: Stop here if the facility is already registered
    S->>H: POST /v1.5/facility/basic-information<br/>header x-hprid-auth,<br/>facilityInformation {facilityName,<br/>facilityAddressDetails (LGD codes),
    H-->>S: trackingId (the Facility ID,<br/>masked until submission), status
    S->>H: POST /v1.5/facility/additional-information<br/>trackingId, linkedProgramIds {nin, abpmjayId,<br/>rohiniId, echsId, cghsId},<br/>generalInformation {hasPharmacy, hasBloodBank,
    H-->>S: trackingId, status
    S->>H: POST /v1.5/facility/detailed-information<br/>trackingId, specialities [systemOfMedicineCode,<br/>specialities],<br/>medicalInfrastructure (bed and ventilator counts)
    H-->>S: trackingId, status
    S->>H: POST /v1.5/facility/submit-facility<br/>headers x-hprid-auth, x-hprid-auth-verifier,<br/>trackingId, sourceOfInformation, facilitySuperUser
    H-->>S: Facility submitted for verification,<br/>Facility ID visible once approved
```

Onboarding consists of one search, three updates, and a final submission, with each update adding another layer of facility details. If you stop before submission, the facility remains in Draft status and is not visible on ABDM.

The first update captures the basic facility information and creates a Facility ID. The Facility ID is retained throughout the onboarding flow, but remains masked until the facility is fully submitted. Once submission is complete, the Facility ID becomes visible. The API returns it as `trackingId`, and that is the value every later update carries.

### What each update carries

| Call                       | Information captured                                                                                                                                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Basic facility information | Facility name, ownership, system of medicine, facility type and subtype, address with LGD codes, contact details, board and building photographs, and operating hours                                         |
| Additional information     | Availability of services and units such as a pharmacy, blood bank, dialysis centre, cath lab, diagnostic laboratory, or imaging centre, along with scheme identifiers such as ABPMJAY, ROHINI, ECHS, and CGHS |
| Detailed information       | Specialities by system of medicine, bed and ventilator counts, and applicable sections for pharmacy, blood bank, diagnostic laboratory, and imaging services, based on the facility type                      |
| Submit facility            | Captures the tracking ID and optional source of information, and moves the facility application out of Draft status                                                                                           |

The mandatory fields under detailed information vary based on the facility type, service type, and system of medicine selected during registration. Diagnostic laboratories, imaging centres, blood banks and pharmacies do not require medical infrastructure counts, such as bed or ventilator counts.

### OTP based facility verification

```mermaid
sequenceDiagram
    autonumber
    participant S as Your system
    participant H as HFR service
    S->>H: POST /v1.5/facility/sendOtpToContact<br/>facilityId
    H-->>S: transactionId,<br/>OTP sent to the facility contact number
    S->>H: POST /v1.5/facility/validateOtp<br/>facilityId, sourceId, otp, source, transactionId
    H-->>S: Validation result
```

A shorter verification flow is available for government programmes. An OTP is sent to the contact number registered against the Facility ID, which is then validated to complete verification.

## Journey 4: linking bridges to a facility

### Facility-Bridge linkage

```mermaid
sequenceDiagram
    autonumber
    participant S as Your system
    participant H as HFR service
    Note over S: Facility ID, 12 characters beginning with IN,<br/>bridgeId from your sandbox registration
    S->>H: POST /v1/bridges/MutipleHRPAddUpdateServices<br/>facilityId, facilityName, HRP [{bridgeId,<br/>hipName (15 characters or fewer,<br/>unique per facility), type HIP or HIU, active true}]
    H-->>S: Linkage result per bridge
    Note over S,H: One call carries every bridge for the facility. Repeat it to add a bridge or set active false.
```

A Facility ID alone does not enable health record exchange. The facility must be linked to a bridge, with each linkage designated as either a HIP or an HIU.

- A single facility can be linked to multiple bridges.
- A single bridge can be linked to multiple facilities. See [one bridge, many facilities](/docs/hiecm/v3/concepts/how-it-fits#one-bridge-many-facilities).
- The HIP/HIU role is defined for each facility-Bridge linkage.
- Integration-level configurations are set once, while facility-specific configurations are maintained separately for each linked facility.

The HIP name is the name displayed to patients in their [ABHA](/docs/hiecm/v3/getting-started/glossary#abha) or [PHR](/docs/hiecm/v3/getting-started/glossary#phr) app when they search for a hospital. The following rules apply to the HIP name:

- Maximum 15 characters
- No special characters
- Must be unique for every Bridge linked to the same facility

For example, the HIP name can be derived by combining the hospital name and Bridge name, while ensuring that the above naming rules are met.

A facility with a Facility ID and a linked HIP bridge can perform [M2](/docs/hiecm/v3/api/m2) activities, including linking care contexts and sharing health records. A facility with a linked HIU bridge can perform [M3](/docs/hiecm/v3/api/m3) activities, including requesting patient consent and fetching health records. M4 covers the registration of the facility and the healthcare professionals working at the facility.

Next: [M4 API reference](/docs/hiecm/v3/api/m4).

## Next

- The base URLs and the operation list: [M4 API reference](/docs/hiecm/v3/api/m4).
- The patient side of all four: [P1 Identity and profile](/docs/hiecm/v3/milestones/p1).
- Take your integration to production: [Go live](/docs/hiecm/v3/getting-started/going-live).


---

# P1 Identity and login

P1 is the patient side of [M1 Identity](/docs/hiecm/v3/milestones/m1). M1 is how a hospital system creates an [ABHA](/docs/hiecm/v3/getting-started/glossary#abha). P1 is how the patient's own [PHR](/docs/hiecm/v3/getting-started/glossary#phr) app does it, and how it maintains the account afterwards.

[Try the P1 APIs](/docs/hiecm/v3/api/p1/endpoints/p1-certificate-and-session/01-p1-get-v3-phr-app-login-public-certificate)

[Every call in P1, one page each: the headers it needs, the payload it takes, the callback it triggers, and a request builder you can fire at the sandbox.](/docs/hiecm/v3/api/p1/endpoints/p1-certificate-and-session/01-p1-get-v3-phr-app-login-public-certificate)

[Error codes](/docs/hiecm/v3/api/p1/errors)

[What each code P1 returns actually means, and the first thing to check when you see one.](/docs/hiecm/v3/api/p1/errors)

## In short

- Every user needs an ABHA address, `username@abdm`. Consent, notifications and record sharing all hang off it.
- Build both creation paths: by mobile number, and by an existing 14 digit ABHA number.
- Every login route is mandatory.
- Fetch the PHR public key first. It is not the ABHA service's key.
- A user can hold several ABHA addresses but only one ABHA number.

## What you build

Registration and login. The profile the patient reads and edits is [P2](/docs/hiecm/v3/milestones/p2).

## Creating an ABHA address

```mermaid
flowchart TD
    A["User picks a path"] --> B{"Mobile number, ABHA number or Aadhaar number?"}
    B -- "Mobile number" --> C["Verify by mobile OTP"]
    C --> D["User types first name, year of birth, gender, address, state, district, pin code"]
    B -- "ABHA number" --> E["Verify by Aadhaar OTP or ABHA OTP"]
    E --> F["Profile details come back from the ABHA system"]
    B -- "Aadhaar number" --> K["Create an ABHA number by Aadhaar OTP"]
    K --> F
    D --> G["Show the ABHA addresses already linked to this mobile or number"]
    F --> G
    G --> H{"An address already exists?"}
    H -- "Yes" --> I["User picks one"]
    H -- "No" --> J["User creates a new address"]
```

A person does not need an [ABHA number](/docs/hiecm/v3/getting-started/glossary#abha-number), and does not need Aadhaar, to get an ABHA address here. A mobile number and the OTP sent to it are enough. What that buys is a Self-Declared profile: an address the network can route to, with no [KYC](/docs/hiecm/v3/getting-started/glossary#kyc) behind it and no ABHA number until the person links one later.

| Path                                    | Validated by                                              | Profile details             | Result                                                               |
| --------------------------------------- | --------------------------------------------------------- | --------------------------- | -------------------------------------------------------------------- |
| Mobile number                           | Mobile [OTP](/docs/hiecm/v3/getting-started/glossary#otp) | The user types them         | Self-Declared, no [KYC](/docs/hiecm/v3/getting-started/glossary#kyc) |
| 14 digit ABHA number                    | Aadhaar OTP or ABHA OTP                                   | Returned by the ABHA system | KYC Verified                                                         |
| Aadhaar number, with no ABHA number yet | Aadhaar OTP, which creates the ABHA number first          | Returned by the ABHA system | KYC Verified                                                         |

After validation on any path, show the ABHA addresses already linked to that mobile number or ABHA number. The user then picks one instead of creating a duplicate.

A Self-Declared profile needs a "Link ABHA number" action. The user enters the 14 digit number and validates by Aadhaar OTP or ABHA OTP. Profile details then follow the ABHA number, and the status changes to KYC Verified.

## Login

Sign a user in to a PHR application by any of these routes. Every route is mandatory.

| Route                          | Validated by                                                     |
| ------------------------------ | ---------------------------------------------------------------- |
| Mobile number                  | Mobile OTP                                                       |
| An address such as `name@abdm` | Password or mobile OTP, by the auth methods the address supports |
| The 14 digit ABHA number       | ABHA OTP or Aadhaar OTP                                          |
| The Aadhaar number             | Aadhaar OTP                                                      |

Every OTP route returns the ABHA addresses linked to that identifier. The user picks the one to sign in as, and you confirm the choice with the verify user call.

Resend OTP unlocks after 60 seconds in every flow. You also need a reset password screen behind login, secure storage of the refresh token, and more than one user profile per install with sign in and sign out.

## Tokens and base URLs

| Token or URL                          | Value                                              |
| ------------------------------------- | -------------------------------------------------- |
| Gateway session token                 | Valid for 20 minutes                               |
| User token from login                 | Valid for 30 minutes                               |
| Refresh token                         | Valid for 15 days                                  |
| PHR APIs, sandbox                     | `https://abhasbx.abdm.gov.in/abha/api/v3/phr/app/` |
| PHR APIs, production                  | `https://apis.abdm.gov.in/phr/api/phr/app/v3/`     |
| ABHA address verification, sandbox    | `https://abhasbx.abdm.gov.in/abha/api/v3/phr/web`  |
| ABHA address verification, production | `https://phr.abdm.gov.in/api/phr/web/v3`           |

Encrypt the Aadhaar number, mobile number, OTP and password with the PHR public key from `GET /abha/api/v3/phr/app/login/public/certificate`. It is a different key from the ABHA service's, so fetch it before any other PHR call.

## Next

- The calls and base URLs: [P1 API reference](/reference/hiecm-p1).
- The next milestone: [P2 Linking and records](/docs/hiecm/v3/milestones/p2).


---

# P2 Linking and records

P2 is the mirror of [M2 Health Information Provider](/docs/hiecm/v3/milestones/m2). M2 is a provider publishing a record. P2 is the patient discovering it and linking it to their own [ABHA address](/docs/hiecm/v3/getting-started/glossary#abha-address).

[Try the P2 APIs](/docs/hiecm/v3/api/p2/endpoints/p2-abdm-hiecm-patient-share-phr/01-p2-post-patient-share-v3-share)

[Every call in P2, one page each: the headers it needs, the payload it takes, the callback it triggers, and a request builder you can fire at the sandbox.](/docs/hiecm/v3/api/p2/endpoints/p2-abdm-hiecm-patient-share-phr/01-p2-post-patient-share-v3-share)

[Error codes](/docs/hiecm/v3/api/p2/errors)

[What each code P2 returns actually means, and the first thing to check when you see one.](/docs/hiecm/v3/api/p2/errors)

## In short

- Discovery is for facilities the user visited without giving an ABHA address, and for old records.
- A [HIP](/docs/hiecm/v3/getting-started/glossary#hip) is expected to answer a discovery request within 10 seconds.
- Never show a [care context](/docs/hiecm/v3/getting-started/glossary#care-context) that is already linked.
- Send the data transfer request within 5 minutes of the user tapping Pull Records.

## What you build

Profile management, care context linking, user initiated linking, scan and share at a facility, and health locker subscriptions.

## Scan and share at a facility

The facility displays a QR code holding a URL with two parameters: the HIP ID and a facility defined context such as a counter code. Your app scans it, then:

1. Shows the user what will be shared.
2. Takes consent in the specified wording. It covers sharing the ABHA address and profile with that facility for registration, and the facility linking any records it generates.
3. Calls the [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm) to share the details.
4. Waits for the facility, currently expected to respond within 30 seconds.
5. Displays the token number if the facility returned one.

Counter names arrive in the QR code: 1 to 250 characters, letters, digits and spaces, with `.`, `-` and `_` allowed between them. A counter name cannot be the facility ID, the [HPID](/docs/hiecm/v3/getting-started/glossary#hpid), the HIP ID or the HIP name.

## Discovery and user initiated linking

The user searches for the facility by name. Only participating facilities appear, and the facility must be a HIP linked to an [HRP](/docs/hiecm/v3/getting-started/glossary#hrp). Your app sends a discovery request carrying the HIP ID and unverified identifiers of type `MR`, `MOBILE`, `ABHA_NUMBER` or `ABHA_ADDRESS`.

The user selects care contexts and confirms. The HIP sends an [OTP](/docs/hiecm/v3/getting-started/glossary#otp) to the registered mobile number, and on successful verification the care contexts link to the ABHA address.

The same flow works for government health programmes such as CoWIN, AB-PMJAY, e-Sanjeevani OPD, e-Sanjeevani HWC and RCH, each with a programme specific optional field.

Three failures have specified copy.

| Situation                           | Message                                                                                                   |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
| The HIP is unreachable              | "Couldn't Connect: We are sorry. Unable to contact your hospital. Please try again later"                 |
| The user never visited the facility | "No health records found"                                                                                 |
| Everything is already linked        | "No new health record to link: Records of all visits are already linked and there is nothing new to link" |

Records should arrive within 2 hours.

## Where the citizen is the HIP

A citizen pushing a record into your app is the HIP. A health locker, where users upload their own records, puts you on that publishing side.

An uploaded record is shareable once you hold three things: a link token from the generate link token call, a care context added by HIP initiated linking from [M2 Attach](/docs/hiecm/v3/milestones/m2), and the M2 health information transfer APIs.

Set the health information type from the contents or from user input. Use `HealthDocumentRecord` when it cannot be determined.

## Profile, card and QR code

The signed in user manages their own profile from your app. Every call takes the user token from login as `X-token`.

| Element                  | What it holds                                                                                                                                   |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Profile screen           | Editable demographics, marked KYC Verified or Self-Declared                                                                                     |
| ABHA number              | Visible only on a KYC Verified profile                                                                                                          |
| ABHA address card, a PDF | Photo, full name, ABHA number, ABHA address, QR code, date of birth, gender, mobile number                                                      |
| Editable, KYC Verified   | Mobile number, with an OTP to the new number, and address                                                                                       |
| Editable, Self-Declared  | The same, plus photo, full name, gender and date of birth                                                                                       |
| Also on the profile      | Update the password, link an ABHA number by mobile OTP or Aadhaar OTP, switch between the profiles on one login, refresh the token, and log out |

## Next

- The calls and base URLs: [P2 API reference](/reference/hiecm-p2).
- The next milestone: [P3 Consent and notifications](/docs/hiecm/v3/milestones/p3).


---

# P3 Consent and notifications

P3 is the other side of [M3 Health Information User](/docs/hiecm/v3/milestones/m3). M3 is a requester asking for records. P3 is the patient deciding, and being told each time.

A citizen fetching records is the [HIU](/docs/hiecm/v3/getting-started/glossary#hiu), so every [PHR](/docs/hiecm/v3/getting-started/glossary#phr) application must implement that side.

[Try the P3 APIs](/docs/hiecm/v3/api/p3/endpoints/p3-subscription-hiu/01-p3-post-subscription-requests-v3-init)

[Every call in P3, one page each: the headers it needs, the payload it takes, the callback it triggers, and a request builder you can fire at the sandbox.](/docs/hiecm/v3/api/p3/endpoints/p3-subscription-hiu/01-p3-post-subscription-requests-v3-init)

[Error codes](/docs/hiecm/v3/api/p3/errors)

[What each code P3 returns actually means, and the first thing to check when you see one.](/docs/hiecm/v3/api/p3/errors)

## In short

- Build for revocation from the start. A consent that worked yesterday can be withdrawn today, and that is the system working correctly.
- A subscription is how your app hears about changes to a user's ABHA address. Set one up at address creation and at first login on a new install.
- An auto approval policy stops the user approving a request every time a hospital adds a record.
- The user must be able to disable a policy at any time.

## Subscriptions and notifications

Ask the user for consent before you create a subscription. An approved subscription notifies your app when a care context is linked or updated. Surface these as device notifications.

You need screens to list subscriptions, approve them, deny them and edit them. Editing covers health information types, purpose, categories and the time period.

## Auto approval: subscribe once, approve every time

1. Ask the user to confirm your app may retrieve new linked records automatically.
2. Set up an auto approval policy with the [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm).

While the policy is active, the consent request you raise on a new or updated care context notification is granted immediately, and you fetch and store the record. Disable the policy and a request arrives for each record instead.

## Consent management

| Capability           | What it covers                                                       |
| -------------------- | -------------------------------------------------------------------- |
| View requests        | Requesting HIU, purpose, data types, date range, validity, status    |
| Modify a request     | Access duration, record date range, data categories, validity period |
| Grant or deny        | The decision goes back to the HIE-CM                                 |
| View active consents | Who currently has access, and to what                                |
| Revoke               | Withdraw at any time. Sharing under that consent stops immediately   |

The Consents tab and the Subscriptions tab group state the same way: a Requests section holding Requested, Denied and Expired, and an Approved section holding Granted and Revoked.

## Fetching and displaying records

Once a care context is linked to the user's ABHA address:

1. Your app receives the notification.
2. It creates a consent request for that record and sends it to the HIE-CM.
3. The consent is granted, automatically if a policy exists, otherwise by the user.
4. It raises a health information request with the approved [consent artefact](/docs/hiecm/v3/getting-started/glossary#consent-artefact).
5. The [HIP](/docs/hiecm/v3/getting-started/glossary#hip) sends the records across the network.
6. Your app stores them for long term access and displays them, preferably in chronological order.

## Next

- The calls and base URLs: [P3 API reference](/reference/hiecm-p3).
- Back to the four provider milestones: [Milestones](/docs/hiecm/v3/milestones).
- Take your integration to production: [Go live](/docs/hiecm/v3/getting-started/going-live).


---

# Authentication

Generated from the specifications. Every scheme and header below is declared in one of them.

## Gateway session

**bearerAuth**, `http` `bearer`. The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer `prefix.

## M1 Identity

**bearerAuth**, `http` `bearer`. The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer `prefix.

## M2 Health Information Provider

**bearerAuth**, `http` `bearer`. The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer `prefix.

## M3 Health Information User

**bearerAuth**, `http` `bearer`. The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer `prefix.

## M4 Registry Integration

**bearerAuth**, `http` `bearer`. M4 declares bearer authentication. The HPID calls publish POST /getManagementToken.

## P1 Registration and login

**bearerAuth**, `http` `bearer`. The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer `prefix.

## P2 Consents Management

**bearerAuth**, `http` `bearer`. The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer `prefix.

## P3 Subscription

**bearerAuth**, `http` `bearer`. The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer `prefix.

## P4 Locker

**bearerAuth**, `http` `bearer`. The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer `prefix.

## Scan and Register

**bearerAuth**, `http` `bearer`. The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer `prefix.

## Patient scan and record share

**bearerAuth**, `http` `bearer`. JWT access token issued by the ABDM session API after successful validation of client id and secret.

| Header         | Required | What it is                                                                                                                                |
| -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `REQUEST-ID`   | yes      | Random UUID, a v4 style guid, unique per request.                                                                                         |
| `TIMESTAMP`    | yes      | ISO 8601 timestamp of when the request was initiated.                                                                                     |
| `X-HIU-ID`     | yes      | Identifier of the health information user to which the request was intended.                                                              |
| `X-CM-ID`      | yes      | Suffix of the consent manager to which the request was intended. sbx in the sandbox, abdm in production.                                  |
| `X-AUTH-TOKEN` | yes      | JWT access token issued by the PHR service after successful user authentication. If the HIP does not have any role, then it is mandatory. |
| `request-id`   | yes      | Random UUID, a v4 style guid, unique per callback.                                                                                        |
| `timestamp`    | yes      | ISO 8601 timestamp of when the callback was sent.                                                                                         |
| `x-hiu-id`     | yes      | Identifier of the health information user to which the request was intended.                                                              |

## Scan and Pay

**bearerAuth**, `http` `bearer`. The access token from POST /api/hiecm/gateway/v3/sessions, sent with a `Bearer `prefix.


---

# Error codes

Seeing a symptom rather than a code? Start at [Troubleshooting](/docs/hiecm/v3/troubleshooting/).

A code is on this page because a response example in a specification returns it.

## M1 Identity

| Code        | HTTP | Message                                                                                                                         | Returned by                                                        |
| ----------- | ---- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `404`       | 404  | Runtime Error                                                                                                                   | `m1_post_v3_profile_login_verify_find_abha_face`                   |
| `900900`    | 500  | Unclassified Authentication Failure                                                                                             | `m1_post_v3_enrollment_auth_byabdm_mobile_verify_create_ab_091285` |
| `900901`    | 401  | Invalid Credentials                                                                                                             | `m1_post_v3_enrollment_request_otp_aadhaar_otp`                    |
| `900902`    | 401  | Missing Credentials                                                                                                             | `m1_post_v3_profile_benefit_search_xmluid`                         |
| `ABDM-1017` | 401  | Invalid Transaction Id                                                                                                          | `m1_get_v3_enrollment_enrol_suggestion_create_abha_aadhaar_otp`    |
| `ABDM-1021` | 401  | Lack of required priviledges                                                                                                    | `m1_post_v3_enrollment_enrol_byaadhaar_child_child_abha`           |
| `ABDM-1094` | 401  | X-token expired                                                                                                                 | `m1_post_v3_enrollment_enrol_byaadhaar_child_child_abha`           |
| `ABDM-1114` | 404  | User not found                                                                                                                  | `m1_patch_v3_profile_account_child_child_abha`                     |
| `ABDM-1124` | 422  | The mobile number provided by you is already linked to 6 ABHA Numbers. Please provide a different Mobile Number.                | `m1_post_v3_enrollment_enrol_byaadhaar_demo_auth_create_ab_81107d` |
| `ABDM-1138` | 400  | The benefit record has already been de-linked                                                                                   | `m1_post_v3_profile_benefit_linkanddelink_x_token`                 |
| `ABDM-1140` | 400  | The benefit record has already been linked                                                                                      | `m1_post_v3_profile_benefit_linkanddelink_x_token`                 |
| `ABDM-1157` | 422  | Child ABHA’s account limit has been exceeded for the requested Abha ID number ‘\<ABHA\_NUMBER>                                  | `m1_post_v3_enrollment_enrol_byaadhaar_child_child_abha`           |
| `ABDM-1160` | 422  | Non KYC CHILD ABHA is allowed to update their profile only once                                                                 | `m1_patch_v3_profile_account_child_child_abha`                     |
| `ABDM-1204` | 422  | UIDAI Error code : 400 : Invalid Aadhaar OTP value.                                                                             | `m1_post_v3_enrollment_enrol_byaadhaar_otp`                        |
| `ABDM-1207` | 422  | The information you provided does not match the details on record with Aadhaar. Please verify and provide accurate information. | `m1_post_v3_enrollment_enrol_byaadhaar_demo_auth_create_ab_81107d` |
| `ABDM-1211` | 400  | User not found.                                                                                                                 | `m1_post_v3_phr_web_login_abha_search_abha_address_login_m_27a20f` |
| `ABDM-1224` | 401  | Login via Biometric is not allowed.                                                                                             | `m1_post_v3_profile_login_request_otp_find_abha_face`              |

## M2 Health Information Provider

| Code        | HTTP | Message                                                                                                                                                    | Returned by |
| ----------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `ABDM-1000` |      | Unable to connect the database                                                                                                                             |             |
| `ABDM-1001` |      | No data found                                                                                                                                              |             |
| `ABDM-1004` |      | SMS Gateway is unavailable                                                                                                                                 |             |
| `ABDM-1006` |      | Bad Request, invalid request Body                                                                                                                          |             |
| `ABDM-1007` |      | Connection failed due to timeout                                                                                                                           |             |
| `ABDM-1008` |      | SMS service currently disabled                                                                                                                             |             |
| `ABDM-1010` |      | Validation failed                                                                                                                                          |             |
| `ABDM-1011` |      | Gateway database unavailable                                                                                                                               |             |
| `ABDM-1012` |      | No records found against the ABHA Address                                                                                                                  |             |
| `ABDM-1013` |      | Invalid ABHA Number                                                                                                                                        |             |
| `ABDM-1015` |      | Invalid Response                                                                                                                                           |             |
| `ABDM-1016` |      | Invalid TimeStamp                                                                                                                                          |             |
| `ABDM-1017` |      | Invalid TransactionId                                                                                                                                      |             |
| `ABDM-1018` |      | Share Profile database unavailable                                                                                                                         |             |
| `ABDM-1019` |      | Dependent Service Unavailable                                                                                                                              |             |
| `ABDM-1020` |      | Unknown database                                                                                                                                           |             |
| `ABDM-1022` |      | Too many requests                                                                                                                                          |             |
| `ABDM-1023` |      | Invalid User                                                                                                                                               |             |
| `ABDM-1024` |      | Dependent service unavailable                                                                                                                              |             |
| `ABDM-1025` |      | Invalid ServiceId                                                                                                                                          |             |
| `ABDM-1026` |      | Invalid Link Token                                                                                                                                         |             |
| `ABDM-1027` |      | You are blocked. Please try again after 24 hours.                                                                                                          |             |
| `ABDM-1028` |      | HIP is unavailable                                                                                                                                         |             |
| `ABDM-1029` |      | Redis server is unavailable                                                                                                                                |             |
| `ABDM-1030` |      | Invalid request ID                                                                                                                                         |             |
| `ABDM-1031` |      | Invalid request                                                                                                                                            |             |
| `ABDM-1032` |      | Invalid header                                                                                                                                             |             |
| `ABDM-1033` |      | HIU is unavailable                                                                                                                                         |             |
| `ABDM-1034` |      | Notification service unavailable                                                                                                                           |             |
| `ABDM-1035` |      | Invalid HIP ID                                                                                                                                             |             |
| `ABDM-1036` |      | Data does not matched                                                                                                                                      |             |
| `ABDM-1037` |      | Counter and Care context count mismatch                                                                                                                    |             |
| `ABDM-1038` |      | ABHA address and Link token mismatch                                                                                                                       |             |
| `ABDM-1040` |      | Invalid HIU ID                                                                                                                                             |             |
| `ABDM-1041` |      | Invalid Acknowledgement                                                                                                                                    |             |
| `ABDM-1042` |      | Provider Mandatory                                                                                                                                         |             |
| `ABDM-1043` |      | ABHA Address does not match with KYC details.                                                                                                              |             |
| `ABDM-1044` |      | Broadcast Failed                                                                                                                                           |             |
| `ABDM-1045` |      | Database Access is restricted                                                                                                                              |             |
| `ABDM-1046` |      | Invalid Purpose                                                                                                                                            |             |
| `ABDM-1047` |      | Purpose does not exist                                                                                                                                     |             |
| `ABDM-1048` |      | Timeout                                                                                                                                                    |             |
| `ABDM-1049` |      | Invalid Profile Share Intent Keys                                                                                                                          |             |
| `ABDM-1050` |      | Invalid Profile Share Metadata Keys                                                                                                                        |             |
| `ABDM-1051` |      | Invalid ABHA Number or ABHA Address                                                                                                                        |             |
| `ABDM-1052` |      | Invalid TransactionId or response's requestId                                                                                                              |             |
| `ABDM-1401` |      | HIP is not available                                                                                                                                       |             |
| `ABDM-1061` |      | Consent artefact expired                                                                                                                                   |             |
| `ABDM-1062` |      | Consent Not granted                                                                                                                                        |             |
| `ABDM-1063` |      | Date Range given is invalid                                                                                                                                |             |
| `ABDM-1064` |      | request with this request id already exists                                                                                                                |             |
| `ABDM-1109` |      | ABHA DB service unavailable                                                                                                                                |             |
| `ABDM-1108` |      | Notification DB service unavailable                                                                                                                        |             |
| `ABDM-1201` |      | IDP Gateway is unavailable                                                                                                                                 |             |
| `ABDM-9999` |      | Unknown exception                                                                                                                                          |             |
| `ABDM-1006` |      | Invalid combinations of scopes                                                                                                                             |             |
| `ABDM-1056` |      | This care contexts has been already linked                                                                                                                 |             |
| `ABDM-1055` |      | Invalid HIP Id or PHR Id                                                                                                                                   |             |
| `ABDM-1056` |      | Invalid Link Reference Number                                                                                                                              |             |
| `ABDM-1057` |      | Invalid Care Contexts                                                                                                                                      |             |
| `ABDM-1059` |      | Invalid Care Contexts count                                                                                                                                |             |
| `ABDM-1060` |      | Invalid Patient Reference Number                                                                                                                           |             |
| `ABDM-1061` |      | Invalid Patient Display                                                                                                                                    |             |
| `ABDM-1062` |      | ABHA number mismatch with Link token                                                                                                                       |             |
| `ABDM-1063` |      | HIP Id mismatch with Link token                                                                                                                            |             |
| `ABDM-1064` |      | Request body was missing                                                                                                                                   |             |
| `ABDM-1065` |      | Invalid X Auth token                                                                                                                                       |             |
| `ABDM-1066` |      | Invalid JWT token                                                                                                                                          |             |
| `ABDM-1067` |      | Request body not required                                                                                                                                  |             |
| `ABDM-1170` |      | Invalid ABHA address                                                                                                                                       |             |
| `ABDM-1084` |      | ABHA address mismatch with X Auth token                                                                                                                    |             |
| `ABDM-1085` |      | ABHA number mismatch with X Auth token                                                                                                                     |             |
| `ABDM-1086` |      | Patient profile mismatch with X Auth token                                                                                                                 |             |
| `ABDM-1087` |      | Duplicate patient share request                                                                                                                            |             |
| `ABDM-1090` |      | Duplicate HIP link request                                                                                                                                 |             |
| `ABDM-1091` |      | Duplicate Get links request                                                                                                                                |             |
| `ABDM-1092` |      | Duplicate Link token request                                                                                                                               |             |
| `ABDM-1093` |      | Duplicate Bridge request                                                                                                                                   |             |
| `ABDM-1094` |      | Duplicate bridge patch request                                                                                                                             |             |
| `ABDM-1095` |      | Duplicate Bridge service request                                                                                                                           |             |
| `ABDM-1102` |      | Profile information cannot be null                                                                                                                         |             |
| `ABDM-1103` |      | Duplicate Discovery request                                                                                                                                |             |
| `ABDM-1104` |      | Duplicate Init request                                                                                                                                     |             |
| `ABDM-1105` |      | Duplicate Confirm request                                                                                                                                  |             |
| `ABDM-1106` |      | Duplicate On discovery request                                                                                                                             |             |
| `ABDM-1107` |      | Duplicate On init request                                                                                                                                  |             |
| `ABDM-1108` |      | Duplicate On confirm request                                                                                                                               |             |
| `ABDM-1109` |      | Invalid On discovery response                                                                                                                              |             |
| `ABDM-1110` |      | Invalid On init response                                                                                                                                   |             |
| `ABDM-1111` |      | Invalid On confirm response                                                                                                                                |             |
| `ABDM-1112` |      | Invalid or already expired consent artefact id                                                                                                             |             |
| `ABDM-1113` |      | Duplicate health information provider data flow response                                                                                                   |             |
| `ABDM-1149` |      | Intent type is not supported at HIP end                                                                                                                    |             |
| `ABDM-1150` |      | Bridge API version cannot be null                                                                                                                          |             |
| `ABDM-1402` |      | Acknowledgement is not received from HIP                                                                                                                   |             |
| `ABDM-9999` |      | HIP is unable to generate a token at this time. Please try again later.                                                                                    |             |
| `ABDM-9999` |      | HIP is unable to process at this time. Please try again later.                                                                                             |             |
| `ABDM-1030` |      | Request id not found                                                                                                                                       |             |
| `ABDM-2500` |      | No mapping found for                                                                                                                                       |             |
| `ABDM-2401` |      | The X Auth token is invalid.                                                                                                                               |             |
| `ABDM-2402` |      | Invalid Timestamp                                                                                                                                          |             |
| `ABDM-2404` |      | Invalid Request Id                                                                                                                                         |             |
| `ABDM-2429` |      | Too many requests found                                                                                                                                    |             |
| `ABDM-2501` |      | Payment status should be : SUCCESS,CANCELED,PENDING,FAIL,REFUND\_INITIATED,REFUND\_SUCCESS                                                                 |             |
| `ABDM-2500` |      | Authorization header is missing                                                                                                                            |             |
| `ABDM-2403` |      | Invalid X-CM-ID                                                                                                                                            |             |
| `ABDM-2406` |      | Invalid API sequence flow, please follow logical flow                                                                                                      |             |
| `ABDM-2406` |      | The status is invalid. Please follow the logical status flow or transition.                                                                                |             |
| `ABDM-9999` |      | User not found                                                                                                                                             |             |
| `ABDM-9999` |      | Cannot process the request at the moment, please try later.                                                                                                |             |
| `ABDM-9001` |      | No open order against ABHA. Please ensure a minimum of one open order                                                                                      |             |
| `ABDM-9002` |      | No registration found at <>. Contact counter support                                                                                                       |             |
| `ABDM-9003` |      | Hospital services temporarily unavailable. Please try again after some time.                                                                               |             |
| `ABDM-9004` |      | Services disrupted, please try again.                                                                                                                      |             |
| `ABDM-9005` |      | Bank server not responding. Please try again later                                                                                                         |             |
| `ABDM-9006` |      | Service details mismatch. Please ensure original service ID from HMIS                                                                                      |             |
| `ABDM-9007` |      | The Scan and Pay functionality is not enabled at this facility. Kindly contact the hospital administration.                                                |             |
| `ABDM-1006` |      | Invalid count, must be 2 digit and ranges between 1 to 20                                                                                                  |             |
| `ABDM-1407` |      | The ABHA Number associated with this ABHA Address is currently deactivated. Please reactivate it.                                                          |             |
| `ABDM-1006` |      | Invalid HIType, it must be in Prescription,DiagnosticReport,OPConsultation,DischargeSummary,ImmunizationRecord,HealthDocumentRecord,WellnessRecord,Invoice |             |

## P1 Registration and login

| Code        | HTTP | Message                        | Returned by                                 |
| ----------- | ---- | ------------------------------ | ------------------------------------------- |
| `900902`    | 401  | Missing Credentials            | `p1_get_v3_phr_app_enrollment_isexists`     |
| `ABDM-1107` | 400  | Invalid combinations of scopes | `p1_post_v3_phr_app_login_verify`           |
| `ABDM-1211` | 400  | User not found.                | `p1_post_v3_phr_app_login_search`           |
| `ABDM-9999` | 400  | Invalid LoginId                | `p1_post_v3_phr_app_enrollment_request_otp` |

## P2 Consents Management

| Code        | HTTP | Message             | Returned by                                    |
| ----------- | ---- | ------------------- | ---------------------------------------------- |
| `900902`    | 401  | Missing Credentials | `p2_get_v3_phr_app_login_profile`              |
| `ABDM-9999` | 400  | Invalid LoginId     | `p2_post_v3_phr_app_login_profile_request_otp` |

143 codes are recorded. A code you meet that is not here is one the specifications do not carry yet.


---

# ABHA Registry

## ABHA (Ayushman Bharat Health Account): Identity Framework and Digital Health Access under ABDM

The Ayushman Bharat Health Account (ABHA) is a unique health identifier issued under the Ayushman Bharat Digital Mission (ABDM). It serves as the foundational digital identity for individuals within the ABDM ecosystem and enables secure identification, authentication, and exchange of health records.

ABHA facilitates access to digital health services while ensuring interoperability across healthcare providers, health information systems, and personal health applications.

## Components of ABHA

An ABHA account consists of two key identifiers:

### 1. ABHA Number

The ABHA Number is a unique 14-digit identifier assigned to an individual after successful identity verification.

**Key Characteristics**

- Unique to each individual.
- Acts as the primary health identity within ABDM.
- Used for patient identification across healthcare systems.
- Issued after completion of the KYC verification process.
- Always associated with at least one ABHA Address.

### 2. ABHA Address

The ABHA Address is a unique and user-friendly identifier in the format: `user@abdm`

**Key Characteristics**

- Facilitates secure routing of health information and consent requests.
- Can be shared with healthcare providers for record linking and data exchange.
- A default ABHA Address is generated along with every ABHA Number.
- Users may subsequently create a personalized ABHA Address.

## Identity Verification Mechanisms

ABHA creation and authentication are performed through ABDM-approved verification methods.

### Verification Modes

**Aadhaar OTP Authentication**

The individual verifies identity using an OTP sent to the Aadhaar-linked mobile number.

**Face Authentication**

Identity verification is completed using face authentication through approved Aadhaar RD Service Application.

**Biometric Authentication**

Verification using fingerprint or iris through registered biometric devices.

**Demographic Authentication**

Identity validation based on demographic details such as name, date of birth, and gender, as per applicable demo authentication workflows.

## Child ABHA

A Child ABHA enables digital health record creation for children who may not possess an Aadhaar number.

**Key Features**

- Created with consent of a parent or legal guardian.
- Enables continuity of health records from birth.
- Available only through approved government programmes and authorized government entities.
- Not available for private-sector implementation.

## ABHA Address Guidelines

ABHA Addresses must comply with defined validation standards.

**Permitted Characters**

- Alphabetic characters (A-Z)
- Numeric characters (0-9)
- Dot (.)

**Validation Rules**

- Cannot begin with a numeric character.
- Cannot begin or end with a dot (.).
- Must conform to ABDM validation requirements at the time of creation.
- Mobile numbers cannot be used directly as ABHA Addresses.

Organizations should rely on ABDM validation services to verify address eligibility.

## Information Associated with an ABHA

An ABHA profile may contain the following information:

| Field Category      | Description                                    |
| ------------------- | ---------------------------------------------- |
| Personal Details    | Name, gender, date of birth                    |
| Contact Information | Mobile number and verified email (if provided) |
| ABHA Details        | ABHA Number and ABHA Address                   |
| Profile Information | Profile photograph (if available)              |
| Digital Assets      | ABHA Card and associated QR Code               |

## Role of ABHA Across ABDM Milestones

### Milestone 1 (M1) - ABHA Management

M1 focuses on:

- ABHA creation
- Identity verification
- Login and authentication
- Profile management
- Session management

**Supported Login Options**

- Mobile Number
- Aadhaar Number
- ABHA Number
- ABHA Address

### Milestone 2 (M2) - Care Context Linking

M2 enables healthcare providers to link care contexts with an individual's ABHA Address, facilitating discovery and record association.

### Milestone 3 (M3) - Consent Management

M3 enables consent-based health information exchange by using the ABHA Address as the identifier for raising and managing consent requests.

## Importance of ABHA in ABDM

ABHA is the foundational identity layer of the ABDM ecosystem. It enables:

- Unique patient identification.
- Secure authentication.
- Health record discovery and linking.
- Consent-based health information exchange.
- Interoperable digital health services across India.

Every ABDM health information exchange workflow begins with a valid ABHA identity, making it a critical component of the national digital health ecosystem.


---

# Registries

A registry is a national directory: it issues an identifier, holds the record behind it and answers lookups. Every other [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm) API assumes those identifiers already exist, so a registry entry is the first thing your integration creates.

There are two, because ABDM separates the person receiving care from the people and places giving it. [ABHA](/docs/hiecm/v3/getting-started/glossary#abha) is the patient side. NHPR is the provider side, and covers two registries of its own: the [HPR](/docs/hiecm/v3/getting-started/glossary#hpr) for professionals and the [HFR](/docs/hiecm/v3/getting-started/glossary#hfr) for facilities.

| Registry                                  | Identifies                                          | Identifier                                                                                                 | Written by                  |
| ----------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------- |
| [ABHA](/docs/hiecm/v3/registries/abha)    | A patient                                           | 14 digit ABHA number issued after [KYC](/docs/hiecm/v3/getting-started/glossary#kyc), plus an ABHA address | [M1](/docs/hiecm/v3/api/m1) |
| [HPR](/docs/hiecm/v3/registries/nhpr/hpr) | A doctor, nurse, pharmacist or facility manager     | HPR ID                                                                                                     | [M4](/docs/hiecm/v3/api/m4) |
| [HFR](/docs/hiecm/v3/registries/nhpr/hfr) | A hospital, clinic, lab, imaging centre or pharmacy | Facility ID                                                                                                | [M4](/docs/hiecm/v3/api/m4) |

## The order they arrive in

The HFR create call takes the HPR token in the `x-hprid-auth` header, generated from an HPR ID and password. Someone in your organisation needs an HPR ID with facility manager rights before you can register a facility, and a facility has to be in the HFR before it can act as a [HIP](/docs/hiecm/v3/getting-started/glossary#hip) or [HIU](/docs/hiecm/v3/getting-started/glossary#hiu) on [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm).

## Next

- [ABHA](/docs/hiecm/v3/registries/abha), the patient registry
- [NHPR](/docs/hiecm/v3/registries/nhpr), the provider registries and their shared base URLs
- [HIE-CM](/docs/hiecm/v3/), the gateway that uses these identifiers


---

# HFR, the facility registry

[HFR](/docs/hiecm/v3/getting-started/glossary#hfr) is the Health Facility Registry, the places half of [NHPR](/docs/hiecm/v3/registries/nhpr) alongside the [HPR](/docs/hiecm/v3/registries/nhpr/hpr). It is a national directory of hospitals, clinics, diagnostic laboratories, imaging centres and pharmacies, and a facility has to enrol here before it can do anything else on [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm).

## Why it blocks everything else

A facility needs a valid facility ID and registration in the [HIP](/docs/hiecm/v3/getting-started/glossary#hip) role before it can create health records and share them. A product that has finished [M2](/docs/hiecm/v3/api/m2) or [M3](/docs/hiecm/v3/api/m3) against the sandbox cannot go live without this registry.

What the facility gets: a trusted identity, a listing in national search results, less paperwork on licence renewals and insurance empanelment, and access to ABDM's digital services.

## What a facility record holds

Three layers, one call each.

| Layer                  | What goes in it                                                                                                                                                                                                                                                                                |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Basic information      | Name, ownership and its subtypes, system of medicine, facility type and subtype, speciality type, operational status, type of service, the full address as codes, latitude and longitude, contact details, opening days and hours, and two mandatory photographs of the board and the building |
| Additional information | Yes or no flags for a dialysis centre, pharmacy, blood bank, cath lab, diagnostic lab and imaging centre, plus scheme identifiers the facility already holds: NHRR, NIN, AB-PMJAY, Rohini, ECHS, CGHS, CEA registration and a state insurance scheme ID                                        |
| Detailed information   | Specialities per system of medicine, and the sections that apply to this facility type: medical infrastructure and bed counts, pharmacy details, blood bank details, diagnostic services, imaging services                                                                                     |

Which parts of the detailed layer are mandatory depends on the facility type, the type of service and the system of medicine, and the rules are on [the HPR and HFR call list](/docs/hiecm/v3/api/m4). Two of them shape your form. An inpatient or day care facility must submit at least one bed count greater than zero. An imaging centre, diagnostic laboratory, blood bank or pharmacy need not submit medical infrastructure at all.

### Codes, not names

Ownership, facility type, facility subtype, speciality, system of medicine, operational status and days of operation come from HFR's own master data calls. Demographic fields come from the Local Government Directory at [lgdirectory.gov.in](https://lgdirectory.gov.in/), through the LGD state, district and sub district calls. HFR APIs accept only the code for any field where master data is defined, never the display value, so build the master data fetch first or every write call fails validation.

## The onboarding journey

Five calls, in a fixed order.

1. **Deduplicate search.** Check the facility is not already listed.
2. **Basic facility information.** Creates the record and returns a tracking ID. That ID is your facility's unique identification number until you submit. Pass it as the facility ID on every later call in the sequence.
3. **Additional information.** Takes the tracking ID.
4. **Detailed information.** Takes the tracking ID.
5. **Submit facility details.** Sends the facility for verification.

Without call five the facility does not exist

If you do not make the submit call, the facility stays in draft. A draft facility goes nowhere, and nothing else in ABDM can use it. Running the first four calls and getting a tracking ID back does not mean you are registered.

To update a facility later, send the same calls with the facility ID or tracking ID in the payload rather than creating a new record.

## The link to the HPR token

Your client credentials are not enough. Basic facility information takes an **HPR token in the header**, generated from an HPR ID and password. Submit facility takes an **`x-hpird-auth` token in the header**. Obtain both from the HPR token flow, and set each header by the name the call asks for.

Both come from a person, not from your application. That is why [HPR](/docs/hiecm/v3/registries/nhpr/hpr) comes first in a rollout, and why somebody in your organisation needs an [HPID](/docs/hiecm/v3/getting-started/glossary#hpid) with facility manager rights, role 2 or role 3, before you write a line of HFR code.

## The facility ID

A submitted and verified facility carries a facility ID, and that ID identifies it in every record you share. Two formats are documented for it:

| Where                                                               | Format                                                            |
| ------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Bridge linkage, facility search, nearby search, send OTP to contact | Starts with `IN` and is 12 characters in total                    |
| Deduplicate search                                                  | A 6 digit numeric value, labelled there as the facility unique ID |

One parameter name carries two different formats. Take the format from the reference page for the call you are making.

## Bridge linkage

A bridge is your software's connection to ABDM. Registering a facility gives it an identity; linking a bridge makes your system resolvable as that facility, in the HIP or [HIU](/docs/hiecm/v3/getting-started/glossary#hiu) direction, so records flow to it. The call takes a facility ID, the facility name, a bridge ID, a HIP name, a type of `HIP` or `HIU`, and an active flag.

The HIP name is the one field a patient sees. It is the name shown in the [ABHA](/docs/hiecm/v3/getting-started/glossary#abha) or [PHR](/docs/hiecm/v3/getting-started/glossary#phr) app when the patient searches for the hospital. It must be 15 characters or fewer, carry no special characters, and be unique for every bridge within a facility. The suggested pattern is the hospital name plus the bridge name: hospital XYZ on bridge BRIDGE TEST becomes `XYZ BRIDGE`. Fifteen characters is short, so pick what a patient will recognise.

## Finding a facility

| Call                             | What it is for                                                                                                                                                                                 |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Deduplicate search               | Name, district and sub district, before creating a record                                                                                                                                      |
| Search facility                  | By facility ID, or by ownership code, state LGD code and facility name. Fuzzy on the name, exact on everything else, paginated                                                                 |
| Nearby search                    | Latitude, longitude and a radius in kilometres, with optional filters for ownership, speciality and ABDM enabled. Results are ordered nearest first                                            |
| Send and validate OTP to contact | Sends an [OTP](/docs/hiecm/v3/getting-started/glossary#otp) to the mobile number registered against a facility, then validates it. This proves control of a facility record you did not create |

Base URLs for every call on this page are on [NHPR](/docs/hiecm/v3/registries/nhpr).

## Request and response formats

This page gives what a facility record holds and the order the calls go in. Take the request and response shapes from the health facility registry sandbox documentation alongside it.

Two paths are fixed here:

| Call                | Path                              |
| ------------------- | --------------------------------- |
| Fetch facility type | `v1.5/facility/fetchfacilitytype` |
| Get specialities    | `/v1.5/facility/get-specialities` |

## Next

- [HPR](/docs/hiecm/v3/registries/nhpr/hpr), which issues the token these calls need.
- [NHPR](/docs/hiecm/v3/registries/nhpr), the parent page.
- [the HPR and HFR call list](/docs/hiecm/v3/api/m4), parameter tables and `HIS-` error codes.
- [M2 Health Information Provider, Health Information Provider Services](/docs/hiecm/v3/api/m2), which needs this facility ID.


---

# HPR, the professional registry

[HPR](/docs/hiecm/v3/getting-started/glossary#hpr) is the Healthcare Professionals Registry, the people half of [NHPR](/docs/hiecm/v3/registries/nhpr) alongside the [HFR](/docs/hiecm/v3/registries/nhpr/hfr). Registering there issues the professional an [HPID](/docs/hiecm/v3/getting-started/glossary#hpid), their identity everywhere in [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm).

## Who can enrol

Three categories today, with more to be added later: doctor, nurse and pharmacist. Each professional also declares a system of medicine, from modern medicine, dentistry, Ayurveda, Unani, Siddha, Homoeopathy, Sowa-Rigpa, and yoga and naturopathy. A person can also enrol as a facility manager instead of a clinician, set by the role code:

| Role code | What the person is                           |
| --------- | -------------------------------------------- |
| 1         | Healthcare Professional                      |
| 2         | Facility Manager                             |
| 3         | Healthcare Professional and Facility Manager |

If nobody in your organisation holds role 2 or role 3, you cannot register a facility. See [HFR](/docs/hiecm/v3/registries/nhpr/hfr).

## The HPID

A unique 14 digit, Aadhaar authenticated identifier issued on successful registration to a healthcare professional or facility manager. It is written both ways, HPID and HPR ID. Like an [ABHA](/docs/hiecm/v3/registries/abha), it comes in two forms:

| Form        | Sample              | Where it is used                                  |
| ----------- | ------------------- | ------------------------------------------------- |
| The number  | `71-2665-5777-XXXX` | Sent as `hpid` or `hprIdNumber`                   |
| The address | `name@hpr.abdm`     | Sent as `hprId`, with `domainName` of `@hpr.abdm` |

The professional chooses the readable part through a username suggestion call, the same pattern as the ABHA address suggestion in [M1](/docs/hiecm/v3/api/m1).

## What identifies a doctor

An HPID on its own is an authenticated person; the profile behind it makes them a doctor. The register professional call groups it in five blocks:

| Block                 | What it holds                                                                                                                                                                     |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Personal information  | Salutation and name, date of birth, gender, nationality, languages spoken, profile photo, official mobile and email                                                               |
| Communication address | Country, state, district, sub district, city and pincode, all as master data codes. Skipped if the address matches the [KYC](/docs/hiecm/v3/getting-started/glossary#kyc) address |
| Registration          | The council the professional is registered with, the registration number, the registration certificate, and whether the registration is permanent or renewable                    |
| Qualification         | Degree or diploma obtained, college, university, year of award, and the degree certificate                                                                                        |
| Current work          | Whether they are working, the purpose of that work, whether it is private, government or both, and the facility they work at                                                      |

Three codes decide what the professional may be. **Category** says doctor, nurse or pharmacist. **Subcategory** fixes the system of medicine. The **degree code** must agree with both. The operations that take them, and their fields, are in [the M4 API reference](/docs/hiecm/v3/api/m4).

The subcategory codes differ between two calls

Subcategory codes differ between the create HPID and register professional tables. Fetch the codes from the HPRID subcategories master call rather than hard coding either table.

The SMD ID identifies doctors only. Searching for nurse colleges by SMD returns a null college and university name, and this is expected: for nurses, SMD is always null.

## The registration journey

Two halves, in order. Nothing in the second works until the first produces a token.

**Half one, create the HPID.** Nine calls follow the management token, in this order:

1. Generate Aadhaar link
2. Check Aadhaar authentication status
3. Verify OTP and fetch user details
4. Check whether an HPID already exists for this Aadhaar
5. Mobile match
6. Generate mobile OTP
7. Verify mobile OTP
8. Username suggestions
9. Create HPID

The last returns the HPID and a `token`, which the next call takes as `hprToken`.

**Half two, register the professional.** Register professional writes the full profile, at `POST https://apihspsbx.abdm.gov.in/v4/int/apis/v1/doctors/register-professional-new`. Then retrieve professional document list, upload documents, update professional and fetch professional details.

Three things to know first:

- The Aadhaar link URL is valid for 5 minutes only. Call the API again once it expires.
- `degreeCertificate` and `registrationCertificate` are mandatory uploads, and `proofOfWorkCertificate` is mandatory when the professional is government or both.
- Call `demographicAuthViaMobile` first, and generate the mobile OTP only when it returns false.

Call by call, with the parameters, is on [M4 user journey](/docs/hiecm/v3/milestones/m4) and [the M4 API reference](/docs/hiecm/v3/api/m4).

## Getting an HPR token later

The `hprToken` from creation does not last. Three ways to get a fresh one, all still carrying the bearer token in the `Authorization` header, because the HPR token proves who the professional is, not that your client may call.

| Route                  | Path                                        |
| ---------------------- | ------------------------------------------- |
| By password            | `/v4/int/api/v1/auth/authPassword`          |
| By mobile OTP, send    | `/v4/int/api/v2/auth/loginViaMobileSendOTP` |
| By Aadhaar OTP, send   | `/v4/int/api/v1/auth/init`                  |
| By Aadhaar OTP, verify | `/v4/int/api/v1/auth/confirmWithAadhaarOtp` |

The bodies are on [the M4 API reference](/docs/hiecm/v3/api/m4).

## What your system has to hold

Per professional, store:

- The HPID, in both forms.
- The current HPR token, its expiry, and a way to refresh it without re-registering the person.
- The transaction id, for one flow only.
- The master data ids you sent for council, course, college, university, language, country, state and district. The registry rejects display values.
- The certificates you uploaded, with each document slot identifier.

Once, for the whole integration: the username and password for the management token call, and the public certificate from `v4/int/api/v1/auth/cert`. Three fields are encrypted with it, cipher `RSA/ECB/PKCS1Padding`: the mobile number in mobile match, the OTP in mobile login, and the email and password in create HPID. That cipher and that certificate belong to the NHPR. M1 encrypts with RSA-OAEP and SHA-1 under the ABHA certificate, so the two paths are not interchangeable.

Upload limits: 1 MB for a profile photo, 5 MB for anything else, png, jpeg, jpg or PDF only. Attachments go as a `fileType` and a base64 `data` string.

## Request and response formats

This page gives the behaviour, the call order, the parameter tables and the code lists. Take the request and response shapes from [the M4 API reference](/docs/hiecm/v3/api/m4) alongside it.

## Next

- [HFR](/docs/hiecm/v3/registries/nhpr/hfr), the facility half, which needs a token from this registry.
- [NHPR](/docs/hiecm/v3/registries/nhpr), the parent page.
- [M4 user journey](/docs/hiecm/v3/milestones/m4), the same order as diagrams.
- [the M4 API reference](/docs/hiecm/v3/api/m4), its operations and their fields.


---

# NHPR, the provider registries

NHPR is the provider half of [Registries](/docs/hiecm/v3/registries), and the name covers the pair underneath it: the [HPR](/docs/hiecm/v3/getting-started/glossary#hpr) for people and the [HFR](/docs/hiecm/v3/getting-started/glossary#hfr) for places. This page carries what they share and forks to each.

They are separate because a doctor holds one identity for a career across many facilities, while a facility sees many professionals pass through. Keeping them apart lets each change without rewriting the other, and lets [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm) answer two questions: who wrote this, and where was it written.

## Which one you need, and when

| You need                                                           | When                                                                                                                                                                                                             |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| An [HPID](/docs/hiecm/v3/getting-started/glossary#hpid) on the HPR | Before anything else in NHPR. The HFR create call carries an HPR token in the `x-hprid-auth` header, generated from an HPR ID and password                                                                       |
| A facility ID on the HFR                                           | Before the facility goes live as a [HIP](/docs/hiecm/v3/getting-started/glossary#hip) or an [HIU](/docs/hiecm/v3/getting-started/glossary#hiu). A valid facility ID is a prerequisite for sharing records at all |
| A bridge linked to the facility                                    | Last. It is what makes your software resolvable as that facility on the network                                                                                                                                  |

## Base URLs

Both registries share one base URL:

```text
Sandbox     https://apihspsbx.abdm.gov.in/v4/int/
```

The calls take a bearer token in the `Authorization` header. M4 declares bearer authentication. The HPID calls publish `POST /getManagementToken`. [M4](/docs/hiecm/v3/api/m4) is the only milestone in [ABDM](/docs/hiecm/v3/getting-started/glossary#abdm) that writes to NHPR, and its operations and their fields are in [the M4 API reference](/docs/hiecm/v3/api/m4).

## Next

- [HPR](/docs/hiecm/v3/registries/nhpr/hpr): the HPID and the registration journey.
- [HFR](/docs/hiecm/v3/registries/nhpr/hfr): the facility record, the five call onboarding sequence, bridge linkage.
- [ABHA](/docs/hiecm/v3/registries/abha), the patient side.
- [M4 API reference](/reference/hiecm-m4).


---

# Developer resources

This section contains the test scenarios applicable for ABDM integration and certification. Test cases are organized module-wise and include the corresponding test case identifiers used during the certification process. Additional developer resources and implementation guidance may be added to this section as they become available.

## Testing use cases

The certification pack NHA issues names the cases each milestone is tested against.

## ABDM integration resources

Access the documentation, AI-assisted tools and reference projects required to support your ABDM integration.

[ABDM Documentation](/docs/hiecm/v3)

[Access versioned guides, API references, milestone details, error information and change logs for HIE-CM, UHI and NHCX.](/docs/hiecm/v3)

[AI-assisted Integration Tools](/docs/hiecm/v3/getting-started/build-with-ai)

[Use milestone guidance, FHIR references and the documentation MCP server to provide the coding assistant with relevant ABDM integration information.](/docs/hiecm/v3/getting-started/build-with-ai)

[National Health Claims Exchange](/docs/nhcx/v1)

[Understand how payers, third-party administrators and healthcare providers exchange health insurance claims through NHCX.](/docs/nhcx/v1)

CARE Reference Environment

Explore planned reference workflows for ABDM integration and follow the progress of the open-source project.

## Next

- The calls each case exercises: [API references](/docs/hiecm/v3/api).


---

# Accepted, then nothing

You started an M2 flow, one or more calls came back accepted, and then it stalled. Discovery and care context linking are chains of several calls with a callback between each pair, and the flow looks broken from the outside whichever link in that chain is missing, so you have to find which one.

Before working through the checks, know which flow you are in. [Discovery](/docs/hiecm/v3/getting-started/glossary#discovery) is whoever asks to read records, in the [HIU](/docs/hiecm/v3/getting-started/glossary#hiu) direction, looking for what your facility holds: a patient's [PHR](/docs/hiecm/v3/getting-started/glossary#phr) app, another facility, an insurer or a referral service. Linking is you attaching a [care context](/docs/hiecm/v3/concepts/linking) to a patient's [ABHA address](/docs/hiecm/v3/getting-started/glossary#abha-address). You also need the `REQUEST-ID` from the call where the chain started: every callback in the chain should carry it, so it is what lets you find where the chain broke.

## Work through these in order

1. **Discovery request.** Your discovery call should produce an inbound discovery request callback to your bridge. If this never arrives, the problem sits upstream of your system entirely; escalate rather than continuing down this list.
2. **Link initiation.** Starting a link should produce an inbound link init callback. If discovery completed but this never arrives, the stall is at the handoff into linking.
3. **Link confirmation.** Do not treat the synchronous acknowledgement to your link request as success. The confirmation arrives as a separate callback to your registered URL, and the care context only becomes visible in the patient's PHR app once it does. See [linking](/docs/hiecm/v3/concepts/linking) for the full sequence.
4. **`REQUEST-ID` reuse.** If you generated the same `REQUEST-ID` for more than one call in the chain, or reused one from an earlier attempt, responses and callbacks can no longer be told apart. Generate a fresh one per call.

Before assuming any step above is genuinely missing, rule out a callback URL problem first: [the callback never arrives](/docs/hiecm/v3/troubleshooting/callback-never-arrives) covers registration and reachability, which is more common than the gateway itself failing to send.

## How you know it worked

For linking, the care context appears when the patient's PHR app runs discovery against your facility, after the link confirm callback reports success. For discovery, your system answers the inbound discovery callback with the care contexts you hold for that patient.

## When it goes wrong

If you have identified which callback in the chain is missing and ruled out a callback URL problem, raise a request on the [support ticketing platform](https://sandboxsupport.abdm.gov.in/). Report which step of the chain stopped, the `REQUEST-ID` from the call that started it, the `TIMESTAMP`, and every response and callback body you did receive up to the point it stalled. See [what to put in a support request](/docs/hiecm/v3/troubleshooting#what-to-put-in-a-support-request) for the full report format.

This symptom can surface as a duplicate or invalid link reference, or a call made out of the logical sequence, both on the [M2 errors reference](/docs/hiecm/v3/api/m2/errors).

[Next Still stuck? Check the M2 user journey Confirm exactly where your call sits in the sequence, and which callback should follow it.](/docs/hiecm/v3/milestones/m2)


---

# The callback never arrives

You made a call, it came back with a 202 or a 200, and nothing else has happened since. This is a common report in [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm) integration. The checks below are in the order we recommend, not a record of how often each has turned out to be the actual cause.

That early response only means the [NHA](/docs/hiecm/v3/getting-started/glossary#nha) gateway accepted your request. In M2 and M3 the real answer arrives later, as a POST from the gateway to a URL you registered in advance. See [the gateway](/docs/hiecm/v3/concepts/gateway) for why this is the normal shape of these flows, and the [API reference](/docs/hiecm/v3/api), where each call names the callback it produces.

## Work through these in order

1. **Is the callback URL registered with the gateway?** Confirm it with the [update bridge callback URL](/docs/hiecm/v3/api/gateway/endpoints/gateway-abdm-gateway/03-gateway-patch-gateway-v3-bridge-url) call. Setting a URL in a console once is not the same as confirming the gateway has it.
2. **Is that URL reachable from the public internet over HTTPS?** ABDM posts to it from outside your network. A URL that only answers on your local machine or behind a VPN will never receive anything, and the original call gives you no signal that this is wrong.
3. **Did the request expire before the other party answered?** How long a request stays live before ABDM gives up is not documented yet. If you have waited what feels like a long time, say so when you escalate rather than assuming a fixed window.
4. **Is your endpoint returning a non success status?** A handler that errors, times out, or is slow is a real problem. Whether and when delivery attempts stop is not documented yet. Deliveries can repeat, so your handler has to treat every one as possibly a retry of one it already handled. Respond quickly with a success status even before you have finished processing the callback body.

## How you know it worked

Your handler receives a POST at your registered URL, carrying the exact `REQUEST-ID` you generated for the original call. Until you have observed that once, the callback path is unproven, even if the registration call itself succeeded.

## When it goes wrong

If all four checks pass and the callback still has not arrived, raise a request on the [support ticketing platform](https://sandboxsupport.abdm.gov.in/). Report the API you called, the `REQUEST-ID`, the `TIMESTAMP`, and the response you got. See [what to put in a support request](/docs/hiecm/v3/troubleshooting#what-to-put-in-a-support-request) for the full report format.

This symptom can surface as [ABDM-9999](/docs/hiecm/v3/reference/error-codes), the catch-all for a failure the gateway does not explain further.

[Next Still stuck? Check the M2 user journey Confirm which step of the sequence your call sits in, so you know which callback should follow it.](/docs/hiecm/v3/milestones/m2)


---

# Consent stuck in Requested

You raised a consent request and it has not moved to Granted or Denied. Requested is the starting state of the consent request itself, not of the [consent artefact](/docs/hiecm/v3/getting-started/glossary#consent-artefact) it can produce: the artefact is created only once the patient grants. Nothing has failed yet, the patient has not yet acted, or something kept them from ever seeing it. See [Consent, two objects, not one](/docs/hiecm/v3/concepts/consent#two-objects-not-one) for the full state model.

Before working through the checks, confirm the request itself was accepted, and check its current state rather than only waiting: the [M3 API reference](/docs/hiecm/v3/api/m3) documents the consent request status call.

## Work through these in order

1. **Does the patient's app show the request at all?** The gateway notifies the patient through the ABHA App when a consent request is raised. If the patient uses a third party PHR app instead, that app needs an approved subscription with the gateway to be notified of a new consent request; without one, the request can sit unseen even though it was accepted. Whether the ABHA App itself needs anything set up beyond the patient having an address is not something we have confirmed.
2. **Has the request expired?** A consent request carries a window the requester sets for the patient to respond, separate from how long access lasts once granted. See [Consent](/docs/hiecm/v3/concepts/consent#the-states-a-consent-moves-through) for the two clocks. Running out of the request window moves the state to Expired, not Requested, so checking the current status tells you if this has already happened.
3. **Was it raised against the right ABHA address?** An address that is malformed or does not exist produces an error and the request goes nowhere. A syntactically valid address that belongs to a different real patient will not error at all: the request is delivered and seen, just by the wrong person, not the one you meant. Getting the address right matters more than passing validation.

## How you know it worked

The consent request status reports Granted or Denied rather than Requested. A Granted result also carries the id of at least one consent artefact, and a granted request can produce more than one.

## When it goes wrong

If the patient's app shows the request, it has not expired, and the address is correct, and the state is still Requested after a reasonable wait, this is expected: Requested means the patient has not decided yet, and there is no call that makes them decide faster. If you believe the patient acted and the state did not change, raise a request on the [support ticketing platform](https://sandboxsupport.abdm.gov.in/). Report the consent request id, the `REQUEST-ID` from the init call, the `TIMESTAMP`, and the status response. See [what to put in a support request](/docs/hiecm/v3/troubleshooting#what-to-put-in-a-support-request) for the full report format.

This symptom can surface as an invalid or non-existent ABHA address on the [error codes reference](/docs/hiecm/v3/reference/error-codes).

[Next Still stuck? Read Consent end to end The full state model, the two clocks, and who holds what.](/docs/hiecm/v3/concepts/consent)


---

# Everything returns 401

Every call fails the same way, on every endpoint, not just one. That pattern points at your session or your headers, not at any single operation.

Before working through the checks, confirm more than one endpoint is actually failing. If only one call fails while others succeed, read that call's own error code on the [error codes reference](/docs/hiecm/v3/reference/error-codes) instead. Read the response body too, not only the status: the gateway returns a code that names the real reason.

## Work through these in order

1. **Has your session token expired?** Session tokens are short lived. Read `expiresIn` from the sessions call response rather than assuming a duration, and re-run it for a fresh token instead of retrying the failing call with the old one. See [authentication](/docs/hiecm/v3/reference/authentication).
2. **Are you calling the wrong environment's base URL?** A sandbox token is not valid against a production base URL, or the reverse. Look at the host in the failing request and the host you requested the session token from, side by side. If they differ, point every call at the same host you authenticated against.
3. **Is your clock wrong?** The `TIMESTAMP` header has to be close to the gateway's own clock, in ISO 8601 UTC. A container host that was suspended and resumed is the usual cause, because its clock resumes behind. See [authentication](/docs/hiecm/v3/reference/authentication).
4. **Is `X-CM-ID` missing or wrong for this environment?** Look at the literal value you sent, not the value you meant to send: `sbx` on the sandbox, `abdm` in production. This header names the consent manager you are pointed at, and the wrong value fails every call the same way a missing session token does.

## How you know it worked

A call that was returning 401 now returns its normal response, and stays that way across more than one call in a row. A single success right after several failures can be a token that was about to expire anyway; confirm with a second call a minute or more later.

## When it goes wrong

If you have re-run the session call, confirmed the environment, fixed the clock, and confirmed `X-CM-ID`, and calls still return 401 with no matching code, raise a request on the [support ticketing platform](https://sandboxsupport.abdm.gov.in/). Report the API you called, the `REQUEST-ID`, the `TIMESTAMP`, and the full response body. See [what to put in a support request](/docs/hiecm/v3/troubleshooting#what-to-put-in-a-support-request) for the full report format.

The codes this symptom can surface are on the [error codes reference](/docs/hiecm/v3/reference/error-codes): an invalid timestamp, the wrong consent manager id, a missing session token, or a required header that is absent or malformed.

[Next Still stuck? Read authentication end to end Every header a call needs, and what the gateway does when one is wrong.](/docs/hiecm/v3/reference/authentication)


---

# When something breaks

Find the symptom you are seeing. Every page here walks the checks in the order this catalogue recommends checking, not a record of how often each has turned out to be the actual cause, so you do not need to know an error code to start.

- [The callback never arrives](/docs/hiecm/v3/troubleshooting/callback-never-arrives): a call returned 202, and nothing followed on your registered URL.
- [Everything returns 401](/docs/hiecm/v3/troubleshooting/everything-returns-401): every call fails the same way, not just one endpoint.
- [The OTP never arrives](/docs/hiecm/v3/troubleshooting/otp-never-arrives): you requested an OTP and nothing reached the phone.
- [Accepted, then nothing](/docs/hiecm/v3/troubleshooting/accepted-then-nothing): discovery or linking started and stalled somewhere in the middle.
- [Consent stuck in Requested](/docs/hiecm/v3/troubleshooting/consent-stuck-requested): a consent request never moved to Granted or Denied.

If your symptom is not here, or you already have an error code in hand, the [error codes reference](/docs/hiecm/v3/reference/error-codes) is organised the other way, by code.

## What to put in a support request

Raise it through [Support](/docs/support), with:

| Include                          | Example                                |
| -------------------------------- | -------------------------------------- |
| The API you called               | `POST /api/hiecm/gateway/v3/sessions`  |
| The `REQUEST-ID` header you sent | `4f8a1c62-6a3b-4d0e-9d7c-2b1f0a5e8d31` |
| The `TIMESTAMP` header you sent  | `2026-08-24T09:14:07.412Z`             |
| The response you received        | Status code and full body              |
| What you expected instead        | The behaviour the document describes   |

Add the callback body if the call is asynchronous and a callback arrived. Never post an access token, a client secret, or a real patient's identifiers. Replace them with a placeholder.

`REQUEST-ID` is a fresh UUID you generate per request. It is the one value that names the exact call you made, so log it and quote it.


---

# The OTP never arrives

You called the request OTP operation, got back a `txnId`, and the phone you are watching has not received an [OTP](/docs/hiecm/v3/getting-started/glossary#otp).

Before working through the checks, confirm the request call itself succeeded and returned a `txnId`. If it failed, work through [Everything returns 401](/docs/hiecm/v3/troubleshooting/everything-returns-401) or the code the response names on the [error codes reference](/docs/hiecm/v3/reference/error-codes) instead.

## Work through these in order

1. **Is this the Aadhaar mobile, and are you holding it?** In the Aadhaar OTP enrolment flow, only the mobile number registered against that Aadhaar number receives the OTP. That is not necessarily the phone the person is holding while they enrol. See the [M1 user journey](/docs/hiecm/v3/milestones/m1) for the full enrolment sequence, and confirm which number Aadhaar has on file before assuming delivery failed.
2. **Have you requested an OTP for this transaction more than a few times in a short window?** You may have been rate limited. A retry loop that fires the request call again on every failure can trigger this without the failure showing clearly in your own logs, because a rate limit response can read like a plain timeout depending on how your client surfaces it.
3. **Has the transaction expired before you tried to verify it?** How long a `txnId` stays valid is not documented yet. A failed enrolment call should not be retried blindly: start a fresh OTP request rather than reuse an old `txnId` if enough time has passed that you are unsure it is still live.

## How you know it worked

The phone registered against the identifier you sent receives an SMS carrying an OTP, and verifying it with that `txnId` succeeds. Receiving a `txnId` from the request call alone does not confirm the SMS was sent.

## When it goes wrong

If you have confirmed the receiving number, are not rate limited, and the transaction is fresh, and the OTP still has not arrived, raise a request on the [support ticketing platform](https://sandboxsupport.abdm.gov.in/) rather than requesting again. Report the API you called, the `REQUEST-ID`, the `TIMESTAMP`, and the full response body including the `txnId`. See [what to put in a support request](/docs/hiecm/v3/troubleshooting#what-to-put-in-a-support-request) for the full report format.

This symptom can surface as a rate limit code or the catch-all failure code, both on the [error codes reference](/docs/hiecm/v3/reference/error-codes).

[Next Still stuck? Walk the M1 user journey See exactly where the OTP request sits among the calls that create an ABHA.](/docs/hiecm/v3/milestones/m1)


---

# Use cases

A use case is one thing a patient does at your counter, and the calls your system makes to answer it. Each one belongs to a [milestone](/docs/hiecm/v3/milestones). Build that milestone first, then add the use case.

| Use case                                                              | Milestone                                                      | What the patient does                                                                                                         |
| --------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| [Scan and Register](/docs/hiecm/v3/use-cases/scan-and-register)       | [M1 Identity](/docs/hiecm/v3/milestones/m1)                    | Scans your counter QR code and shares their ABHA profile, so registration needs no typing and they get a queue token.         |
| [Patient record share](/docs/hiecm/v3/use-cases/patient-record-share) | [M3 Health Information User](/docs/hiecm/v3/milestones/m3)     | Scans your counter QR code and pushes records from their PHR app straight to your system, without a consent request from you. |
| [Scan and Pay](/docs/hiecm/v3/use-cases/scan-and-pay)                 | [M2 Health Information Provider](/docs/hiecm/v3/milestones/m2) | Scans your counter QR code, sees their open orders in their PHR app, pays there, and your system learns the payment status.   |

All three start with the same QR code at the counter. What differs is what moves: Scan and Register sends the patient's profile to you, Patient record share sends their health records, and Scan and Pay sends their payment.


---

# Patient record share

Receive health records that a patient chooses to push to you from their [PHR](/docs/hiecm/v3/getting-started/glossary#phr) app. This use case belongs to [M3 Health Information User](/docs/hiecm/v3/milestones/m3): your system is the [HIU](/docs/hiecm/v3/getting-started/glossary#hiu), but the patient starts the share, so there is no consent request and no consent artefact.

Your facility prints a QR code at each counter. It carries your HIU id and a counter id. The patient scans it in their PHR app, picks the care contexts to share, and the [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm) tells your bridge a share is coming. You answer with a data push URL and an encryption key, the records arrive on that URL, and both sides report what was delivered.

[Try the Patient record share APIs](/docs/hiecm/v3/api/record-share)

[Every call in Patient record share, one page each: the headers it needs, the payload it takes, the callback it triggers, and a request builder you can fire at the sandbox.](/docs/hiecm/v3/api/record-share)

[Error codes](/docs/hiecm/v3/api/record-share/errors)

[What each code Patient record share returns actually means, and the first thing to check when you see one.](/docs/hiecm/v3/api/record-share/errors)

## In short

```mermaid
sequenceDiagram
    autonumber
    actor P as Patient
    participant A as Patient's PHR app
    participant CM as HIE-CM
    participant S as Your system
    P->>A: Scans the counter QR code, picks records to share
    A->>CM: POST /api/hiecm/patient-record/v3/share
    CM->>S: POST /api/v3/patient-record/share on your bridge
    Note over CM,S: transactionId, profile.patient, consent.careContexts, dataEraseAt
    S-->>CM: 202
    S->>CM: POST /api/hiecm/patient-record/v3/on-share
    Note over S,CM: hiRequest.dataPushUrl and keyMaterial
    CM->>A: POST /api/v3/patient-record/on-share on the app's callback
    A->>S: Encrypted records to your dataPushUrl
    A->>CM: POST /api/hiecm/patient-record/v3/notify, TRANSFERRED
    S->>CM: POST /api/hiecm/patient-record/v3/notify, RECEIVED
    CM->>A: POST /api/v3/patient-record/on-notify
```

- The patient starts it. You never raise a consent request.
- Two callbacks land on your bridge: the share, then the transfer status.
- You reply once, with a data push URL and an ECDH key, the same key material M3 uses for a consented fetch.
- Records arrive encrypted on your data push URL. Decrypt, store, then notify.
- `consent.dataEraseAt` is the date the patient set. Erase the records by then.

## The calls

Every call carries `REQUEST-ID`, `TIMESTAMP`, the gateway `Authorization` token, `X-CM-ID` and `X-HIU-ID`. The base URL is `https://dev.abdm.gov.in` in sandbox and `https://apis.abdm.gov.in` in production.

| Step     | Who calls                     | Path                                             | Carries                                                                                           |
| -------- | ----------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| 1        | PHR app to HIE-CM             | `POST /api/hiecm/patient-record/v3/share`        | `metaData.hiuId`, `metaData.counterId`, `profile.patient`, `sharedRecordCount`, `consent`         |
| 2        | HIE-CM to your bridge         | `POST /api/v3/patient-record/share`              | The same body plus `transactionId`                                                                |
| 3        | You to HIE-CM                 | `POST /api/hiecm/patient-record/v3/on-share`     | `hiRequest.transactionId`, `hiRequest.dataPushUrl`, `hiRequest.keyMaterial`, `response.requestId` |
| 4        | PHR app to your `dataPushUrl` | `POST`                                           | The encrypted records                                                                             |
| 5        | Both sides to HIE-CM          | `POST /api/hiecm/patient-record/v3/notify`       | `notification.transactionId`, `sessionStatus`, one `hiStatus` per care context                    |
| 6        | HIE-CM to both callbacks      | `POST /api/v3/patient-record/on-notify`          | The other side's status                                                                           |
| Any time | PHR app to HIE-CM             | `GET /api/hiecm/patient-record/v3/audit-history` | Every share for the signed-in address, with `limit`, `offset`, `startDate` and `endDate`          |

Step 2 is a callback on the URL registered for your bridge, not a call you make. Answer it with a 202 at once, then send step 3. The `response.requestId` in step 3 is the `REQUEST-ID` header you received in step 2.

`keyMaterial` is ECDH on curve25519, with your ephemeral public key, its expiry and a nonce. It is the same shape M3 sends in a health information request, so reuse that code. The key exchange is explained under [ECDH](/docs/hiecm/v3/getting-started/glossary#ecdh).

## What each status means

The PHR app reports the send, and you report the receipt. Send your notify once, after the transfer is complete.

| Sender                   | `sessionStatus`                                | `hiStatus` per care context              |
| ------------------------ | ---------------------------------------------- | ---------------------------------------- |
| PHR app or health locker | `TRANSFERRED`, `PARTIAL_TRANSFERRED`, `FAILED` | `DELIVERED`, `ERRORED`                   |
| You, the HIU             | `RECEIVED`, `PARTIAL_RECEIVED`, `FAILED`       | `VALID`, `CORRUPTED`, `BLANK`, `ERRORED` |

Report `FAILED` when nothing arrived or what arrived did not decrypt.

## What you see when it works

Your bridge receives step 2 with a `transactionId`, your step 3 returns 202, records arrive on your `dataPushUrl`, and step 6 brings the app's `TRANSFERRED` status against the same `transactionId`.

## When it goes wrong

- No records after step 3: check that `dataPushUrl` is reachable from the internet and that `keyMaterial.dhPublicKey.expiry` is in the future.
- Records that do not decrypt: report `CORRUPTED` for that care context in step 5, so the patient sees it in their app.
- The share arrives for a counter you do not know: `metaData.counterId` is the value printed in your QR code. Reject with `FAILED` rather than guess.

The request and response bodies, with every field, are on the [Patient scan and record share API reference](/docs/hiecm/v3/api/record-share). NHA has published no swagger for these calls: the reference is built from the API document and Postman collection NHA issued, and no call has been run against sandbox.

## Next

- The milestone this belongs to: [M3 Health Information User](/docs/hiecm/v3/milestones/m3).
- The profile-only version of the same scan: [Scan and Register](/docs/hiecm/v3/use-cases/scan-and-register).
- The patient's side of the share: [P3 Consent and records](/docs/hiecm/v3/milestones/p3).


---

# Scan and Pay

Let a patient pay for their open orders from their [PHR](/docs/hiecm/v3/getting-started/glossary#phr) app after scanning the QR code at your counter. Your system is the [HIP](/docs/hiecm/v3/getting-started/glossary#hip) that holds the orders. The app is the [HIU](/docs/hiecm/v3/getting-started/glossary#hiu) that shows them, takes the selection and the payment, and reports back. The calls run through the [HIE-CM](/docs/hiecm/v3/getting-started/glossary#hie-cm) and land on the bridge you register for [M2](/docs/hiecm/v3/milestones/m2).

[Try the Scan and Pay APIs](/docs/hiecm/v3/api/scan-and-pay/endpoints/scan-and-pay-abdm-hiecm-scan-pay-phr/01-scan-and-pay-post-scan-gateway-v3-patient-share-open-order)

[Every call in Scan and Pay, one page each: the headers it needs, the payload it takes, the callback it triggers, and a request builder you can fire at the sandbox.](/docs/hiecm/v3/api/scan-and-pay/endpoints/scan-and-pay-abdm-hiecm-scan-pay-phr/01-scan-and-pay-post-scan-gateway-v3-patient-share-open-order)

[Error codes](/docs/hiecm/v3/api/scan-and-pay/errors)

[What each code Scan and Pay returns actually means, and the first thing to check when you see one.](/docs/hiecm/v3/api/scan-and-pay/errors)

## In short

```mermaid
sequenceDiagram
    autonumber
    actor P as Patient
    participant A as Patient's PHR app
    participant CM as HIE-CM
    participant S as Your system
    P->>A: Scans the counter QR code
    A->>CM: POST /patient/share/open-order
    CM->>S: POST /v3/patient/share/open-order on your bridge
    S->>CM: POST /patient/on-share/open-order, every open order
    CM->>A: Open orders on the app's callback
    P->>A: Picks the orders to pay
    A->>CM: POST /patient/selection
    CM->>S: POST /v3/patient/selection on your bridge
    S->>CM: POST /patient/on-selection, payment bundle and procedures
    CM->>A: Payment bundle on the app's callback
    P->>A: Pays
    S->>CM: POST /patient/scan-pay/notify, payment status
    CM->>A: Status on the app's callback
    A->>CM: POST /patient/scan-pay/on-notify, received
    CM->>S: POST /v3/patient/scan-pay/on-notify on your bridge
```

- Same counter QR code as [Scan and Register](/docs/hiecm/v3/use-cases/scan-and-register). The app sends the patient's payment details instead of a profile.
- You answer with the patient's open orders. The app sends back the ones the patient picked, and you answer with the payment bundle and its procedures.
- Payment status flows from you to the app, and the app confirms it received it. Either side can ask for the order status later.
- Every callback is a POST on your bridge. Answer 202 at once, then send the matching reply.

Paths are under `/api/hiecm/scan-gateway/v3` on the gateway, and under `/v3` on your bridge. Every call carries `REQUEST-ID`, `TIMESTAMP`, the gateway `Authorization` token and `X-CM-ID`.

## The calls

| Step     | Who calls             | Path                                                        | Carries                                |
| -------- | --------------------- | ----------------------------------------------------------- | -------------------------------------- |
| 1        | PHR app to HIE-CM     | `POST /patient/share/open-order`                            | The patient's payment details          |
| 2        | HIE-CM to your bridge | `POST /v3/patient/share/open-order`                         | The same, with a transaction id        |
| 3        | You to HIE-CM         | `POST /patient/on-share/open-order`                         | Every open order for the patient       |
| 4        | PHR app to HIE-CM     | `POST /patient/selection`                                   | The open orders the patient picked     |
| 5        | HIE-CM to your bridge | `POST /v3/patient/selection`                                | The selection                          |
| 6        | You to HIE-CM         | `POST /patient/on-selection`                                | The payment bundle with its procedures |
| 7        | You to HIE-CM         | `POST /patient/scan-pay/notify`                             | The payment status                     |
| 8        | PHR app to HIE-CM     | `POST /patient/scan-pay/on-notify`                          | Confirmation that the status arrived   |
| Later    | Either side           | `POST /patient/scan-pay/order-status` and `on-order-status` | A status check and its answer          |
| Any time | PHR app to HIE-CM     | `GET /patient/scan-pay/details`                             | Everything held for the patient        |

The request and response bodies, with every field, are on the [Scan and Pay API reference](/docs/hiecm/v3/api/scan-and-pay/endpoints/scan-and-pay-abdm-scan-pay-hip/01-scan-and-pay-post-v3-patient-share-open-order). No call on this page has been run against sandbox.

## What you see when it works

Step 2 arrives on your bridge, your step 3 and step 6 return 202, and step 8 comes back on your bridge with the same transaction id after you send the payment status.

## When it goes wrong

- No selection after step 3: the patient may not have picked anything yet. Your system is waiting on a person, not on a network call.
- No step 8 after step 7: check the status callback URL is registered for your bridge, then use the order status pair to ask.
- A share for a counter you do not know: reject it rather than guess.

## Next

- The profile-only version of the same scan: [Scan and Register](/docs/hiecm/v3/use-cases/scan-and-register).
- The bridge these callbacks land on: [M2 Health Information Provider](/docs/hiecm/v3/milestones/m2).
- The app's side: [P2 Linking and records](/docs/hiecm/v3/milestones/p2).


---

# Scan and Register

```mermaid
sequenceDiagram
    autonumber
    actor P as Patient
    participant A as Patient's PHR app
    participant CM as HIE-CM
    participant S as Your system
    P->>A: Scans the counter QR code, agrees to share
    A->>CM: Share the profile with this HIP and counter
    CM->>S: POST /patient-share/v3/share on your bridge
    Note over CM,S: intent PROFILE_SHARE, metaData.hipId, metaData.context, profile.patient
    S-->>CM: 200, profile received
    S->>S: Register the patient, assign a queue token
    S->>CM: POST /patient-share/v3/on-share with status and tokenNumber
    CM-->>A: Token number to show the patient
```

Support patient registration through QR-based workflows and generate service or queue identifiers in accordance with organization-specific processes. This use case belongs to [M1 Identity](/docs/hiecm/v3/milestones/m1): it uses the ABHA the person already holds.

Your facility prints a QR code at each counter. It holds a URL with two parameters: your HIP id and a counter context such as `OPD1`. The patient scans it in their [PHR](/docs/hiecm/v3/getting-started/glossary#phr) app, agrees to share, and their profile arrives on your bridge. Nobody types a name at the desk, and every record from that visit links to the right ABHA address from the start.

Step 3 is a callback on the URL registered for your bridge, not a call you make. Answer it with a 200 at once and do the registration afterwards. Step 7 is your reply: `acknowledgement.status` is `SUCCESS` with `profile.tokenNumber` and the same `context`, or `FAILURE` with an `error` code and message.

The patient's app holds its screen open for 30 seconds. Send the acknowledgement inside that window or the patient sees no token.

`profile.patient` carries the ABHA number, the ABHA address, name, gender, date of birth, mobile number, address and a KYC photo. Match on the ABHA address. The counter context is yours to define: up to 20 alphanumeric characters, and never the facility id, the HIP id or the HIP name.

The two calls: [receive a patient's shared profile](/docs/hiecm/v3/api/scan-and-register/endpoints/scan-and-register-abdm-patient-share-hip/01-scan-and-register-post-v3-hip-patient-share) and [send the share acknowledgement](/docs/hiecm/v3/api/scan-and-register/endpoints/scan-and-register-abdm-patient-share-hip/02-scan-and-register-post-patient-share-v3-on-share). The patient's side is [P2 Linking and records](/docs/hiecm/v3/milestones/p2#scan-and-share-at-a-facility).


---

# Provider: make the dummy payer send a payment notice

`POST /paymentNotice/init`

Makes the sandbox dummy payer send a payment notice to the provider named, on `/v1/paymentnotice/request`.

### Business purpose

A payment notice only follows a settled claim, which is slow to reach in a test. This hook makes the sandbox's dummy payer, `1000003538@hcx`, send one on demand, so a provider can build and test its payment notice handling and acknowledgement without waiting for a settlement.

### When to use

Use it in the sandbox to make the dummy payer send you a payment notice. Put your own participant code in `providerId`.

### Preconditions

- Your participant is registered with a reachable callback address.
- You host `/v1/paymentnotice/request` and answer it `202` within 30 seconds.
- A valid ABDM session token.

### Postconditions

The notice arrives on `/v1/paymentnotice/request`. You acknowledge it on `/v1/paymentnotice/on_request`.

### Common mistakes

- Triggering the notice before your `/v1/paymentnotice/request` handler is ready.
- Sending another participant's code in `providerId`.
- Never sending the acknowledgement on `/v1/paymentnotice/on_request`.

### Best practices

- Test both the receipt and the acknowledgement.
- Keep this hook out of production code paths. It exists only in the sandbox.

### Related scenario

A provider has built its payment notice handler. It posts this hook with its own participant code in `providerId`. A payment notice from the dummy payer arrives on its `/v1/paymentnotice/request`. The handler answers 202, opens and records the notice, and sends the acknowledgement on `/v1/paymentnotice/on_request`.

### Specification

Chapter [NHCX Use Cases](/docs/nhcx/v1/concepts/nhcx-use-cases) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/dummyhcxpayer/paymentNotice/init \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "providerId": "<participant code>",
  "claimNumber": ""
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Body

- `providerId` (string)
- `claimNumber` (string)

## Responses

- `200`: The dummy payer sends a payment notice to the provider named, arriving on `/v1/paymentnotice/request`.


---

# Adjudicator: act on a case

`POST /pmjay/hcx/nhcxpayerservice/wrapper/process/case`

Approves, rejects, queries, forwards or pends a PMJAY case in the State Health Agency's Transaction Management System, as the role that currently holds it.

In the sandbox this call is reached on `https://apisbeta.nha.gov.in`, a different host from the role lookup, which sits on `https://apisbx.abdm.gov.in`. That is the only published address for it. No production host is published for this call, so obtain it at onboarding and keep it configurable rather than deriving it from the sandbox one.

### Business purpose

This is the action half of the NHCX Payer Service. A PMJAY case sits at `request.initiated` until a role acts on it here, so in the sandbox this call is what makes a case move. A scheme payer building its own side can copy the shape: the exchange carries messages, the queue decides cases, and a case ID the payer issues joins the two.

### When to use

Call it after `Adjudicator: get the user role for a case` names the role that holds the case. Each role accepts its own action names, and `usecase` must match the role.

### Roles and actions

| Step | Role | Actions | `usecase` |
| --- | --- | --- | --- |
| Pre-authorisation | `PPD-Trust` | `Approve`, `Reject`, `Query` | `PREAUTH` |
| Claim 1 | `CEX-Trust` | `Forward` | `CLAIM` |
| Claim 2 | `CPD-Trust` | `cpdApprove`, `cpdReject`, `Pending` | `CLAIM` |
| Claim 3 | Medical Audit Committee | `Approve`, `Reject`, `iQuery` | `Medical Audit Committee` |
| Claim 4 | `ACO-Trust` | `Approve`, `Reject`, `Pending` | `CLAIM` |
| Claim 5 | `SHA-Trust` | `Approve`, `Reject`, `Pending` | `CLAIM` |
| Claim 6 | Claim Review Committee | `Approve`, `Reject`, `Pending` | `Claim Review Committee` |

### Preconditions

- `casenumber` is the scheme's case ID, not the hospital's claim number.
- `action` is spelled exactly as the current role expects. It is case-sensitive.
- A fresh `correlationid` for every call.
- A valid ABDM session token.

### Postconditions

The scheme's decision reaches you over NHCX as a normal `ClaimResponse` on the original request's correlation ID. If the action is refused, the role has moved, so read it again.

### Common mistakes

- Sending `Approve` to `CPD-Trust`, which takes `cpdApprove`.
- Sending `Query` to the Medical Audit Committee, which takes `iQuery`.
- Sending `CLAIM` as `usecase` at a committee, which takes its full name.
- Reusing a correlation ID across calls.
- Raising a second request on a case while the first is still queued.

### Best practices

- Read the role immediately before every action.
- Retry shortly on `Event Meta Log not found for correlationId`, which means the exchange has not finished delivering the request, and on `Case not found for caseId`, which means the case is mid-filing.
- Hold both threads in a test harness: this call, and the callback it causes.
- Report the scheme's pace rather than asserting it. An enhancement may be answered `queued` again and decided minutes later.

### Related scenario

On the recorded sandbox run the pre-authorisation was approved as `PPD-Trust` with `Approve` and `usecase` `PREAUTH`. After the claim was raised it was forwarded by `CEX-Trust`, approved by `CPD-Trust` as `cpdApprove`, then by `ACO-Trust` and `SHA-Trust`, each time after reading the role again and with a new correlation ID. The role lookup then answered with no role, and the approval arrived on the claim's own callback.

### Specification

Chapter [PMJAY adjudication APIs](/docs/nhcx/v1/roles/provider/pmjay-adjudication-apis) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbeta.nha.gov.in/pmjay/hcx/nhcxpayerservice/wrapper/process/case \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "casenumber": "<case number>",
  "action": "Approve",
  "receivercode": "<payer code>",
  "usecase": "PREAUTH",
  "correlationid": "<correlation id>",
  "sendercode": "<participant code>",
  "memberid": "<member id>",
  "remarks": "ok"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the payer service.

## Body

- `casenumber` (string, required): The scheme's case ID, the same one sent to the role lookup as `caseid`.
- `action` (string, required): The action, spelled exactly as the current role takes it in the table above. Case-sensitive. One of: Approve, Reject, Query, Forward, Pending, cpdApprove, cpdReject, iQuery.
- `receivercode` (string, required): The payer's registry code without the `@hcx` suffix, such as `1518`.
- `usecase` (string, required): `PREAUTH` for a pre-authorisation, `CLAIM` for the claim roles, and the committee's full name at the two committees. One of: PREAUTH, CLAIM, Medical Audit Committee, Claim Review Committee.
- `correlationid` (string, required): A new UUID for every request.
- `sendercode` (string, required): Your participant code without the `@hcx` suffix.
- `memberid` (string, required): The beneficiary's member ID.
- `remarks` (string, required): Free text the desk records with the action.

## Responses

- `200`: Acting on the case makes the scheme issue its verdict, which reaches the provider over NHCX as an ordinary `ClaimResponse` on the original request's correlation ID.
  - `status` (string)
  - `message` (string)

Example 200 response. The values are placeholders:

```json
{
  "status": "success",
  "message": "Case processed"
}
```


---

# Adjudicator: get the user role for a case

`POST /pmjay/sbxhcx/nhcxpayerservice/v1/get/user-role`

Asks the NHCX Payer Service which role in the State Health Agency's Transaction Management System holds a PMJAY case, and so which actions may be taken on it next.

### Business purpose

A PMJAY case is not decided over NHCX. The exchange carries the submission to the scheme and the verdict back, but the decision is taken in the SHA's own system, by a named role, on that system's schedule. This call is how an integrator reads that queue. It is also the only way to see where a PMJAY case stands, because a status `Task` sent to the scheme over NHCX is refused, first with `PAYR-1018` and then with `PAYR-1008`.

### When to use

It is mandatory before any claim action. Call it before every `Adjudicator: act on a case`, and whenever a PMJAY case has gone quiet. The case moves on its own, so read the role each time.

### Preconditions

- `caseid` is the scheme's case ID, not the hospital's claim number.
- `payerid` is the scheme payer's code.
- A valid ABDM session token.

### Postconditions

Returns the role that holds the case in `currentuserrole`. A decided case has no role.

### Common mistakes

- Sending the hospital's claim number as `caseid`.
- Acting on the case without reading the role first.
- Taking a pre-authorisation role on a claim as an error. The case is still in the pre-authorisation queue.

### Best practices

- Store the scheme's case ID beside your own claim number the moment it appears.
- Read the role before every action, and again after it.
- Expect this lookup and the action call to sit on different hosts. That is how the service is deployed, not a documentation error.

### Related scenario

A hospital has raised a pre-authorisation that sits at `request.initiated`. It takes the case ID from the payer's acknowledgement and posts it here with the payer code. The answer is `PPD-Trust`, so it approves the case as that role with `Adjudicator: act on a case`. After the claim is raised it reads the role again at every step, through `CEX-Trust`, `CPD-Trust`, `ACO-Trust` and `SHA-Trust`, until the lookup answers with no role and the verdict arrives on the claim's own callback.

### Specification

Chapter [PMJAY adjudication APIs](/docs/nhcx/v1/roles/provider/pmjay-adjudication-apis) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/nhcxpayerservice/v1/get/user-role \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "caseid": "<case number>",
  "payerid": "<payer code>"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the payer service.

## Body

- `caseid` (string, required): The scheme's case ID, such as `2026072210000472`. Not the hospital's claim number.
- `payerid` (string, required): The scheme payer's registry code without the `@hcx` suffix, such as `1518`.

## Responses

- `200`: The service answers with the role that holds the case in `currentuserrole`, and `errormessage` empty.
  - `currentuserrole` (string)
  - `errormessage` (object)

Example 200 response. The values are placeholders:

```json
{
  "currentuserrole": "PPD-Trust",
  "errormessage": null
}
```


---

# Provider: make the dummy payer act on a request

`POST /process/request`

Makes the sandbox dummy payer, participant `1000003538@hcx`, approve, reject or query a pre-authorisation or claim you have submitted, by correlation ID.

### Business purpose

The sandbox hosts a payer that answers back, and this hook decides what it answers. It closes the loop on the first message a new integration sends. Whichever answer comes back proves the token works, the participant record is live, the exchange can reach the provider's address, the dummy payer could open the message, and the provider could read its reply.

### When to use

Use it in the sandbox only. It makes the dummy payer approve, reject or query a pre-authorisation or claim you sent it.

### Preconditions

- You sent a pre-authorisation or claim to the dummy payer and hold its correlation ID.
- Your callback address is registered and answers `202` within 30 seconds.
- A valid ABDM session token.

### Postconditions

The decision arrives on your callback, for example `/v1/preauth/on_submit`, on the same correlation ID. A `Query` first sends you a communication request, which you answer on `/v1/communication/on_request`.

### Common mistakes

- Passing the correlation ID of a request not sent to the dummy payer.
- Waiting for a decision after a `Query` without answering the communication request.
- Reading the rejection of an empty test bundle as a failure. It is the expected answer.

### Best practices

- Test all three outcomes of each flow, not only approval.
- Make the callback handler idempotent, since the exchange retries a missed receipt.
- Keep this hook out of production code paths. It exists only in the sandbox.

### Related scenario

A new provider integration sends the empty bundle from its smoke test to the dummy payer on `/v1/preauth/submit` and gets 202. It posts this hook with `action` `Approve`, `method` `Preauth` and that request's correlation ID. A `ProtocolResponse` refusing the empty bundle lands on its `/v1/preauth/on_submit`, the handler answers 202, and the base framework is proven end to end.

### Specification

Chapter [Building and sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/dummyhcxpayer/process/request \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "action": "Approve",
  "method": "Preauth",
  "correlationId": "<correlation id>"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Body

- `action` (string)
- `method` (string)
- `correlationId` (string)

## Responses

- `200`: The answer arrives on your callback for the request's family, `/v1/preauth/on_submit` for a pre-authorisation, as a sealed `ClaimResponse` or as a `ProtocolResponse` carrying a refusal, on the correlation ID you sent.


---

# Update ABHA number

`POST /update/abhanumber`

Replaces a placeholder (dummy) ABHA number with the beneficiary's real ABHA number in the ABHA_AUTH_TRANSACTION table.

### Business purpose

Beneficiaries are sometimes onboarded before their real ABHA is known, using a placeholder value. Because the member layer and the Patient resource both key on the ABHA number, a placeholder that is never corrected leaves the beneficiary undiscoverable and breaks the identifier rules for claim bundles. This endpoint, tagged Retrieving API and implemented by updateAbhaNumberController, lets the placeholder be swapped for the real number so that later policy lookups and claim transactions line up. The docs describe it as updating the ABHA number in the ABHA_AUTH_TRANSACTION table.

### When to use

Use it when a member's real ABHA number becomes available after they were set up with a placeholder. Do it before you rely on ABHA-based lookups.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- You know both the placeholder and the real ABHA number.

### Postconditions

The member's ABHA number is updated. Errors come back in the same response shape as success, so read `errorMessage`.

### Common mistakes

- Reading errors as the usual registry error format.
- Sending an empty body.
- Forgetting to refresh cached policies that still use the placeholder.

### Best practices

- Record both the placeholder and the real ABHA with the timestamp of the change for audit purposes.
- Read successMessage and errorMessage on every response and treat a non-200 status as failure even if the body parses.
- Immediately re-run /participant/get/policies with forceRefresh: true for the affected beneficiary.
- Keep the ABHA formatting rule per field: hyphen-free for member lookups and x-hcx-ben-ABHA-ID, XX-XXXX-XXXX-XXXX where NHCX-1018 applies.
- Never log the token; log the ABHA change with the request identifier only.

### Related scenario

A state scheme enrols a beneficiary in a hurry with a dummy ABHA so that a policy can be linked and an emergency admission can proceed. After discharge the beneficiary completes ABHA creation and the real number is captured. The payer's system calls /update/abhanumber with dummyAbha and realAbha, receives a successMessage, and then calls /participant/get/policies with forceRefresh to make sure the real ABHA resolves the linked product. The hospital's billing team, preparing the final claim, refreshes its own policy cache so that the Claim bundle's Patient identifiers carry the PMJAY member ID and the real hyphen-free ABHA.

### Specification

Chapter [Participants and policies](/docs/nhcx/v1/registries) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/update/abhanumber \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "dummyAbha": "99999999999999",
  "realAbha": "12345678910111"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the payer service.

## Body

- `dummyAbha` (string)
- `realAbha` (string)

## Responses

- `200`: A successful call returns HTTP 200 with UpdateAbhaResponse, which carries optional successMessage and errorMessage strings.
  - `successMessage` (string)

Example 200 response. The values are placeholders:

```json
{
  "successMessage": "ABHA number updated successfully"
}
```


---

# PMJAY adjudicator

A PMJAY case is not decided over NHCX.

## APIs

The calls fall in two groups. The dummy payer calls drive the sandbox's test payer. The PMJAY payer calls read and act on a PMJAY case in the State Health Agency's Transaction Management System, and replace a placeholder ABHA number.

### Dummy payer APIs

| Call                                                                                                                           | Called by | Environment  | Endpoint                                                                        | What it does                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------ | --------- | ------------ | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Provider: make the dummy payer act on a request](/docs/nhcx/v1/api/adjudicator/endpoints/adjudicator-process-request)         | Provider  | Sandbox only | `POST https://apisbx.abdm.gov.in/pmjay/sbxhcx/dummyhcxpayer/process/request`    | Makes the sandbox dummy payer, participant `1000003538@hcx`, approve, reject or query a pre-authorisation or claim you have submitted, by correlation ID. |
| [Provider: make the dummy payer send a payment notice](/docs/nhcx/v1/api/adjudicator/endpoints/adjudicator-paymentnotice-init) | Provider  | Sandbox only | `POST https://apisbx.abdm.gov.in/pmjay/sbxhcx/dummyhcxpayer/paymentNotice/init` | Makes the sandbox dummy payer send a payment notice to the provider named, on `/v1/paymentnotice/request`.                                                |

### PMJAY payer APIs

Read the role first, then act on the case as that role. Those two calls sit on different hosts. Update ABHA number replaces a placeholder ABHA number and goes to the participant service.

| Call                                                                                                                                            | Called by                                                  | Environment            | Endpoint                                                                               | What it does                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Adjudicator: get the user role for a case](/docs/nhcx/v1/api/adjudicator/endpoints/adjudicator-pmjay-sbxhcx-nhcxpayerservice-v1-get-user-role) | Integrator driving a PMJAY case                            | Sandbox                | `POST https://apisbx.abdm.gov.in/pmjay/sbxhcx/nhcxpayerservice/v1/get/user-role`       | Asks the NHCX Payer Service which role in the State Health Agency's Transaction Management System holds a PMJAY case, and so which actions may be taken on it next. |
| [Adjudicator: act on a case](/docs/nhcx/v1/api/adjudicator/endpoints/adjudicator-pmjay-hcx-nhcxpayerservice-wrapper-process-case)               | Integrator driving a PMJAY case, as the role that holds it | Sandbox                | `POST https://apisbeta.nha.gov.in/pmjay/hcx/nhcxpayerservice/wrapper/process/case`     | Approves, rejects, queries, forwards or pends a PMJAY case in the State Health Agency's Transaction Management System, as the role that currently holds it.         |
| [Update ABHA number](/docs/nhcx/v1/api/adjudicator/endpoints/adjudicator-update-abhanumber)                                                     | Any participant                                            | Sandbox and production | `POST https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/update/abhanumber` | Replaces a placeholder (dummy) ABHA number with the beneficiary's real ABHA number.                                                                                 |

## Base URLs

| Environment                                          | Base URL                                                        |
| ---------------------------------------------------- | --------------------------------------------------------------- |
| Sandbox, Dummy payer.                                | `https://apisbx.abdm.gov.in/pmjay/sbxhcx/dummyhcxpayer`         |
| Sandbox, PMJAY payer service, role lookup.           | `https://apisbx.abdm.gov.in`                                    |
| Sandbox, PMJAY payer service, act on a case.         | `https://apisbeta.nha.gov.in`                                   |
| Production, PMJAY payer service.                     | Not published. Confirm at onboarding.                           |
| Sandbox, Participant service, update ABHA number.    | `https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice` |
| Production, Participant service, update ABHA number. | `https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice`   |

The dummy payer exists only in the sandbox, so it has no production address.

## Guides that use these calls

- [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback)
- [Get your sandbox credentials](/docs/nhcx/v1/getting-started/get-your-sandbox-credentials)
- [PMJAY sandbox run](/docs/nhcx/v1/roles/provider/pmjay-sandbox-run)
- [PMJAY adjudication APIs](/docs/nhcx/v1/roles/provider/pmjay-adjudication-apis)

The whole specification, with a request you can send from the page, is the [PMJAY adjudicator API reference](/reference/nhcx-adjudicator).


---

# Submit the biometric auth init

`POST /hcx/abha/biometric/auth/init`

Starts a fingerprint or iris authentication of a PMJAY beneficiary against the ABHA registry and returns the `txnId` the verify call needs.

### Business purpose

PMJAY requires proof that the beneficiary was physically present. A hospital proves it by authenticating them against their ABHA, biometrically, and the user token that results rides on the eligibility check, the pre-authorisation and the claim. A request without it, and without the consent form that stands in for it, is refused by name. These are ABDM calls built for the PMJAY payer, not NHCX calls: no JWE and no callbacks.

### When to use

Use it at the desk while the beneficiary is present: at admission, at discharge and at every visit of a cyclic case. `scope` picks fingerprint or iris. Face has its own calls, starting with `Face auth init`.

### Preconditions

- The beneficiary's ABHA is linked to their PMJAY card.
- The ABDM session token is on `Authorization: Bearer`.
- `loginId` is the ABHA number with its hyphens.
- A capture device is ready.

### Postconditions

Returns a `txnId`. Send it with the capture to `Biometric auth verify`.

### Common mistakes

- Sending the token on `bearer_auth` only, which gets a `401`.
- Calling the face host instead of `/hcx/abha/biometric/`.
- Stripping the hyphens from `loginId`.
- Setting `lr` to `N` when building the capture.

### Best practices

- Implement fingerprint, iris and face. Each is mandatory, because any one of them may be the only one that works for a given patient.
- Set `process` from the stage of the case, not from a constant.
- Record the transaction ID, the method and the moment it succeeded against the case.

### Related scenario

A PMJAY beneficiary arrives for admission. The desk posts this request with `scope` `["ABHA-login", "Aadhaar-bio-verify"]`, `authMode` `FINGERPRINT`, the ABHA number with hyphens, `process` `Preauth` and the scheme payer's code, and gets a `txnId` back. The fingerprint is captured on the device and sent with that `txnId` to `Biometric auth verify`.

### Specification

Chapter [Biometric authentication](/docs/nhcx/v1/roles/provider/biometric-authentication) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/abha/biometric/auth/init \
  --header 'process: Preauth' \
  --header 'payerid: <payer code>' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-bio-verify"
  ],
  "loginHint": "abha-number",
  "loginId": "91-XXXX-XXXX-1234",
  "otpSystem": "aadhaar",
  "authMode": "FINGERPRINT"
}'
```

## Headers

- `process` (string, required): No source puts `process` or `payerid` on `faceauth/init` or `capture/pid`.
- `payerid` (string, required): `payerid` is the insurer's own participant code. Every insurer has one, even when it works through a TPA.

## Body

- `scope` (string[])
- `loginHint` (string)
- `loginId` (string)
- `otpSystem` (string)
- `authMode` (string)

## Responses

- `200`: Returns the `txnId` that `Biometric auth verify` quotes, with a message saying the authentication request was sent.
  - `txnId` (string)
  - `authMode` (object)
  - `message` (string)
  - `status` (object)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "8c8a12e3-xxxx-4278-xxxx-10acffa44f07",
  "authMode": null,
  "message": "FingerPrint authentication request successfully sent.",
  "status": null
}
```


---

# Get the biometric auth refresh token

`GET /hcx/abha/biometric/auth/refresh/token`

Exchanges the refresh token from `Biometric auth verify` for a new thirty-minute user token without a fresh capture.

### Business purpose

A beneficiary's user token lasts thirty minutes, and a case lasts much longer. The refresh keeps a case authenticated through its transaction cycle without bringing the patient back to the device each time the token lapses.

### When to use

Use it when the user token lapses while a case is still open. Refresh at least once every ten days and keep the new refresh token.

### Preconditions

- A refresh token less than fifteen days old, sent on `R-token`.
- The ABDM session token on `Authorization`, with `payerid` and `process`.

### Postconditions

Returns a new user token and a new refresh token. The new refresh token replaces the old one.

### Common mistakes

- Sending the refresh token on `Authorization` instead of `R-token`.
- Keeping the old refresh token after a refresh.
- Refreshing where a live capture is required, such as each visit of a cyclic case.

### Best practices

- Refresh within every ten days and store the new token.
- Refresh automatically while a case is open. If the token has lapsed and cannot be refreshed, start a fresh authentication.

### Related scenario

A beneficiary's eligibility was checked with a fresh token at admission, but the pre-authorisation is ready only after the thirty minutes have passed. The integration sends the stored refresh token on `R-token` to this endpoint, receives a new user token and a new refresh token, sends the user token on the pre-authorisation, and stores the new refresh token against the case.

### Specification

Chapter [Biometric authentication](/docs/nhcx/v1/roles/provider/biometric-authentication) of the NHCX integration specification.

```bash
curl --request GET \
  --url https://apisbx.abdm.gov.in/hcx/abha/biometric/auth/refresh/token \
  --header 'R-token: Bearer <refresh token>' \
  --header 'payerid: <payer code>' \
  --header 'process: Preauth'
```

## Headers

- `R-token` (string, required): Sent on this call, as the package's request carries it.
- `payerid` (string, required): `payerid` is the insurer's own participant code. Every insurer has one, even when it works through a TPA.
- `process` (string, required): No source puts `process` or `payerid` on `faceauth/init` or `capture/pid`.

## Responses

- `200`: Returns a new user token and a new refresh token.


---

# Submit the biometric auth verify

`POST /hcx/abha/biometric/auth/verify`

Completes the authentication started by `Biometric auth init` with the captured PID block, and returns the beneficiary's user token, valid thirty minutes.

### Business purpose

The user token this call returns is the proof of presence PMJAY asks for. It rides on the eligibility check, the pre-authorisation and the claim. Without it a request must carry the plan's consent questionnaire instead, or it is refused: `PAYR-1256` at the pre-authorisation, `PAYR-1363` at the claim.

### When to use

Call it right after the capture, with the `txnId` from init and the PID block from the device.

### Preconditions

- A `txnId` from `Biometric auth init` for the same method.
- The PID block from the capture device.
- The same headers as init.

### Postconditions

Returns a user token valid for thirty minutes and a refresh token valid for fifteen days. The user token goes on the eligibility check, the pre-authorisation and the claim.

### Common mistakes

- Putting the PID block under the wrong key for the method.
- Storing the token against the session instead of the case.
- Using a refreshed token where a cyclic visit needs a new capture.

### Best practices

- Store the user token and its expiry against the case.
- Store the refresh token, and refresh automatically for the duration of the transaction cycle.
- Keep nothing from the ABHA profile beyond what the encounter needs.

### Related scenario

Right after the fingerprint capture, the desk posts the `txnId` from init and the device's PID block in `fingerPrintAuthPid`, with `authMethods` `["bio"]`. The answer carries a thirty-minute token and a fifteen-day refresh token. The token goes on the header of the eligibility check and the pre-authorisation, and both tokens are stored against the case.

### Specification

Chapter [Biometric authentication](/docs/nhcx/v1/roles/provider/biometric-authentication) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/abha/biometric/auth/verify \
  --header 'process: Preauth' \
  --header 'payerid: <payer code>' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-login",
    "aadhaar-bio-verify"
  ],
  "authData": {
    "authMethods": [
      "bio"
    ],
    "bio": {
      "txnId": "<txn id>",
      "fingerPrintAuthPid": "<pid block>"
    }
  },
  "authMode": "FINGERPRINT"
}'
```

## Headers

- `process` (string, required): No source puts `process` or `payerid` on `faceauth/init` or `capture/pid`.
- `payerid` (string, required): `payerid` is the insurer's own participant code. Every insurer has one, even when it works through a TPA.

## Body

- `scope` (string[])
- `authData` (object)
- `authData.authMethods` (string[])
- `authData.bio` (object)
- `authData.bio.txnId` (string)
- `authData.bio.fingerPrintAuthPid` (string)
- `authMode` (string)

## Responses

- `200`: On success it returns `authResult` `success`, a user `token` with `expiresIn` 1800 seconds, a `refreshToken` with `refreshExpiresIn` 1296000 seconds, fifteen days, and the ABHA `accounts` matched.
  - `txnId` (string)
  - `authResult` (string)
  - `message` (string)
  - `token` (string)
  - `refreshToken` (string)
  - `expiresIn` (integer)
  - `refreshExpiresIn` (integer)
  - `accounts` (object[])
  - `accounts.ABHANumber` (string)
  - `accounts.name` (string)
  - `accounts.status` (string)

Example 200 response. The values are placeholders:

```json
{
  "txnId": "d21b3db9-478a-xxxx-xxxx-8f75e7f86b9f",
  "authResult": "success",
  "message": "… verified successfully",
  "token": "eyZhx….",
  "refreshToken": "eyZhx….",
  "expiresIn": 1800,
  "refreshExpiresIn": 1296000,
  "accounts": [
    {
      "ABHANumber": "91-XXXX-XXXX-1234",
      "name": "…",
      "status": "ACTIVE"
    }
  ]
}
```


---

# Submit the face auth capture PID

`POST /pmjay/sbxhcx/abdmproxy/abha/biometric/capture/pid`

Polls for the face capture the patient completes in the ABHA app after scanning the QR code for the `txnId` from `Face auth init`.

### Business purpose

The face capture happens on the patient's phone, out of the hospital system's sight. This call is how the hospital learns that it has finished. It is the step between showing the QR code and verifying.

### When to use

Call it repeatedly after showing the QR code, until the capture is complete. There is no callback.

### Preconditions

- A `txnId` from `Face auth init`.
- The patient has scanned the QR code.
- The ABDM session token, a fresh `REQUEST-ID` and `TIMESTAMP`, sent to the ABDM proxy host.

### Postconditions

It answers `PENDING` until the patient finishes, then `COMPLETE`. Then call `Face auth verify`.

### Common mistakes

- Waiting for a callback instead of polling.
- Calling `Face auth verify` before this answers `COMPLETE`.
- Sending it to the fingerprint host.

### Best practices

- Poll while the QR code is on screen, and stop when the answer is `COMPLETE`.
- Show the desk that the capture is pending, so the patient is not asked to scan twice.

### Related scenario

The desk has shown the QR code for a discharge face authentication. It polls this endpoint with the `txnId` and gets `PENDING` while the patient completes the scan in the ABHA app. The next poll answers `COMPLETE`, and the desk calls `Face auth verify`.

### Specification

Chapter [Biometric authentication](/docs/nhcx/v1/roles/provider/biometric-authentication) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/abdmproxy/abha/biometric/capture/pid \
  --header 'REQUEST-ID: <uuid>' \
  --header 'TIMESTAMP: <iso timestamp>' \
  --header 'Content-Type: application/json' \
  --data '{
  "txnId": "<txn id>"
}'
```

## Headers

- `REQUEST-ID` (string, required): `REQUEST-ID` is a fresh UUID that you generate for every call. Sending the same one twice is the mistake to avoid; generate it, do not copy it from an example.
- `TIMESTAMP` (string, required): `TIMESTAMP` is the current time in UTC, ISO 8601 with milliseconds and a trailing `Z`, as in `2026-09-04T06:15:51.975Z`. A clock that has drifted will be refused, so take the time from the system rather than constructing it by hand. How to produce it in each language is at the end of this chapter.

## Body

- `txnId` (string)

## Responses

- `200`: Answers `PENDING` with `Awaiting PID capture` until the patient finishes, then `COMPLETE` with `PID capture successful`.
  - `status` (string)
  - `message` (string)

Example 200 response. The values are placeholders:

```json
{
  "status": "COMPLETE",
  "message": "PID capture successful"
}
```


---

# Submit the face auth init

`POST /pmjay/sbxhcx/abdmproxy/abha/biometric/faceauth/init`

Starts a face authentication on the ABDM proxy host and returns the `txnId` the rest of the face flow quotes.

### Business purpose

Face authentication is the method that works when fingerprint and iris do not. The capture happens on the patient's own phone, in the ABHA app, rather than on a hospital device. A case authenticated by fingerprint at admission can be authenticated by face at discharge, because the methods do not have to match across a case.

### When to use

Use it when fingerprint and iris do not work for the patient. The patient completes the face scan on their own phone, in the ABHA app.

### Preconditions

- The ABDM session token on `Authorization`, with a fresh `REQUEST-ID` and `TIMESTAMP`.
- The request goes to the ABDM proxy host, not the fingerprint host.
- The patient has the ABHA app on a phone.

### Postconditions

Returns a `txnId`. Show `https://phrsbx.abdm.gov.in/face-auth?txnId=<txnId>` as a QR code for the patient to scan with the ABHA app.

### Common mistakes

- Sending it to the fingerprint host.
- Waiting for a callback. There is none, so you poll.
- Treating face as optional. All three methods must be built.

### Best practices

- Keep both biometric base paths in configuration.
- Record the `txnId` against the case as soon as it arrives.

### Related scenario

A patient authenticated by fingerprint at admission cannot be captured on the device at discharge. The desk calls this endpoint, shows the QR code built from the `txnId`, and the patient scans it with the ABHA app. The desk polls `Face auth capture PID` until the capture is complete, then calls `Face auth verify`.

### Specification

Chapter [Biometric authentication](/docs/nhcx/v1/roles/provider/biometric-authentication) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/abdmproxy/abha/biometric/faceauth/init \
  --header 'REQUEST-ID: <uuid>' \
  --header 'TIMESTAMP: <iso timestamp>' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": [
    "abha-enrol",
    "face-auth"
  ]
}'
```

## Headers

- `REQUEST-ID` (string, required): `REQUEST-ID` is a fresh UUID that you generate for every call. Sending the same one twice is the mistake to avoid; generate it, do not copy it from an example.
- `TIMESTAMP` (string, required): `TIMESTAMP` is the current time in UTC, ISO 8601 with milliseconds and a trailing `Z`, as in `2026-09-04T06:15:51.975Z`. A clock that has drifted will be refused, so take the time from the system rather than constructing it by hand. How to produce it in each language is at the end of this chapter.

## Body

- `scope` (string[])

## Responses

- `200`: Returns a `txnId`.


---

# Submit the face auth verify

`POST /pmjay/sbxhcx/abdmproxy/abha/biometric/v2/auth/verify`

Completes a face authentication with the encrypted Aadhaar number, the Aadhaar-linked mobile and the `txnId`, and returns the beneficiary's user token.

### Business purpose

It completes the face method with the same outcome as fingerprint and iris: the user token that proves presence to the scheme and rides on the eligibility check, the pre-authorisation and the claim.

### When to use

Call it once `Face auth capture PID` answers `COMPLETE`.

### Preconditions

- The `txnId` from `Face auth init`.
- The Aadhaar number, encrypted with the public key the portal publishes.
- The Aadhaar-linked mobile number.
- The session token and headers, including `payerid` and `process`, sent to the ABDM proxy host.

### Postconditions

Returns the same tokens as `Biometric auth verify`, plus the patient's ABHA profile.

### Common mistakes

- Sending the Aadhaar number unencrypted.
- Checking the encrypted value as if it were a twelve-digit number.
- Logging or storing the encrypted Aadhaar value.
- Sending it to the fingerprint host.

### Best practices

- Never log or store the encrypted Aadhaar value.
- Take from the ABHA profile only what the record needs.
- Store the user token and its expiry against the case.

### Related scenario

The capture for a discharge face authentication has answered `COMPLETE`. The desk encrypts the patient's Aadhaar number with the portal's public key, posts it here with the `txnId` and the Aadhaar-linked mobile, and receives the token pair and the ABHA profile. It stores the token against the case, keeps only the profile fields the record needs, and discards the encrypted value.

### Specification

Chapter [Biometric authentication](/docs/nhcx/v1/roles/provider/biometric-authentication) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/abdmproxy/abha/biometric/v2/auth/verify \
  --header 'REQUEST-ID: <uuid>' \
  --header 'TIMESTAMP: <iso timestamp>' \
  --header 'payerid: <payer code>' \
  --header 'process: Preauth' \
  --header 'Content-Type: application/json' \
  --data '{
  "authData": {
    "authMethods": [
      "face_auth"
    ],
    "face": {
      "txnId": "<txn id>",
      "aadhaar": "<encrypted aadhaar>",
      "mobile": "<aadhaar mobile>"
    }
  },
  "authMode": "FACE_AUTH"
}'
```

## Headers

- `REQUEST-ID` (string, required): `REQUEST-ID` is a fresh UUID that you generate for every call. Sending the same one twice is the mistake to avoid; generate it, do not copy it from an example.
- `TIMESTAMP` (string, required): `TIMESTAMP` is the current time in UTC, ISO 8601 with milliseconds and a trailing `Z`, as in `2026-09-04T06:15:51.975Z`. A clock that has drifted will be refused, so take the time from the system rather than constructing it by hand. How to produce it in each language is at the end of this chapter.
- `payerid` (string, required): `payerid` is the insurer's own participant code. Every insurer has one, even when it works through a TPA.
- `process` (string, required): No source puts `process` or `payerid` on `faceauth/init` or `capture/pid`.

## Body

- `authData` (object)
- `authData.authMethods` (string[])
- `authData.face` (object)
- `authData.face.txnId` (string)
- `authData.face.aadhaar` (string)
- `authData.face.mobile` (string)
- `authMode` (string)

## Responses

- `200`: Returns the same token pair as `Biometric auth verify`, a thirty-minute user token and a fifteen-day refresh token, plus a full ABHA profile: name, date of birth, gender, photo, address, state and district.


---

# ABHA biometric authentication

PMJAY requires proof that the beneficiary was physically present.

## APIs

| Call                                                                                                                       | Called by | Method and path                                              | What it does                                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Biometric auth init](/docs/nhcx/v1/api/biometric/endpoints/biometric-hcx-abha-biometric-auth-init)                        | Provider  | `POST /hcx/abha/biometric/auth/init`                         | Starts a fingerprint or iris authentication of a PMJAY beneficiary against the ABHA registry and returns the `txnId` the verify call needs.                |
| [Biometric auth verify](/docs/nhcx/v1/api/biometric/endpoints/biometric-hcx-abha-biometric-auth-verify)                    | Provider  | `POST /hcx/abha/biometric/auth/verify`                       | Completes the authentication started by `Biometric auth init` with the captured PID block, and returns the beneficiary's user token, valid thirty minutes. |
| [Biometric auth refresh token](/docs/nhcx/v1/api/biometric/endpoints/biometric-hcx-abha-biometric-auth-refresh-token)      | Provider  | `GET /hcx/abha/biometric/auth/refresh/token`                 | Exchanges the refresh token from `Biometric auth verify` for a new thirty-minute user token without a fresh capture.                                       |
| [Face auth init](/docs/nhcx/v1/api/biometric/endpoints/biometric-pmjay-sbxhcx-abdmproxy-abha-biometric-faceauth-init)      | Provider  | `POST /pmjay/sbxhcx/abdmproxy/abha/biometric/faceauth/init`  | Starts a face authentication on the ABDM proxy host and returns the `txnId` the rest of the face flow quotes.                                              |
| [Face auth capture PID](/docs/nhcx/v1/api/biometric/endpoints/biometric-pmjay-sbxhcx-abdmproxy-abha-biometric-capture-pid) | Provider  | `POST /pmjay/sbxhcx/abdmproxy/abha/biometric/capture/pid`    | Polls for the face capture the patient completes in the ABHA app after scanning the QR code for the `txnId` from `Face auth init`.                         |
| [Face auth verify](/docs/nhcx/v1/api/biometric/endpoints/biometric-pmjay-sbxhcx-abdmproxy-abha-biometric-v2-auth-verify)   | Provider  | `POST /pmjay/sbxhcx/abdmproxy/abha/biometric/v2/auth/verify` | Completes a face authentication with the encrypted Aadhaar number, the Aadhaar-linked mobile and the `txnId`, and returns the beneficiary's user token.    |

## Base URLs

| Environment | Base URL                     |
| ----------- | ---------------------------- |
| Sandbox.    | `https://apisbx.abdm.gov.in` |

The six calls share a hostname and split across two bases under it. A client configured with one base reaches only half of them.

| Modality                            | Base, sandbox                                                       |
| ----------------------------------- | ------------------------------------------------------------------- |
| Fingerprint, iris and token refresh | `https://apisbx.abdm.gov.in/hcx/abha/biometric/`                    |
| Face                                | `https://apisbx.abdm.gov.in/pmjay/sbxhcx/abdmproxy/abha/biometric/` |

If fingerprint works and every face call fails, check the base before you check the face flow. [Biometric authentication](/docs/nhcx/v1/roles/provider/biometric-authentication#two-hosts-and-this-is-the-first-thing-to-get-right) sets out both.

## Guides that use these calls

- [Biometric authentication](/docs/nhcx/v1/roles/provider/biometric-authentication)

The whole specification, with a request you can send from the page, is the [ABHA biometric authentication API reference](/reference/nhcx-biometric).


---

# Payer: send the claim response

`POST /v1/claim/on_submit`

Payer returns interim (response.partial) and final (response.complete) ClaimResponseBundles for a claim to the provider via NHCX.

### Business purpose

This callback carries the payer's adjudication of the final claim, possibly in several stages. Interim partial responses let the payer signal receipt, processing and queries while the claim stays open; the complete response fixes the financial decision (approved, partially approved or rejected) and triggers payment advice and settlement. For the hospital it is the source of truth for what will be paid and why; for the payer it is the auditable record of the decision.

### When to use

The payer calls it after each step of reviewing a claim, on the claim's correlation ID. It may come several times: progress updates, a query, then approval or rejection.

### Preconditions

- A claim with this correlation ID exists and is still open.
- A valid access token and the provider's certificate.
- The header echoes the claim's `x-hcx-correlation_ID`, with a new `x-hcx-API_call_ID`.

### Postconditions

- NHCX answers `202` and forwards the response. The provider must answer `202` within 30 seconds.
- After `response.partial` the claim stays open. After `response.complete` it is closed.
- An approval leads to payment notices. After a rejection, the provider may ask for a reprocess.

### Common mistakes

- Treating outcome `complete` as approval. A rejection is also `complete`.
- Stopping after the first callback. More may follow.
- Sending another response after `response.complete`, or using a new correlation ID.
- Replying `202` too slowly, which makes NHCX retry.

### Best practices

- Provider: acknowledge first, then decrypt, then update case state; be idempotent on correlation ID and API_call_ID.
- "Provider: treat the PMJAY query audit trail (USER~datetime~type~comment~actor, entries separated by |; actor is PPD-Trust, CPD-Trust or the hospital name) as display text. Show each entry's comment and never parse a timestamp from it."
- Provider: on complete plus approved, trigger settlement tracking and await 30, 31 and 33; the claim is only closed when 33 arrives and the UTR is persisted.
- Payer: emit 25 on receipt and 28 during processing so the desk sees progress, and put reduction reasons in processNote linked by noteNumber.
- Both: keep x-hcx-status and x-hcx-workflow_ID consistent with the NHA status sheet, since the pair identifies the message.

### Related scenario

A state health agency receives a final claim for 13700 INR against an approved preauth. Its bridge first posts 25 (received) and 28 (in process) as response.partial to /v1/claim/on_submit. The medical auditor finds the investigation report missing and the bridge posts 27 with the query text in the adjudication reason display; the hospital answers under 151 on /v1/claim/submit. Satisfied, the payer posts 26 with outcome complete, reason approved and benefit 13700 as response.complete. The hospital's callback acknowledges each message within 30 seconds, marks the claim adjudicated and waits for the payment notice under workflow 30.

### Specification

Chapter [Claim response](/docs/nhcx/v1/reference/fhir/claim-response) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/claim/on_submit \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.
- `x-hcx-debug_flag` (string): `Error`, `Info` or `Debug`. A server may ignore it. Optional on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: HTTP 202 Accepted with the StatusSuccessResponse acknowledgement (entity_type claim) from NHCX, then asynchronous delivery to the provider's callback, which must acknowledge with 202 within 30 seconds or NHCX retries up to five times before deleting the request.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "19/03/2026 11:46:35:120",
  "api_call_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "correlation_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "result": {
    "sender_code": "<payer participant code>",
    "recipient_code": "<provider participant code>",
    "entity_type": "claim",
    "protocol_status": "request.dispatched"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Provider: submit a claim

`POST /v1/claim/submit`

Provider submits the final itemised Claim bundle (Claim.use claim), or a claim query response or resubmission; NHCX routes it to the payer.

### Business purpose

The claim is where money actually moves. After treatment the provider assembles finalised bills, the complete document set and the preAuthRef, and asks the payer to adjudicate and settle. A well-prepared claim closes within days; a poorly prepared one cycles through queries and resubmissions for weeks. The endpoint gives hospitals a single structured channel for settlement requests and gives payers a complete evidentiary package against which to calculate the approved amount, apply deductions and trigger payment.

### When to use

Use it after discharge to claim payment for a case with an approved pre-authorisation. The same call answers a payer query on the claim: the workflow code in the header says which. A reprocess goes through `/v1/task/submit` instead.

### Preconditions

- An approved pre-authorisation exists, and no claim has been raised for the case yet.
- The bundle is an FHIR `Claim` with `use` set to `claim` and the final bill amounts.
- Discharge details and the required documents are attached. For PMJAY, so is proof of presence at discharge.
- A valid access token, the payer's certificate and a fresh correlation ID.

### Postconditions

- NHCX answers `202` at once. That only means the message was accepted.
- The payer's answers arrive later on `/v1/claim/on_submit`, possibly several times.
- A `response.complete` closes the claim. Nothing more can be sent on it.

### Common mistakes

- Claiming more than the pre-authorisation approved, or items it did not include.
- Answering a claim query as a new claim instead of a query reply.
- Missing documents the payer asked for, which causes a query and delays payment.
- Reusing the pre-authorisation's correlation ID for the claim.

### Best practices

- Start from the approved preauth payload: keep diagnosis and procedure entries, change Claim.use to claim, replace estimates with final amounts and add the full document set.
- Reference preAuthRef and reuse the case number; key every submission on the correlation ID and persist workflow ID and use_case with it.
- Check response.outcome on every callback; partial means the claim is still live, so keep monitoring the same correlation ID.
- Validate supportingInfo value types and discharge codes before encrypting; the PAYR-1098, 1099 and 1501 to 1505 family rejects malformed supporting info.
- For LAMA discharges send stratification with duration; for cyclic procedures send cycle information for every cycle with one biometric record per date (PAYR-1368, PAYR-1369).
- Implement v1/error and use /v1/status with the claim's correlation ID when no callback arrives.

### Related scenario

A patient is discharged home after the corneal grafting approved under preAuthRef PREAUTH-HP-2026-78901. The billing desk takes the preauth bundle, sets Claim.use to claim, records discharge code DTH After Surgery, attaches the discharge summary, operative notes and final itemised bill of 13700 INR, and posts it to /v1/claim/submit under workflow 15 with use_case New and a new correlation ID. NHCX returns 202. The payer sends 25 and 28 as response.partial, then queries under 27 for a missing investigation report; the hospital answers under 151. Approval arrives under 26 as response.complete, and a payment notice follows on /v1/paymentnotice/request.

### Specification

Chapter [Claim request](/docs/nhcx/v1/reference/fhir/claim-request) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/claim/submit \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.
- `x-hcx-use_case` (string): Values differ by exchange. [Domain headers](/docs/nhcx/v1/reference/envelope-fields#domain-headers) lists them. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: NHCX returns HTTP 202 Accepted with a StatusSuccessResponse acknowledgement (entity_type claim) and forwards the request asynchronously.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "19/03/2026 11:46:35:120",
  "api_call_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "correlation_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "result": {
    "sender_code": "<provider participant code>",
    "recipient_code": "<payer participant code>",
    "entity_type": "claim",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Provider receives the claim response

`POST /v1/claim/on_submit`

Hosted by the provider. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/claim/on_submit`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Payer returns interim (response.partial) and final (response.complete) ClaimResponseBundles for a claim to the provider via NHCX.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/claim/on_submit \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.
- `x-hcx-debug_flag` (string): `Error`, `Info` or `Debug`. A server may ignore it. Optional on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "claim",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Payer receives a claim

`POST /v1/claim/submit`

Hosted by the payer. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/claim/submit`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Provider submits the final itemised Claim bundle (Claim.use claim), or a claim query response or resubmission; NHCX routes it to the payer.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/claim/submit \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.
- `x-hcx-use_case` (string): Values differ by exchange. [Domain headers](/docs/nhcx/v1/reference/envelope-fields#domain-headers) lists them. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "claim",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Claim errors

A Claim code arrives sealed inside the callback, not in the response to your call. These are the codes the Catalogue records on this module's paths.

## Codes

| Code                                                                                | What it means                                                                                                                |
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| [`ERR-PYR-CLM-007`](/docs/nhcx/v1/reference/pmjay-error-codes?code=ERR-PYR-CLM-007) | No preauthorisation or claim exists for the claim's case number                                                              |
| [`PAYR-1001`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1001)             | The recipient could not decrypt your request                                                                                 |
| [`PAYR-1002`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1002)             | The payer could not encrypt its answer to you                                                                                |
| [`PAYR-1003`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1003)             | The payer's system could not reach the exchange and will resend, or the workflow requested is not valid                      |
| [`PAYR-1004`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1004)             | Your facility is not registered with the payer for the policy, or the FHIR bundle is malformed                               |
| [`PAYR-1005`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1005)             | The beneficiary is not a covered member of the policy, or the request is more than 24 hours old                              |
| [`PAYR-1006`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1006)             | The policy does not exist, or a name in the request is not valid                                                             |
| [`PAYR-1007`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1007)             | The policy has expired, or the gender in the request is not valid                                                            |
| [`PAYR-1008`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1008)             | The beneficiary's remaining cover is not enough for the request, or the FHIR bundle is not valid or cannot be parsed         |
| [`PAYR-1009`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1009)             | The requested items are not valid or not covered, or the Patient resource has no identifier                                  |
| [`PAYR-1010`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1010)             | A preauthorisation was required but not obtained, or the Patient identifier has no type                                      |
| [`PAYR-1012`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1012)             | The claim amount is more than the approved preauthorisation amount, or the Claim identifier has no type                      |
| [`PAYR-1013`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1013)             | The procedures or packages have no prior approval, or the provider Organization resource has no identifier                   |
| [`PAYR-1014`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1014)             | The date of birth is after the date of service, or the provider Organization identifier has no type                          |
| [`PAYR-1015`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1015)             | The date of service is after the date of death, or the payer Organization resource has no identifier                         |
| [`PAYR-1016`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1016)             | The claim duplicates one already submitted for the same services and dates, or the payer Organization identifier has no type |
| [`PAYR-1017`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1017)             | The amount calculations are not correct, or the Task resource has no task code                                               |
| [`PAYR-1018`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1018)             | The time limit for submission has expired, or the Task resource has no reason code                                           |
| [`PAYR-1019`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1019)             | The additional information the payer asked for did not arrive in time, or a supporting info sequence is not valid            |
| [`PAYR-1020`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1020)             | The payer holds no valid bank details for your facility, or a supporting info category is not valid                          |
| [`PAYR-1021`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1021)             | A supporting info entry has an invalid code                                                                                  |
| [`PAYR-1023`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1023)             | A procedure has an invalid category                                                                                          |
| [`PAYR-1024`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1024)             | A procedure has an invalid status                                                                                            |
| [`PAYR-1025`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1025)             | A procedure has an invalid sequence                                                                                          |
| [`PAYR-1026`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1026)             | The claim references a procedure that is not in the bundle                                                                   |
| [`PAYR-1027`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1027)             | A claim item has an invalid id                                                                                               |
| [`PAYR-1028`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1028)             | A claim item has an invalid sequence                                                                                         |
| [`PAYR-1029`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1029)             | The bundle id is invalid                                                                                                     |
| [`PAYR-1030`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1030)             | A questionnaire id in the bundle is invalid                                                                                  |
| [`PAYR-1031`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1031)             | A bundle entry has an invalid URL                                                                                            |
| [`PAYR-1034`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1034)             | A procedure code is invalid                                                                                                  |
| [`PAYR-1035`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1035)             | The policy code is invalid                                                                                                   |
| [`PAYR-1036`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1036)             | A supporting info entry lacks a valid attachment                                                                             |
| [`PAYR-1040`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1040)             | A reference points at a resource that is not in the bundle                                                                   |
| [`PAYR-1041`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1041)             | A procedure has no identifier                                                                                                |
| [`PAYR-1042`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1042)             | A procedure identifier has no type                                                                                           |
| [`PAYR-1043`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1043)             | A date is in the wrong format                                                                                                |
| [`PAYR-1044`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1044)             | A date and time is in the wrong format                                                                                       |
| [`PAYR-1045`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1045)             | A claim item has an invalid quantity                                                                                         |
| [`PAYR-1046`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1046)             | A supporting info entry has no value or date                                                                                 |
| [`PAYR-1047`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1047)             | A supporting info entry has an invalid reference                                                                             |
| [`PAYR-1048`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1048)             | A supporting info entry references a resource that is not in the bundle                                                      |
| [`PAYR-1049`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1049)             | The payer cannot accept the bundle                                                                                           |
| [`PAYR-1050`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1050)             | A practitioner identifier has no type                                                                                        |
| [`PAYR-1051`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1051)             | A clinical record has no section                                                                                             |
| [`PAYR-1052`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1052)             | A clinical record section has no references                                                                                  |
| [`PAYR-1053`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1053)             | A nested clinical record section has an invalid reference                                                                    |
| [`PAYR-1054`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1054)             | A clinical record section is empty                                                                                           |
| [`PAYR-1055`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1055)             | A clinical record has no subject or its subject is not a patient                                                             |
| [`PAYR-1056`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1056)             | The patient's contact organization is not an Organization                                                                    |
| [`PAYR-1057`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1057)             | The patient's general practitioner has the wrong type                                                                        |
| [`PAYR-1058`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1058)             | The patient's managing organization is not an Organization                                                                   |
| [`PAYR-1059`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1059)             | A clinical record points at something other than an encounter                                                                |
| [`PAYR-1060`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1060)             | A clinical record has no encounter or its encounter has no subject                                                           |
| [`PAYR-1061`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1061)             | An encounter's subject has the wrong resource type                                                                           |
| [`PAYR-1062`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1062)             | An encounter has no episode of care the payer can find                                                                       |
| [`PAYR-1063`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1063)             | An encounter's episode of care has the wrong resource type                                                                   |
| [`PAYR-1064`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1064)             | An encounter has no based-on reference the payer can find                                                                    |
| [`PAYR-1065`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1065)             | An encounter's based-on reference has the wrong resource type                                                                |
| [`PAYR-1066`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1066)             | An encounter has no appointment the payer can find                                                                           |
| [`PAYR-1067`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1067)             | An encounter's appointment has the wrong resource type                                                                       |
| [`PAYR-1068`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1068)             | An encounter has no reason reference the payer can find                                                                      |
| [`PAYR-1069`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1069)             | An encounter's reason reference has the wrong resource type                                                                  |
| [`PAYR-1070`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1070)             | A composition has no author                                                                                                  |
| [`PAYR-1071`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1071)             | A composition's author has the wrong resource type                                                                           |
| [`PAYR-1072`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1072)             | A claim procedure has no procedure reference                                                                                 |
| [`PAYR-1073`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1073)             | An observation has no based-on reference                                                                                     |
| [`PAYR-1074`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1074)             | An observation's based-on reference has the wrong resource type                                                              |
| [`PAYR-1075`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1075)             | An observation has no part-of reference                                                                                      |
| [`PAYR-1076`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1076)             | An observation's part-of reference has the wrong resource type                                                               |
| [`PAYR-1077`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1077)             | An observation has no subject                                                                                                |
| [`PAYR-1078`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1078)             | An observation's subject is not a Patient                                                                                    |
| [`PAYR-1079`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1079)             | The claim has no care team                                                                                                   |
| [`PAYR-1080`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1080)             | A practitioner's HPR id is not valid                                                                                         |
| [`PAYR-1081`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1081)             | An item's service date is not valid                                                                                          |
| [`PAYR-1082`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1082)             | A composition linked from supporting info has an invalid title                                                               |
| [`PAYR-1083`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1083)             | A practitioner has no HPR id                                                                                                 |
| [`PAYR-1084`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1084)             | A reference points at a questionnaire response that is not in the bundle                                                     |
| [`PAYR-1085`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1085)             | A questionnaire response reference points at the wrong resource type                                                         |
| [`PAYR-1086`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1086)             | A reference points at a procedure that is not in the bundle                                                                  |
| [`PAYR-1087`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1087)             | A procedure reference points at the wrong resource type                                                                      |
| [`PAYR-1088`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1088)             | A composition failed the payer's checks                                                                                      |
| [`PAYR-1089`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1089)             | The claim has no billing items                                                                                               |
| [`PAYR-1090`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1090)             | The coverage has no identifier                                                                                               |
| [`PAYR-1091`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1091)             | The coverage identifier has no type                                                                                          |
| [`PAYR-1092`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1092)             | The payer failed while processing your request                                                                               |
| [`PAYR-1093`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1093)             | An encounter linked from a composition has no subject                                                                        |
| [`PAYR-1094`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1094)             | An encounter's subject has the wrong resource type                                                                           |
| [`PAYR-1095`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1095)             | The claim carries no valid discharge information                                                                             |
| [`PAYR-1096`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1096)             | A death discharge carries no valid death date                                                                                |
| [`PAYR-1097`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1097)             | The request arrived with no encrypted payload                                                                                |
| [`PAYR-1098`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1098)             | The registration date has the wrong value type                                                                               |
| [`PAYR-1099`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1099)             | The discharge date has the wrong value type                                                                                  |
| [`PAYR-1102`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1102)             | The id you searched with is not valid                                                                                        |
| [`PAYR-1301`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1301)             | A claim already exists for this case                                                                                         |
| [`PAYR-1302`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1302)             | No approved preauthorisation for this case                                                                                   |
| [`PAYR-1303`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1303)             | No active claim to update for this case                                                                                      |
| [`PAYR-1304`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1304)             | The claim for this case is not under query                                                                                   |
| [`PAYR-1305`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1305)             | The use case is not valid for this case                                                                                      |
| [`PAYR-1306`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1306)             | The procedure is not in the preauthorisation request                                                                         |
| [`PAYR-1307`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1307)             | The procedure quantity is not valid                                                                                          |
| [`PAYR-1308`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1308)             | The procedure is not in the active claim                                                                                     |
| [`PAYR-1309`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1309)             | The implant is not in the preauthorisation request                                                                           |
| [`PAYR-1310`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1310)             | The implant quantity is not valid                                                                                            |
| [`PAYR-1311`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1311)             | The implant is not in the active claim                                                                                       |
| [`PAYR-1312`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1312)             | The investigation is not in the preauthorisation request                                                                     |
| [`PAYR-1313`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1313)             | The investigation quantity is not valid                                                                                      |
| [`PAYR-1314`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1314)             | The investigation is not in the active claim                                                                                 |
| [`PAYR-1315`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1315)             | The procedure was rejected at preauthorisation                                                                               |
| [`PAYR-1316`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1316)             | The investigation was rejected at preauthorisation                                                                           |
| [`PAYR-1317`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1317)             | The implant was rejected at preauthorisation                                                                                 |
| [`PAYR-1318`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1318)             | The claim has no requested treatment plan                                                                                    |
| [`PAYR-1319`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1319)             | The claim has no requested investigation plan                                                                                |
| [`PAYR-1320`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1320)             | The payer has no details for the requested investigations                                                                    |
| [`PAYR-1321`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1321)             | The workflow id is not valid for this step                                                                                   |
| [`PAYR-1322`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1322)             | The case is not in a state that accepts this request                                                                         |
| [`PAYR-1323`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1323)             | The beneficiary's wallet balance is too low                                                                                  |
| [`PAYR-1324`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1324)             | The discharge stage is not valid                                                                                             |
| [`PAYR-1325`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1325)             | The admission date is not valid                                                                                              |
| [`PAYR-1326`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1326)             | The discharge date is not valid                                                                                              |
| [`PAYR-1327`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1327)             | The admission date is in the wrong format                                                                                    |
| [`PAYR-1328`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1328)             | The discharge date is in the wrong format                                                                                    |
| [`PAYR-1329`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1329)             | The registration date is not valid                                                                                           |
| [`PAYR-1330`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1330)             | The registration date is in the wrong format                                                                                 |
| [`PAYR-1331`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1331)             | The receiver is not registered in NHCX                                                                                       |
| [`PAYR-1332`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1332)             | The Claim Review Committee request is not valid                                                                              |
| [`PAYR-1333`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1333)             | The claim type is not valid                                                                                                  |
| [`PAYR-1334`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1334)             | The payer has no configuration for your hospital                                                                             |
| [`PAYR-1335`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1335)             | The implant quantity is not valid                                                                                            |
| [`PAYR-1336`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1336)             | The implant unit price is not valid                                                                                          |
| [`PAYR-1337`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1337)             | The implant net amount is not valid                                                                                          |
| [`PAYR-1338`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1338)             | The implant attachment is not valid                                                                                          |
| [`PAYR-1339`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1339)             | The implant status is not valid                                                                                              |
| [`PAYR-1340`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1340)             | The investigation status is not valid                                                                                        |
| [`PAYR-1341`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1341)             | The investigation attachment is not valid                                                                                    |
| [`PAYR-1342`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1342)             | A case in progress blocks a new reimbursement request                                                                        |
| [`PAYR-1343`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1343)             | A reimbursement was already approved for this case                                                                           |
| [`PAYR-1344`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1344)             | The payer has no details for the requested procedures                                                                        |
| [`PAYR-1345`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1345)             | The procedure status is not valid                                                                                            |
| [`PAYR-1346`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1346)             | The procedure description is not valid                                                                                       |
| [`PAYR-1347`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1347)             | The procedure type is not valid                                                                                              |
| [`PAYR-1348`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1348)             | The procedure factor is not valid                                                                                            |
| [`PAYR-1349`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1349)             | The procedure quantity is not valid                                                                                          |
| [`PAYR-1350`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1350)             | The procedure net amount is not valid                                                                                        |
| [`PAYR-1351`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1351)             | The procedure speciality code is not valid                                                                                   |
| [`PAYR-1352`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1352)             | The beneficiary and care plan do not fit this hospital                                                                       |
| [`PAYR-1353`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1353)             | The care plan id is not valid                                                                                                |
| [`PAYR-1354`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1354)             | The claim failed a payer rule                                                                                                |
| [`PAYR-1355`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1355)             | The payer has no details for the requested implants                                                                          |
| [`PAYR-1356`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1356)             | The wallet is short and the patient cannot pay the difference                                                                |
| [`PAYR-1357`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1357)             | The admission date is after the discharge date                                                                               |
| [`PAYR-1358`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1358)             | The patient was registered too long after admission                                                                          |
| [`PAYR-1359`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1359)             | The claim has no billable treatment plan                                                                                     |
| [`PAYR-1360`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1360)             | An item code is not valid                                                                                                    |
| [`PAYR-1361`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1361)             | An item sequence is not valid                                                                                                |
| [`PAYR-1362`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1362)             | A discharge against medical advice needs the LM100 procedure                                                                 |
| [`PAYR-1363`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1363)             | No biometric authentication and no consent questionnaire at discharge                                                        |
| [`PAYR-1364`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1364)             | A consent questionnaire answer is empty                                                                                      |
| [`PAYR-1365`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1365)             | The standard treatment guideline response is missing                                                                         |
| [`PAYR-1366`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1366)             | The biometric user token is not valid                                                                                        |
| [`PAYR-1367`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1367)             | No biometric record for a cycle date                                                                                         |
| [`PAYR-1368`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1368)             | Cycle information is missing for some cycles                                                                                 |
| [`PAYR-1369`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1369)             | Two biometric authentications on one date for a cyclic procedure                                                             |
| [`PAYR-1370`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1370)             | A supporting detail has an invalid start date                                                                                |
| [`PAYR-1501`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1501)             | The surgery date entry carries the wrong kind of value                                                                       |
| [`PAYR-1502`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1502)             | The admission date entry carries the wrong kind of value                                                                     |
| [`PAYR-1503`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1503)             | The death date entry carries the wrong kind of value                                                                         |
| [`PAYR-1504`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1504)             | The case remarks in your query response are not text                                                                         |
| [`PAYR-1505`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1505)             | A questionnaire response is attached under the wrong category or code                                                        |
| [`PAYR-1506`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1506)             | The newborn's gender is not valid                                                                                            |
| [`PAYR-1507`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1507)             | The newborn's date of birth is not valid                                                                                     |
| [`PAYR-1508`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1508)             | The newborn link does not lead to a Patient resource                                                                         |
| [`PAYR-1509`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1509)             | The newborn's proof of birth attachment is not valid                                                                         |
| [`PAYR-1512`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1512)             | A patient reference does not lead to a Patient resource                                                                      |
| [`PAYR-1513`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1513)             | A diagnosis is not sent as a coded concept                                                                                   |
| [`PAYR-1514`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1514)             | The discharge information entry does not name a discharge stage                                                              |
| [`PAYR-1515`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1515)             | An organisation in your bundle has no name                                                                                   |

Every code above is recorded in the Catalogue. The aggregated list across modules is at [error codes](/docs/nhcx/v1/reference/pmjay-error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# Claim

The claim is where money actually moves.

## APIs

| Call                                                                                         | Called by | Method and path            | What it does                                                                                                                                |
| -------------------------------------------------------------------------------------------- | --------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| [Provider: submit a claim](/docs/nhcx/v1/api/claim/endpoints/claim-v1-claim-submit)          | Provider  | `POST /v1/claim/submit`    | Provider submits the final itemised Claim bundle (Claim.use claim), or a claim query response or resubmission; NHCX routes it to the payer. |
| [Payer: send the claim response](/docs/nhcx/v1/api/claim/endpoints/claim-v1-claim-on-submit) | Payer     | `POST /v1/claim/on_submit` | Payer returns interim (response.partial) and final (response.complete) ClaimResponseBundles for a claim to the provider via NHCX.           |

## One path, two meanings by scheme

Nothing in the envelope names the scheme, so the payer you address decides what `/v1/claim/submit` carries.

| Payer           | What travels on `/v1/claim/submit`                                             | Workflow        |
| --------------- | ------------------------------------------------------------------------------ | --------------- |
| General network | A provisional discharge submission first, then the final claim                 | `14`, then `15` |
| PMJAY           | One combined discharge and claim submission. No separate discharge step exists | `15`            |

[Discharge and claim](/docs/nhcx/v1/roles/provider/discharge-and-claim) and [PMJAY scheme rules](/docs/nhcx/v1/concepts/pmjay-use-cases#scheme-rules-the-hmis-must-implement) carry the detail.

## Callbacks you host

The exchange posts these to the `endpoint_url` you registered. Answer each with HTTP 202 first.

| Path                  | Hosted by    |
| --------------------- | ------------ |
| `/v1/claim/submit`    | The payer    |
| `/v1/claim/on_submit` | The provider |

## Base URLs

| Environment             | Base URL                          |
| ----------------------- | --------------------------------- |
| Sandbox, NHCX exchange. | `https://apisbx.abdm.gov.in/hcx`  |
| Production.             | `https://apisprod.nha.gov.in/hcx` |

## Guides that use these calls

- [Building and sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe)
- [Claim request](/docs/nhcx/v1/reference/fhir/claim-request)
- [Claim response](/docs/nhcx/v1/reference/fhir/claim-response)
- [Claim query and answer](/docs/nhcx/v1/reference/fhir/claim-query-and-answer)

The whole specification, with a request you can send from the page, is the [Claim API reference](/reference/nhcx-claim).


---

# Provider: acknowledge the communication

`POST /v1/communication/on_request`

Provider returns the acknowledgement Task bundle for a payer communication, echoing the reason code and correlation ID so the payer can close the loop.

### Business purpose

A payer that has pushed a TAT alert, grievance, wallet update, policy change or document request needs proof that the hospital received it, because the next adjudication step or SLA clock often depends on it. This callback is that proof. The provider posts a bundle of identical structure to the request, with Task.status completed confirming receipt, and the payer's system can then continue, escalate or wait for the documents. It keeps the entire exchange inside NHCX, auditable by correlation ID, rather than in phone calls and email.

### When to use

The provider calls it to acknowledge a `/v1/communication/request`. It comes after the quick `202` reply and reuses the request's correlation ID and reason.

### Preconditions

- You decrypted the incoming request and answered it `202` within 30 seconds.
- A valid access token and the payer's certificate.
- The acknowledgement mirrors the request and reuses its `x-hcx-correlation_ID`.

### Postconditions

NHCX answers `202` and forwards the acknowledgement to the payer. It only confirms receipt, so the issue itself may still be open.

### Common mistakes

- Using a new correlation ID, so the payer cannot link the acknowledgement.
- Keeping the connection open while someone reads the message, missing the 30-second limit.
- Closing the hospital case because the Communication says `completed`.

### Best practices

- Acknowledge first, process later: return 202 with the acceptance body, queue the bundle, then build and post the on_request acknowledgement asynchronously.
- Switch on Task.reasonCode.code to route: tatquery to the claims desk, walletupdate to the benefit cache, policychange to package rate tables.
- Be idempotent on x-hcx-correlation_ID; the same communication may be redelivered.
- Validate x-hcx-workflow_ID against the workflow of the associated claim or preauth before acting.
- Use IST timestamps and a fresh x-hcx-API_call_ID on the acknowledgement call.
- Log the reason code, category, priority and correlation ID for the audit trail.

### Related scenario

A district hospital receives a communication from the scheme payer on its registered callback: reasonCode additionalinfo, category instruction, asking for an updated discharge summary on a claim submitted last week. The endpoint returns 202 immediately and queues the bundle. The claims desk is notified, and the integration posts the acknowledgement Task on /v1/communication/on_request with the same correlation ID and reasonCode. The desk then attaches the discharge summary through the claim's resubmission path, and the final adjudication arrives later on /v1/claim/on_submit, possibly followed by a payment notice on /v1/paymentnotice/request.

### Specification

Chapter [Communication](/docs/nhcx/v1/reference/fhir/communication) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/communication/on_request \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: The gateway returns HTTP 202 with the StatusSuccessResponse envelope (timestamp, api_call_id, correlation_id, result, error) and forwards the bundle to the payer.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "25/08/2026 11:56:35:004",
  "api_call_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "correlation_id": "11223344-5566-7788-99aa-bbccddeeff00",
  "result": {
    "sender_code": "<provider participant code>",
    "recipient_code": "<payer participant code>",
    "entity_type": "task",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Payer: send a communication request

`POST /v1/communication/request`

Payer pushes a Task plus Communication bundle to a provider mid-claim: TAT alerts, wallet or policy changes, grievances or extra-information requests.

### Business purpose

Every other NHCX exchange is provider-initiated and expects a matching response. Communication inverts that: it is the payer's asynchronous, event-driven channel into the hospital system, used when something must be said about an in-flight case without the provider having asked. It carries TAT breach alerts, grievance notices, wallet or benefit updates, policy or package-rate changes, requests for additional evidence and claim-arbitration intimations. Hospitals benefit because these signals arrive in a structured, routable bundle rather than by phone or email, and payers benefit because adjudication can proceed without waiting for an out-of-band exchange.

### When to use

The payer uses it to send the provider a message outside the pre-authorisation or claim flow, such as a delay notice, a grievance or a request for more information. The workflow code in the header must match the related claim or pre-authorisation.

### Preconditions

- A valid access token and the provider's certificate.
- The bundle is encrypted for the provider.
- The header carries `x-hcx-status` `request.initiated` and a fresh correlation ID.

### Postconditions

- NHCX answers `202` at once. That only means the message was accepted.
- The provider's acknowledgement arrives later on `/v1/communication/on_request`, with the same correlation ID.

### Common mistakes

- Treating the `202` as the provider's answer.
- Sending a workflow code that does not match the related claim or pre-authorisation.
- Reusing a correlation ID from an earlier or failed cycle.
- Using it in place of the query inside a `ClaimResponse`.

### Best practices

- Mint a new UUID for x-hcx-API_call_ID on every call and for x-hcx-correlation_ID on every new communication cycle, including retries after failure.
- Put the routing intent in Task.reasonCode and the message classification in Communication.category, topic and priority; pair additionalinfo with category instruction or questionnaire.
- Use IST timestamps; UTC causes validation failures.
- Persist the correlation ID before posting so the on_request acknowledgement can be matched.
- Expect up to five redeliveries if the provider mis-acknowledges; keep your own handling idempotent.
- Implement v1/error so a message that never reaches the provider is reported back to you.

### Related scenario

A state health agency's TPA notices that a cashless claim from a district hospital has sat in adjudication past the scheme's turnaround threshold. It builds a Task bundle with reasonCode tatquery, category reminder, topic progress-update and priority asap, encrypts it for the hospital and posts /v1/communication/request with the workflow ID of the claim submitted earlier on /v1/claim/submit. The gateway returns 202 and forwards the bundle. The hospital's claims desk is alerted, and its system posts the acknowledgement Task on /v1/communication/on_request with the same correlation ID. Adjudication then continues and the outcome arrives on /v1/claim/on_submit as usual.

### Specification

Chapter [Communication](/docs/nhcx/v1/reference/fhir/communication) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/communication/request \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: The gateway validates the JWE headers, workflow id and NIIP and returns HTTP 202 with a StatusSuccessResponse (timestamp, api_call_id, correlation_id, result with sender_code, recipient_code, entity_type and protocol_status, and an error object).
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "25/08/2026 11:46:35:120",
  "api_call_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "correlation_id": "11223344-5566-7788-99aa-bbccddeeff00",
  "result": {
    "sender_code": "<payer participant code>",
    "recipient_code": "<provider participant code>",
    "entity_type": "task",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Payer receives the communication acknowledgement

`POST /v1/communication/on_request`

Hosted by the payer. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/communication/on_request`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Provider returns the acknowledgement Task bundle for a payer communication, echoing the reason code and correlation ID so the payer can close the loop.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/communication/on_request \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "task",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Provider receives a communication request

`POST /v1/communication/request`

Hosted by the provider. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/communication/request`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Payer pushes a Task plus Communication bundle to a provider mid-claim: TAT alerts, wallet or policy changes, grievances or extra-information requests.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/communication/request \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "task",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Communication errors

A Communication code arrives sealed inside the callback, not in the response to your call. These are the codes the Catalogue records on this module's paths.

## Codes

| Code                                                                    | What it means                                                         |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [`PAYR-1037`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1037) | The communication has no identifier                                   |
| [`PAYR-1038`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1038) | The communication identifier has no type                              |
| [`PAYR-1039`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1039) | The communication has no payload                                      |
| [`PAYR-1516`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1516) | The payer cannot match your error response to any message             |
| [`PAYR-1517`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1517) | Your error was sent encrypted instead of as a protocol response       |
| [`PAYR-1518`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1518) | Your Task resource carries no input parameters                        |
| [`PAYR-1519`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1519) | A Task input parameter has no type                                    |
| [`PAYR-1520`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1520) | The communication reference does not lead to a Communication resource |

Every code above is recorded in the Catalogue. The aggregated list across modules is at [error codes](/docs/nhcx/v1/reference/pmjay-error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# Communication

Every other NHCX exchange is provider-initiated and expects a matching response.

## APIs

| Call                                                                                                                           | Called by | Method and path                     | What it does                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------ | --------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Payer: send a communication request](/docs/nhcx/v1/api/communication/endpoints/communication-v1-communication-request)        | Payer     | `POST /v1/communication/request`    | Payer pushes a Task plus Communication bundle to a provider mid-claim: TAT alerts, wallet or policy changes, grievances or extra-information requests.  |
| [Provider: acknowledge the communication](/docs/nhcx/v1/api/communication/endpoints/communication-v1-communication-on-request) | Provider  | `POST /v1/communication/on_request` | Provider returns the acknowledgement Task bundle for a payer communication, echoing the reason code and correlation id so the payer can close the loop. |

## Callbacks you host

The exchange posts these to the `endpoint_url` you registered. Answer each with HTTP 202 first.

| Path                           | Hosted by    |
| ------------------------------ | ------------ |
| `/v1/communication/request`    | The provider |
| `/v1/communication/on_request` | The payer    |

## Base URLs

| Environment             | Base URL                          |
| ----------------------- | --------------------------------- |
| Sandbox, NHCX exchange. | `https://apisbx.abdm.gov.in/hcx`  |
| Production.             | `https://apisprod.nha.gov.in/hcx` |

## Guides that use these calls

- [Building and sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe)
- [Communication](/docs/nhcx/v1/reference/fhir/communication)

The whole specification, with a request you can send from the page, is the [Communication API reference](/reference/nhcx-communication).


---

# Provider: check coverage eligibility

`POST /v1/coverageeligibility/check`

Provider asks the payer, via NHCX, whether a beneficiary's policy is in force, what it covers and which documents a preauth will need.

### Business purpose

Coverage eligibility is the pre-check a hospital desk runs before committing a patient to a cashless pathway. It confirms three things the desk needs: that the policy is active, what benefits and wallet balance are available, and whether a specific procedure needs authorisation at all. A rejection that would otherwise surface days later at preauth or claim adjudication surfaces in seconds while the patient is still at the counter, which benefits the hospital (less rework), the payer (fewer malformed preauths) and the patient (earlier certainty).

### When to use

- Call it at registration or admission, before you submit a pre-authorisation on `/v1/preauth/submit`.
- Set `purpose` to say what you want back. It takes one or more values:
 - `discovery` finds the beneficiary's policies. Use it only when `/participant/get/policies` gives no policy code.
 - `validation` says whether the policy is in force, with the used amount, available balance and wallet liability.
 - `benefits` says whether a package is covered for this beneficiary.
 - `auth-requirements` says whether a chosen procedure is covered at this hospital, and returns the STG questionnaires and `MAND` document codes the pre-authorisation must carry.
- Send `x-hcx-status` `request.initiated`.
- No workflow code is specific to eligibility. The sample exchange uses `x-hcx-workflow_ID` `11` (PATIENT_ADMITTED).
- Under PMJAY, run an `auth-requirements` check even for an unspecified procedure.

### Preconditions

- You have a valid access token and the payer's certificate.
- `x-hcx-recipient_code` is the processing ID from the policy lookup, not the payer ID.
- `x-hcx-correlation_ID` is a new UUID for this check.
- The bundle names the patient, the coverage, the hospital and the insurer, encrypted for the payer.

### Postconditions

- NHCX answers `202` at once. That only means the message was accepted.
- The payer's answer arrives later on `/v1/coverageeligibility/on_check`.

### Common mistakes

- Treating the `202` as the eligibility answer.
- Using the payer ID as the recipient code instead of the processing ID.
- Reusing a correlation ID from an earlier check.
- Sending a status other than `request.initiated`.

### Best practices

- Persist the correlation ID against the patient episode before posting; it is the only key for matching the callback.
- Refresh the token automatically before the 1200-second expiry and treat a 401 as refresh-and-retry-once.
- Run discovery first only when get/policies gives no policy code, then validation, then auth-requirements for the chosen package; store the returned MAND codes and STG questionnaire references and attach them to the preauth.
- "Match response items to your request by `productOrService` code: the payer answers in the package codes you sent, for example `MG004A`, as NHA's published PMJAY bundles show. The numbers in the handbook's response table (100005, 100478, 100063, 100012) are not item codes; in the published bundles they are questionnaire, document-requirement and question identifiers."
- Use IST timestamps with the +05:30 offset in the protected header.
- Log the 202 body (protocol_status, API_call_ID) so a missing callback can be traced with /v1/status.

### Related scenario

A patient arrives at a district hospital with a PMJAY card. The desk calls /participant/get/policies and receives a processingID for the state health agency. Because the treating doctor wants a corneal grafting package, the desk builds a CoverageEligibilityRequest with purpose validation and auth-requirements, encrypts it for the payer and posts it to /v1/coverageeligibility/check, receiving a 202 with protocol_status request.queued. Minutes later the payer's answer lands on /v1/coverageeligibility/on_check with inforce true, authorizationRequired true and MAND0409 and MAND0104 listed as supporting documents. The desk collects those documents and proceeds to /v1/preauth/submit under workflow 12.

### Specification

Chapter [Coverage eligibility request](/docs/nhcx/v1/reference/fhir/coverage-eligibility-request) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/coverageeligibility/check \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: NHCX replies synchronously with HTTP 202 Accepted and a StatusSuccessResponse acknowledgement (timestamp, api_call_id, correlation_id, result with sender_code, recipient_code, entity_type coverageeligibility and protocol_status such as request.queued or request.dispatched, plus an empty error object).
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "19/03/2026 11:46:35:120",
  "api_call_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "correlation_id": "11223344-5566-7788-99aa-bbccddeeff00",
  "result": {
    "sender_code": "<provider participant code>",
    "recipient_code": "<payer participant code>",
    "entity_type": "coverageeligibility",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Payer: send the coverage eligibility response

`POST /v1/coverageeligibility/on_check`

Payer returns the CoverageEligibilityResponse (policy in force, benefits, auth requirements) or an error to the provider through NHCX.

### Business purpose

This is the answer leg of the eligibility check. The payer (or a TPA acting for it) tells the provider whether the policy is live, which items are covered or excluded, the allowed amounts, whether preauthorisation is required and which supporting documents the preauth must carry. Delivering this before treatment lets the hospital counsel the patient and assemble the right evidence, and lets the payer avoid adjudicating preauths that were never going to be covered.

### When to use

- The payer calls it after it has processed a `/v1/coverageeligibility/check`, with the same `x-hcx-correlation_ID`.
- Set `x-hcx-status` to one of these:
 - `response.complete` for a final answer. Accept `response.completed` as the same value; some samples spell it that way.
 - `response.partial` for a partial answer.
 - `response.error` for a protocol-level rejection, with `x-hcx-error_details` filled in.
- The payload is a CoverageEligibilityResponseBundle with `outcome` `complete`. It says whether the policy is in force (`insurance[*].inforce`), which items are excluded (`item[*].excluded`), and whether a pre-authorisation is needed and with which documents (`item[*].authorizationRequired`, `item[*].authorizationSupporting`).
- A redirect or forward to another payer is also a valid outcome.

### Preconditions

- A check with this correlation ID exists in NHCX.
- The payer has a valid access token and the provider's certificate, and encrypts the answer for the provider.
- `x-hcx-status` is `response.complete`, `response.partial` or `response.error`.
- Business errors go inside the encrypted answer. Only protocol errors go in `x-hcx-error_details`.

### Postconditions

- NHCX answers `202` and forwards the answer to the provider.
- The provider must reply `202` within 30 seconds, or NHCX retries up to five times.
- On success the check is closed and the provider can move on to pre-authorisation.

### Common mistakes

- Replying with `200` or a custom body on the receiving side, which makes NHCX retry.
- Creating a new correlation ID instead of reusing the request's.
- Putting patient or clinical details in `x-hcx-error_details`.

### Best practices

- Acknowledge first, process later: return 202 within 30 seconds and queue decryption and business handling.
- Be idempotent on x-hcx-correlation_ID; the same callback may be redelivered up to five times.
- Set inforce, disposition, excluded, authorizationRequired and authorizationSupporting explicitly so the desk can act without free-text interpretation.
- Use ProtocolResponse with x-hcx-status response.error and a catalogued error code for protocol rejections; put business errors inside the encrypted resource.
- Providers: whitelist the NHCX NAT IPs, expose the callback on a domain name (not IP or port) on an India-based server, and implement v1/error alongside on_check.

### Related scenario

A state health agency's bridge receives an eligibility check for a beneficiary requesting validation and auth-requirements for package SE012A. Its rules engine confirms the policy is active with sufficient wallet balance and that SE012A needs preauthorisation with documents MAND0409, MAND0104 and MAND0062. The bridge builds a CoverageEligibilityResponseBundle, encrypts it for the hospital, sets x-hcx-status response.complete with the original correlation ID and posts it to /v1/coverageeligibility/on_check. NHCX acknowledges with 202 and delivers it to the hospital's callback, which acknowledges within 30 seconds; the hospital then prepares its /v1/preauth/submit.

### Specification

Chapter [Coverage eligibility response](/docs/nhcx/v1/reference/fhir/coverage-eligibility-response) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/coverageeligibility/on_check \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.
- `x-hcx-debug_flag` (string): `Error`, `Info` or `Debug`. A server may ignore it. Optional on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: The gateway (and, when the callback reaches it, the provider system) returns HTTP 202 Accepted with the StatusSuccessResponse acknowledgement echoing correlation_id and api_call_id, entity_type coverageeligibility and a protocol_status.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "19/03/2026 11:46:35:120",
  "api_call_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "correlation_id": "11223344-5566-7788-99aa-bbccddeeff00",
  "result": {
    "sender_code": "<payer participant code>",
    "recipient_code": "<provider participant code>",
    "entity_type": "coverageeligibility",
    "protocol_status": "request.dispatched"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Payer receives a coverage eligibility check

`POST /v1/coverageeligibility/check`

Hosted by the payer. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/coverageeligibility/check`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Provider asks the payer, via NHCX, whether a beneficiary's policy is in force, what it covers and which documents a preauth will need.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/coverageeligibility/check \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "coverageeligibility",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Provider receives the coverage eligibility response

`POST /v1/coverageeligibility/on_check`

Hosted by the provider. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/coverageeligibility/on_check`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Payer returns the CoverageEligibilityResponse (policy in force, benefits, auth requirements) or an error to the provider through NHCX.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/coverageeligibility/on_check \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.
- `x-hcx-debug_flag` (string): `Error`, `Info` or `Debug`. A server may ignore it. Optional on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "coverageeligibility",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Coverage eligibility errors

A Coverage eligibility code arrives sealed inside the callback, not in the response to your call. These are the codes the Catalogue records on this module's paths.

## Codes

| Code                                                                    | What it means                                                                                       |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [`PAYR-1001`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1001) | The recipient could not decrypt your request                                                        |
| [`PAYR-1002`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1002) | The payer could not encrypt its answer to you                                                       |
| [`PAYR-1004`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1004) | Your facility is not registered with the payer for the policy, or the FHIR bundle is malformed      |
| [`PAYR-1005`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1005) | The beneficiary is not a covered member of the policy, or the request is more than 24 hours old     |
| [`PAYR-1006`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1006) | The policy does not exist, or a name in the request is not valid                                    |
| [`PAYR-1007`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1007) | The policy has expired, or the gender in the request is not valid                                   |
| [`PAYR-1014`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1014) | The date of birth is after the date of service, or the provider Organization identifier has no type |
| [`PAYR-1029`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1029) | The bundle id is invalid                                                                            |
| [`PAYR-1031`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1031) | A bundle entry has an invalid URL                                                                   |
| [`PAYR-1032`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1032) | The eligibility check has an invalid purpose                                                        |
| [`PAYR-1033`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1033) | The eligibility check has no items for its purpose                                                  |
| [`PAYR-1035`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1035) | The policy code is invalid                                                                          |
| [`PAYR-1040`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1040) | A reference points at a resource that is not in the bundle                                          |
| [`PAYR-1043`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1043) | A date is in the wrong format                                                                       |
| [`PAYR-1044`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1044) | A date and time is in the wrong format                                                              |
| [`PAYR-1049`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1049) | The payer cannot accept the bundle                                                                  |
| [`PAYR-1090`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1090) | The coverage has no identifier                                                                      |
| [`PAYR-1091`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1091) | The coverage identifier has no type                                                                 |
| [`PAYR-1092`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1092) | The payer failed while processing your request                                                      |
| [`PAYR-1097`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1097) | The request arrived with no encrypted payload                                                       |
| [`PAYR-1101`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1101) | The eligibility purpose is not valid                                                                |
| [`PAYR-1102`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1102) | The id you searched with is not valid                                                               |
| [`PAYR-1103`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1103) | The care plan id is not valid                                                                       |
| [`PAYR-1104`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1104) | More than one beneficiary record matches                                                            |
| [`PAYR-1105`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1105) | The payer has no configuration for your hospital                                                    |
| [`PAYR-1106`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1106) | The payer has no details for a requested procedure                                                  |
| [`PAYR-1107`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1107) | The check carries no billable item                                                                  |
| [`PAYR-1108`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1108) | The payer has no details for the requested stratification                                           |
| [`PAYR-1109`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1109) | The payer has no details for a requested investigation                                              |
| [`PAYR-1110`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1110) | The payer has no details for a requested implant                                                    |
| [`PAYR-1111`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1111) | A payer rule rejected the request                                                                   |
| [`PAYR-1112`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1112) | The payer id is not valid                                                                           |
| [`PAYR-1113`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1113) | An item code is not valid                                                                           |
| [`PAYR-1114`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1114) | An item's speciality code is not valid                                                              |
| [`PAYR-1115`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1115) | An item's quantity is not valid                                                                     |
| [`PAYR-1116`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1116) | Your hospital is not authorised under the policy                                                    |
| [`PAYR-1117`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1117) | The payer has no details for the policy                                                             |
| [`PAYR-1118`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1118) | The payer has no details for the requested items                                                    |
| [`PAYR-1119`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1119) | The payer received no details for the payer id from the exchange                                    |
| [`PAYR-1120`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1120) | The reference id has been used before                                                               |
| [`PAYR-1121`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1121) | The policy is not found for this beneficiary                                                        |
| [`PAYR-1122`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1122) | The beneficiary has no policy with the payer                                                        |
| [`PAYR-1123`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1123) | The beneficiary is not covered by this payer                                                        |
| [`PAYR-1512`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1512) | A patient reference does not lead to a Patient resource                                             |
| [`PAYR-1513`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1513) | A diagnosis is not sent as a coded concept                                                          |
| [`PAYR-1515`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1515) | An organisation in your bundle has no name                                                          |

Every code above is recorded in the Catalogue. The aggregated list across modules is at [error codes](/docs/nhcx/v1/reference/pmjay-error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# Coverage eligibility

Coverage eligibility is the pre-check a hospital desk runs before committing a patient to a cashless pathway.

## APIs

| Call                                                                                                                                 | Called by | Method and path                         | What it does                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------ | --------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| [Provider: check coverage eligibility](/docs/nhcx/v1/api/eligibility/endpoints/eligibility-v1-coverageeligibility-check)             | Provider  | `POST /v1/coverageeligibility/check`    | Provider asks the payer, via NHCX, whether a beneficiary's policy is in force, what it covers and which documents a preauth will need. |
| [Payer: send the coverage eligibility response](/docs/nhcx/v1/api/eligibility/endpoints/eligibility-v1-coverageeligibility-on-check) | Payer     | `POST /v1/coverageeligibility/on_check` | Payer returns the CoverageEligibilityResponse (policy in force, benefits, auth requirements) or an error to the provider through NHCX. |

## Callbacks you host

The exchange posts these to the `endpoint_url` you registered. Answer each with HTTP 202 first.

| Path                               | Hosted by    |
| ---------------------------------- | ------------ |
| `/v1/coverageeligibility/check`    | The payer    |
| `/v1/coverageeligibility/on_check` | The provider |

## Base URLs

| Environment             | Base URL                          |
| ----------------------- | --------------------------------- |
| Sandbox, NHCX exchange. | `https://apisbx.abdm.gov.in/hcx`  |
| Production.             | `https://apisprod.nha.gov.in/hcx` |

## Guides that use these calls

- [Building and sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe)
- [Coverage eligibility request](/docs/nhcx/v1/reference/fhir/coverage-eligibility-request)
- [Coverage eligibility response](/docs/nhcx/v1/reference/fhir/coverage-eligibility-response)

The whole specification, with a request you can send from the page, is the [Coverage eligibility API reference](/reference/nhcx-eligibility).


---

# API references

Every endpoint below is generated from the specification that declares it. Each one has its own page with the headers, the body and a request you can send.

This page lists every module, including any that the role you have chosen does not use. The sidebar shows only yours.

## [Session](/docs/nhcx/v1/api/session/)

1 endpoint, with its own page in the sidebar.

[Open the Session overview](/docs/nhcx/v1/api/session/). The whole specification is also on [one page](/reference/nhcx-session).

## [Participant registry](/docs/nhcx/v1/api/registry/)

21 endpoints, each with its own page in the sidebar.

[Open the Participant registry overview](/docs/nhcx/v1/api/registry/). The whole specification is also on [one page](/reference/nhcx-registry).

## [Coverage eligibility](/docs/nhcx/v1/api/eligibility/)

4 endpoints, each with its own page in the sidebar.

[Open the Coverage eligibility overview](/docs/nhcx/v1/api/eligibility/). The whole specification is also on [one page](/reference/nhcx-eligibility).

## [Insurance plan](/docs/nhcx/v1/api/insurance-plan/)

4 endpoints, each with its own page in the sidebar.

[Open the Insurance plan overview](/docs/nhcx/v1/api/insurance-plan/). The whole specification is also on [one page](/reference/nhcx-insurance-plan).

## [Pre-authorisation](/docs/nhcx/v1/api/preauth/)

4 endpoints, each with its own page in the sidebar.

[Open the Pre-authorisation overview](/docs/nhcx/v1/api/preauth/). The whole specification is also on [one page](/reference/nhcx-preauth).

## [Claim](/docs/nhcx/v1/api/claim/)

4 endpoints, each with its own page in the sidebar.

[Open the Claim overview](/docs/nhcx/v1/api/claim/). The whole specification is also on [one page](/reference/nhcx-claim).

## [Reprocess, cancel and shortfall](/docs/nhcx/v1/api/task/)

4 endpoints, each with its own page in the sidebar.

[Open the Reprocess, cancel and shortfall overview](/docs/nhcx/v1/api/task/). The whole specification is also on [one page](/reference/nhcx-task).

## [Payment notice](/docs/nhcx/v1/api/payment-notice/)

4 endpoints, each with its own page in the sidebar.

[Open the Payment notice overview](/docs/nhcx/v1/api/payment-notice/). The whole specification is also on [one page](/reference/nhcx-payment-notice).

## [Communication](/docs/nhcx/v1/api/communication/)

4 endpoints, each with its own page in the sidebar.

[Open the Communication overview](/docs/nhcx/v1/api/communication/). The whole specification is also on [one page](/reference/nhcx-communication).

## [Status and search](/docs/nhcx/v1/api/status/)

6 endpoints, each with its own page in the sidebar.

[Open the Status and search overview](/docs/nhcx/v1/api/status/). The whole specification is also on [one page](/reference/nhcx-status).

## [Onboarding](/docs/nhcx/v1/api/onboarding/)

5 endpoints, each with its own page in the sidebar.

[Open the Onboarding overview](/docs/nhcx/v1/api/onboarding/). The whole specification is also on [one page](/reference/nhcx-onboarding).

## [PMJAY adjudicator](/docs/nhcx/v1/api/adjudicator/)

5 endpoints across 2 groups: Dummy payer APIs, PMJAY payer APIs. Each endpoint has its own page in the sidebar.

[Open the PMJAY adjudicator overview](/docs/nhcx/v1/api/adjudicator/). The whole specification is also on [one page](/reference/nhcx-adjudicator).

## [ABHA biometric authentication](/docs/nhcx/v1/api/biometric/)

6 endpoints, each with its own page in the sidebar.

[Open the ABHA biometric authentication overview](/docs/nhcx/v1/api/biometric/). The whole specification is also on [one page](/reference/nhcx-biometric).

## [Other](/docs/nhcx/v1/api/other/)

7 endpoints, each with its own page in the sidebar.

[Open the Other overview](/docs/nhcx/v1/api/other/). The whole specification is also on [one page](/reference/nhcx-other).


---

# Payer: send the insurance plan

`POST /v1/insuranceplan/on_request`

Payer returns the InsurancePlan collection Bundle (InsurancePlan, Organisation, optional Questionnaire) under the request correlation ID.

### Business purpose

This callback delivers the digital policy that every later preauth and claim is judged against. The payer publishes, for one policy and one hospital, the empanelled specialities, packages and rates, cost qualifiers for implants and stratification, exclusions, claim conditions and mandatory documents, and the questionnaires for standard treatment guidelines or history. Hospitals use it to select packages and validate submissions before they go out; payers use it to cut malformed requests and to make the MoU an enforceable, machine-readable contract view rather than a PDF.

### When to use

The payer calls it after receiving a plan request, with the same correlation ID. It sends the plan for that policy and hospital, or an error if no plan can be produced.

### Preconditions

- The payer has already replied `202` to the incoming request.
- The payer has a valid access token and the provider's certificate, and encrypts the plan for the provider.
- The bundle holds the `InsurancePlan`, the organisations and any questionnaires.
- The correlation ID matches the request, and the call ID is new.

### Postconditions

- NHCX answers `202` and forwards the plan to the provider, who must reply `202` within 30 seconds.
- The provider may cache the plan and checks later pre-authorisations and claims against it.

### Common mistakes

- Returning the plan in the `202` reply to the request.
- Creating a new correlation ID instead of reusing the request's.
- Sending the full package list instead of the part that applies to this hospital.
- Provider side: treating an empty plan as a transport failure.

### Best practices

- Acknowledge the inbound request first, build the bundle asynchronously, then post this callback.
- Filter to the requesting provider's empanelled specialities and the named policy; include Questionnaire resources for mandatory documents and STGs.
- Use the documented claim-condition codes (GovtReserved, ApprovalNotRequired, EnhancementAllowed, QuantityAllowed, IsDayCare, ImplantApplicable, StratificationAllowed, Standalone, ParentProcedure, Unspecified) so provider systems can enforce them.
- Provider side: cache with periodic refresh, refresh when treatment changes, and validate preauth items against the plan's speciality and package codes.
- Use a fresh API_call_ID, IST timestamp and response.complete or response.error.

### Related scenario

A state health agency's payer platform receives a plan discovery Task from an empanelled hospital for policy PMJAY with the hospital's HFR ID. It returns 202, then generates the InsurancePlan bundle: General Medicine and Ophthalmology as specificCost categories, each package as a benefit with its rate, implant qualifiers on the packages that allow them, EnhancementAllowed and Standalone conditions, and the proof-of-identity questionnaire. It posts /v1/insuranceplan/on_request under the same correlation ID. The hospital acknowledges within 30 seconds, caches the plan, selects a package, and moves to /v1/coverageeligibility/check before submitting the preauth.

### Specification

Chapter [Insurance plan response](/docs/nhcx/v1/reference/fhir/insurance-plan-response-overview) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/insuranceplan/on_request \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: The gateway returns HTTP 202 with the StatusSuccessResponse envelope (400, 404 and 500 in the same shape) and forwards the bundle to the provider's registered endpoint, which must acknowledge with 202 within 30 seconds.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "25/08/2026 09:12:00:502",
  "api_call_id": "c9d0e1f2-a3b4-5678-2345-789012345678",
  "correlation_id": "44556677-8899-aabb-ccdd-eeff00112233",
  "result": {
    "sender_code": "<payer participant code>",
    "recipient_code": "<provider participant code>",
    "entity_type": "insuranceplan",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Provider: request an insurance plan

`POST /v1/insuranceplan/request`

Provider sends a Task with code poll naming both a policy number and its HFR ID to fetch the payer's machine-readable InsurancePlan for that pairing.

### Business purpose

Policies have traditionally been PDFs that hospital desks interpret by hand, producing ambiguity about benefits, claim conditions and documents, and rework and rejections downstream. The InsurancePlan API replaces that with a structured, provider-specific, policy-specific contract view: empanelled specialities, package codes and rates, implant and stratification qualifiers, claim conditions such as EnhancementAllowed or Standalone, mandatory documents and questionnaires. Hospitals gain an authoritative view before treatment; payers gain fewer malformed preauths and claims. It is one of the most critical APIs for implementors.

### When to use

Call it before any pre-authorisation or claim for a payer and policy, ideally at registration. It fetches the plan: covered treatments, rates and required documents.

### Preconditions

- You have a valid access token and the payer's certificate.
- The request is an FHIR `Task` with both the policy number and the hospital's HFR ID.
- `x-hcx-recipient_code` is the processing ID, not the payer ID, and the correlation ID is new.

### Postconditions

- NHCX answers `202` at once. That is a receipt, not the plan.
- The plan arrives later on `/v1/insuranceplan/on_request`. It may be empty if nothing matches.

### Common mistakes

- Sending a `Task` without both the policy number and the HFR ID.
- Expecting the plan in the `202` response.
- Sending a new request while an earlier one is still with the payer.
- Treating an empty plan as a gateway fault.

### Best practices

- Integrate deeply: call at registration or admission, before cost estimation, and together with coverage eligibility.
- Cache the returned plan and refresh on a schedule or when the treatment plan changes; it is provider-, policy- and MoU-specific.
- Enforce the returned claim conditions (GovtReserved, EnhancementAllowed, QuantityAllowed, ImplantApplicable, Standalone, ParentProcedure, Unspecified) locally before building preauths.
- Persist the correlation ID so the on_request callback can be matched; mint a new one for each discovery cycle.
- Use IST timestamps and a fresh API_call_ID per call.
- Stand up the on_request receiver and v1/error before the first request.

### Related scenario

A PMJAY beneficiary arrives at an empanelled hospital's admission desk. After the desk fetches the patient's policies through the participant registry and resolves the processingID, the integration posts /v1/insuranceplan/request with a Task carrying policyNumber and the hospital's HFR ID. The gateway returns 202. Minutes later the payer's package master arrives on /v1/insuranceplan/on_request: the hospital's empanelled specialities, package codes, rates, implant qualifiers and the mandatory-document questionnaire. The desk selects the relevant package, checks the claim conditions, and proceeds to /v1/coverageeligibility/check and then /v1/preauth/submit.

### Specification

Chapter [Insurance plan request](/docs/nhcx/v1/reference/fhir/insurance-plan-request) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/insuranceplan/request \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: The gateway returns HTTP 202 with a StatusSuccessResponse whose result carries sender_code, recipient_code, entity_type insuranceplan and protocol_status; 400, 404 and 500 use the same envelope.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "25/08/2026 09:05:00:188",
  "api_call_id": "b8c9d0e1-f2a3-4567-1234-678901234567",
  "correlation_id": "44556677-8899-aabb-ccdd-eeff00112233",
  "result": {
    "sender_code": "<provider participant code>",
    "recipient_code": "<payer participant code>",
    "entity_type": "insuranceplan",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Provider receives the insurance plan

`POST /v1/insuranceplan/on_request`

Hosted by the provider. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/insuranceplan/on_request`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Payer returns the InsurancePlan collection Bundle (InsurancePlan, Organisation, optional Questionnaire) under the request correlation ID.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/insuranceplan/on_request \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "insuranceplan",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Payer receives an insurance plan request

`POST /v1/insuranceplan/request`

Hosted by the payer. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/insuranceplan/request`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Provider sends a Task with code poll naming both a policy number and its HFR ID to fetch the payer's machine-readable InsurancePlan for that pairing.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/insuranceplan/request \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "insuranceplan",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Insurance plan errors

A Insurance plan code arrives sealed inside the callback, not in the response to your call. These are the codes the Catalogue records on this module's paths.

## Codes

| Code                                                                    | What it means                                                          |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [`PAYR-1035`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1035) | The policy code is invalid                                             |
| [`PAYR-1401`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1401) | The policy is not allowed for your hospital                            |
| [`PAYR-1402`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1402) | The payer has no policy with the code you requested                    |
| [`PAYR-1403`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1403) | The renewal does not belong to the requested policy                    |
| [`PAYR-1404`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1404) | No treatment is configured for the policy under any speciality         |
| [`PAYR-1405`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1405) | The payer has no enrolled hospital for your HFR id or sender code      |
| [`PAYR-1406`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1406) | An earlier insurance plan request for the same policy is still running |
| [`PAYR-1510`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1510) | A parameter code in your request is not valid                          |
| [`PAYR-1511`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1511) | A parameter value in your request is not valid                         |
| [`PAYR-1518`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1518) | Your Task resource carries no input parameters                         |
| [`PAYR-1519`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1519) | A Task input parameter has no type                                     |

Every code above is recorded in the Catalogue. The aggregated list across modules is at [error codes](/docs/nhcx/v1/reference/pmjay-error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# Insurance plan

Policies have traditionally been PDFs that hospital desks interpret by hand, producing ambiguity about benefits, claim conditions and documents, and rework and rejections downstream.

## APIs

| Call                                                                                                                      | Called by | Method and path                     | What it does                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Provider: request an insurance plan](/docs/nhcx/v1/api/insurance-plan/endpoints/insurance-plan-v1-insuranceplan-request) | Provider  | `POST /v1/insuranceplan/request`    | Provider sends a Task with code poll naming both a policy number and its HFR id to fetch the payer's machine-readable InsurancePlan for that pairing. |
| [Payer: send the insurance plan](/docs/nhcx/v1/api/insurance-plan/endpoints/insurance-plan-v1-insuranceplan-on-request)   | Payer     | `POST /v1/insuranceplan/on_request` | Payer returns the InsurancePlan collection Bundle (InsurancePlan, Organization, optional Questionnaire) under the request correlation id.             |

## Callbacks you host

The exchange posts these to the `endpoint_url` you registered. Answer each with HTTP 202 first.

| Path                           | Hosted by    |
| ------------------------------ | ------------ |
| `/v1/insuranceplan/request`    | The payer    |
| `/v1/insuranceplan/on_request` | The provider |

## Base URLs

| Environment             | Base URL                          |
| ----------------------- | --------------------------------- |
| Sandbox, NHCX exchange. | `https://apisbx.abdm.gov.in/hcx`  |
| Production.             | `https://apisprod.nha.gov.in/hcx` |

## Guides that use these calls

- [Building and sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe)
- [Insurance plan request](/docs/nhcx/v1/reference/fhir/insurance-plan-request)
- [Insurance plan response](/docs/nhcx/v1/reference/fhir/insurance-plan-response-overview)

The whole specification, with a request you can send from the page, is the [Insurance plan API reference](/reference/nhcx-insurance-plan).


---

# Submit the participant create (v1)

`POST /participant/create`

Sandbox call. Creates a participant record in the NHCX registry from a full v1 profile and returns the generated participant_code.

### Business purpose

Nothing moves through NHCX until both the sender and the recipient exist in the participant registry, which the platform treats as the source of truth for who may exchange claims data. This call is the original, full-profile way to register a hospital, insurer or TPA: it captures the organisation's name, roles, contact points, linked registry identifiers, callback endpoint and public encryption certificate in one record. The registry then issues the participant_code that every later transaction is addressed with.

### When to use

Call it once in the sandbox, when you first register, before any other NHCX call. The sandbox address is `https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/create`. In production, register with `/v2/participant/create` followed by `GET /validate`. To change a certificate or callback URL later, use an update call.

### Preconditions

- Your registration was approved and you hold a client ID and secret.
- You have a valid access token.
- You have made your key pair and certificate, and Base64-encoded the certificate.
- You have the right registry ID: HFR ID for providers, IRDAI ID for payers and TPAs.

### Postconditions

The registry returns your `participant_code`. You cannot send transactions with it until NHCX activates the record.

### Common mistakes

- Sending the wrong registry ID, or an IRDAI ID with leading zeros.
- Using v2 field names such as `endpointurl` in this v1 body.
- Registering a callback URL with an IP address or a port.
- Sending the raw PEM certificate instead of the Base64 form.

### Best practices

- Keep the private key generated alongside the certificate in PKCS8 form locally; only the certificate (public half) is registered.
- Store the returned participant_code as configuration; it becomes x-hcx-sender_code on every outbound message and the value payers use in /fetch/certs.
- Do not re-run create to fix a field; the registry is updated with /participant/update, and an entity can legitimately hold several participant codes only when each is linked to a separate HFR ID.
- Log the request minus the certificate body and never log the bearer token or client_secret.
- Treat host and prefix as one environment variable; sandbox codes and credentials do not carry into production.

### Related scenario

A 200-bed hospital has been approved for the NHCX sandbox and received its client credentials. The integration team first calls POST /get/session to obtain a Bearer token, then generates an RSA key pair and self-signed certificate. They call /participant/create with the hospital's HFR ID as registryid, role PROVIDER, the Base64 certificate and their callback base URL. The registry returns participant_code 100001@sbx. With that code in hand the team calls /fetch/participants/list to find the dummy payer 1000003538@hcx and /fetch/certs to obtain its certificate, and only then sends the first /v1/coverageeligibility/check.

### Specification

Chapter [Your certificate](/docs/nhcx/v1/getting-started/your-certificate) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/create \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'source: internal' \
  --header 'Content-Type: application/json' \
  --data '{
  "linked_registry_codes": [
    "10001"
  ],
  "registryid": "<client id>",
  "participant_name": "Test Hospital",
  "scheme_code": "PMJAY",
  "state": "Haryana",
  "district": "Panchkula",
  "roles": [
    "10001"
  ],
  "primaryEmail": "integration@hospital.example",
  "phone": [
    "01123456789"
  ],
  "primaryMobile": "9876543210",
  "signing_cert_path": "",
  "encryption_cert": "<encryption cert>",
  "endpoint_url": "https://nhcx.hospital.example"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.
- `source` (string, required): Sent on this call, as the package's request carries it.

## Body

- `linked_registry_codes` (string[])
- `registryid` (string)
- `participant_name` (string)
- `scheme_code` (string)
- `state` (string)
- `district` (string)
- `roles` (string[])
- `primaryEmail` (string)
- `phone` (string[])
- `primaryMobile` (string)
- `signing_cert_path` (string)
- `encryption_cert` (string)
- `endpoint_url` (string)

## Responses

- `200`: On success the registry returns HTTP 200 with ParticipantCreateResponse containing only participant_code, described as the machine-generated unique identifier of the participant on the HCX instance; sandbox codes look like 100001@sbx and production codes like XXXXX7583@hcx.
  - `participant_code` (string)

Example 200 response. The values are placeholders:

```json
{
  "participant_code": "100001@sbx"
}
```


---

# Validate participant update

`GET /update/validate`

Production call. Confirms a participant update by presenting the SMS passcode and the transactionId returned by /v2/participant/update.

### Business purpose

Changing a participant's encryption certificate or callback endpoint changes where encrypted claims data is delivered and who can decrypt it, so the registry does not apply such updates on an API call alone. /v2/participant/update stages the change and sends a passcode to the registered mobile number; this call confirms it. It is step 4 of the production onboarding sequence and the same approval mechanism protects every later certificate or bridge rotation done through the v2 update.

### When to use

Call it in production after `/v2/participant/update` returns a `transactionid` and the passcode arrives by SMS, within 24 hours. It makes the new certificate and callback URL live. The production address is `https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice/update/validate`.

### Preconditions

- The participant was created and confirmed through `/validate`.
- You have the `transactionid` from the update call and its SMS passcode.
- You have a valid access token.

### Postconditions

The new certificate and callback URL become live. Other participants now fetch the new certificate.

### Common mistakes

- Assuming the update is live before this call succeeds.
- Using a passcode from an earlier update attempt.
- Calling `/validate` instead. That one confirms creation.

### Best practices

- Rotate keys in two phases: keep the old private key available for decrypting inbound callbacks until the update is validated and cached certificates (24-hour TTL on the payer side) have refreshed.
- Persist transactionid with its 24-hour expiry and record who completed validation, for audit.
- Never log the passcode; treat it as a one-time credential.
- After success, call /participant/search on your own code to confirm encryption_cert and endpoint_URL reflect the change.

### Related scenario

A year after go-live a payer's security team rotates the encryption key pair. The integrator generates a new self-signed X.509 certificate, Base64-encodes it and calls /v2/participant/update with participantcode and encryptioncert. The registry returns status and a new transactionid and sends a passcode to the registered mobile. Within the hour the team calls GET /update/validate with both values; on 200 the new certificate is live. Providers that cached the old certificate pick up the new one at their next 24-hour refresh, and the payer keeps the old private key for one more day to decrypt in-flight callbacks.

### Specification

Chapter [Your certificate](/docs/nhcx/v1/getting-started/your-certificate) of the NHCX integration specification.

```bash
curl --request GET \
  --url "https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice/update/validate?transactionId=<TRANSACTIONID>&passcode=<PASSCODE>" \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Query parameters

- `transactionId` (string, required)
- `passcode` (string, required)

## Responses

- `200`: HTTP 200 with a bare string body (operation particiapntUpdateValidate, response type string).
  - `_contentType` (string)
  - `_body` (string)

Example 200 response. The values are placeholders:

```json
{
  "_contentType": "string",
  "_body": "<confirmation string as declared by the OpenAPI 200 response>"
}
```


---

# Submit the participant create (v2)

`POST /v2/participant/create`

Production call. Registry-linked creation: registry type and ID, role codes, endpoint URL and contacts; returns participantid and a transactionid for /validate.

### Business purpose

Production onboarding needs to prove that the organisation registering on NHCX is the same one already known to an external authority (the ABDM Health Facility Registry for hospitals, the IRDAI registry for insurers and TPAs). The v2 create therefore takes a thin, registry-linked payload rather than a full profile, validates the mobile number against the number held in HFR or the NHCX payer details, and sends a one-time passcode to that number. This is step 1 of the four-step production sequence and is what turns a verified facility into an addressable NHCX participant.

### When to use

Use it for production onboarding, after sandbox certification. The production address is `https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice/v2/participant/create`. Follow it with `GET /validate` within 24 hours, using the returned `transactionid` and the SMS passcode. In the sandbox, use `/participant/create` instead.

### Preconditions

- You have a valid access token.
- `registrytype` and `role` use the codes from the valid enum lists.
- The registry ID is right, with leading zeros removed from an IRDAI ID.
- The mobile number matches the one held in HFR or the NHCX payer details.

### Postconditions

The registry returns `participantid` and a `transactionid`, and sends a passcode by SMS. You are not registered until `/validate` succeeds.

### Common mistakes

- Mixing up role codes and registry type codes, which share numbers.
- Using a mobile number that does not match the one on record.
- Losing the `transactionid`, or letting 24 hours pass before `/validate`.
- Sending the v1 body, or expecting `participant_code` back.

### Best practices

- Persist transactionid immediately, together with the timestamp, so the /validate step can be completed by whoever holds the registered phone.
- Verify the mobile number and registry ID against HFR or IRDAI records before calling; the check is strict and every failed attempt is a manual round trip.
- Treat the error object in a 200 response as meaningful and surface it to the operator rather than assuming success from the HTTP status alone.
- Do not retry blindly: each call generates a new transaction ID and passcode and invalidates the plan to confirm the previous one.
- Keep sandbox and production credentials, hosts and participant codes strictly separate.

### Related scenario

An insurer's TPA has cleared sandbox certification and received production credentials. Its integrator obtains a Bearer token, then calls /v2/participant/create with registrytype 10004, the IRDAI-issued registry ID (leading zeros stripped), role ["10003"], the production callback base URL and the mobile number the NHA has on file. The response returns participantid, the facility details and transactionid 1vouv8tlz2tnl-1fpspjhwj07c6, and an SMS passcode reaches the compliance officer's phone. Within the hour the team calls GET /validate with both values to confirm creation, then proceeds to /v2/participant/update to publish its encryption certificate.

### Specification

Chapter [Your certificate](/docs/nhcx/v1/getting-started/your-certificate) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice/v2/participant/create \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "registrytype": "10001",
  "registryid": "XXXXX74586",
  "role": [
    "10001"
  ],
  "endpointurl": "https://nhcx.demohospital.example.in",
  "mobilenumber": "XXXX748348",
  "email": "sample@gmail.com"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `registrytype` (string)
- `registryid` (string)
- `role` (string[])
- `endpointurl` (string)
- `mobilenumber` (string)
- `email` (string)

## Responses

- `200`: HTTP 200 with ParticipantCreateV2Resp: participantid, facilityname, facilitycontact and facilityemail echoed from the linked registry, a transactionid such as 1vouv8tlz2tnl-1fpspjhwj07c6, and an error object (code, message, trace).
  - `participantid` (string)
  - `facilityname` (string)
  - `facilitycontact` (string)
  - `facilityemail` (string)
  - `transactionid` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)
  - `error.trace` (string)

Example 200 response. The values are placeholders:

```json
{
  "participantid": "XXXXX7583@hcx",
  "facilityname": "Demo Multispeciality Hospital",
  "facilitycontact": "XXXX748348",
  "facilityemail": "sample@gmail.com",
  "transactionid": "1vouv8tlz2tnl-1fpspjhwj07c6",
  "error": {
    "code": "",
    "message": "",
    "trace": ""
  }
}
```


---

# Submit the HEM-entity participant create

`POST /v2/participant/hementity/create`

Creates a hospital (HEM-entity) participant from the full empanelment payload (bank, tax, beds, specialities, doctors); returns status and hospitalid.

### Business purpose

Government scheme empanelment needs far more than a name and a certificate: a hospital must be identified by scheme, state and district, carry bank details for settlement, tax identifiers for deduction handling, and descriptive data such as hospital type, bed strength, accreditation, specialities and doctors. This endpoint captures that full hospital-empanelment profile in one registry call so the payer side can settle and audit against it. It exists alongside the thinner v2 create because scheme onboarding (for example PMJAY) involves configuration that regular private-insurance onboarding does not.

### When to use

Use it for scheme hospital onboarding, such as PMJAY, when the operator asks for this form. It is not a drop-in swap for `/v2/participant/create`.

### Preconditions

- You have a valid access token.
- The body has every required field, including the bank details.
- If you send tax details, include the PAN, TAN and GST numbers together.
- You have a Base64-encoded certificate and a callback URL that uses a domain name.

### Postconditions

The registry returns `status` and `hospitalid`. It does not return a participant code, so keep the `participantcode` you sent.

### Common mistakes

- Expecting a participant code back and not saving `hospitalid`.
- Leaving out required fields inside the bank details.
- Guessing field names. Copy them exactly from the schema.
- Sending the certificate without Base64 encoding.

### Best practices

- Build the payload from the schema field by field and validate nested objects (BankDetails, HospitalDoctorDetails, IncentiveRequest) before sending; a 400 does not point at the offending nested field.
- Collect bank, tax, MICR and IFSC values from the finance team in advance; they are mandatory and settlement depends on them.
- Keep the private key that pairs with encryption_cert in PKCS8 form on the callback host only.
- Never log the full request; it contains bank account and tax identifiers.
- Confirm with the onboarding operator whether a passcode approval step applies, since the response has no transactionid to pair with /validate.

### Related scenario

A district hospital being empanelled under a state scheme is asked to register as an HEM entity. The hospital's IT partner obtains a Bearer token and assembles the full payload: scheme_code, state and district, bed strength, hospital type, speciality list, doctor roster, bank details for settlement and PAN, TAN and GST numbers, plus the Base64 certificate and callback URL. They call /v2/participant/hementity/create and receive status and hospitalid. The record is then available to the scheme payer via /participant/search, and the hospital moves on to fetching the payer's certificate with /fetch/certs before sending its first pre-authorisation.

### Specification

Chapter [Your certificate](/docs/nhcx/v1/getting-started/your-certificate) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/v2/participant/hementity/create \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "participant_name": "District Hospital Demo",
  "participantcode": "XXXXX7583@hcx",
  "scheme_code": "PMJAY",
  "state": "Karnataka",
  "district": "Mysuru",
  "entityid": "IN2910001234",
  "hospitaltype": "Public",
  "incentiveCode": "NABH",
  "hospitalbedstrength": "200",
  "lab_yn": "Y",
  "roles": [
    "provider"
  ],
  "specialityList": [
    "General Medicine",
    "General Surgery"
  ],
  "primaryEmail": "claims@districthospital.example.in",
  "primaryMobile": "9800000000",
  "encryption_cert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...",
  "endpoint_url": "https://nhcx.districthospital.example.in",
  "bankdetails": {
    "facilitybankaccountname": "District Hospital Demo",
    "authorizedsignatoryname": "Medical Superintendent",
    "bankaccountnumber": "000000000000",
    "ifsccode": "SBIN0000000",
    "bankname": "State Bank of India",
    "bankbranchname": "Mysuru Main",
    "bankaddress": "Mysuru, Karnataka",
    "micrcode": "570002000",
    "accounttype": "Current"
  },
  "taxdetails": {
    "pannumber": "AAAAA0000A",
    "tannumber": "BLRA00000A",
    "gstnumber": "29AAAAA0000A1Z5"
  }
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `participant_name` (string)
- `participantcode` (string)
- `scheme_code` (string)
- `state` (string)
- `district` (string)
- `entityid` (string)
- `hospitaltype` (string)
- `incentiveCode` (string)
- `hospitalbedstrength` (string)
- `lab_yn` (string)
- `roles` (string[])
- `specialityList` (string[])
- `primaryEmail` (string)
- `primaryMobile` (string)
- `encryption_cert` (string)
- `endpoint_url` (string)
- `bankdetails` (object)
- `bankdetails.facilitybankaccountname` (string)
- `bankdetails.authorizedsignatoryname` (string)
- `bankdetails.bankaccountnumber` (string)
- `bankdetails.ifsccode` (string)
- `bankdetails.bankname` (string)
- `bankdetails.bankbranchname` (string)
- `bankdetails.bankaddress` (string)
- `bankdetails.micrcode` (string)
- `bankdetails.accounttype` (string)
- `taxdetails` (object)
- `taxdetails.pannumber` (string)
- `taxdetails.tannumber` (string)
- `taxdetails.gstnumber` (string)

## Responses

- `200`: HTTP 200 with ParticipantCreateResponseV2 containing status and hospitalid.
  - `status` (string)
  - `hospitalid` (string)

Example 200 response. The values are placeholders:

```json
{
  "status": "Created",
  "hospitalid": "H00012345"
}
```


---

# Validate participant creation

`GET /validate`

Production call. Confirms a participant creation by presenting the SMS passcode and the transactionId returned by /v2/participant/create.

### Business purpose

Registering an organisation on a national claims exchange must be authorised by someone who actually controls that organisation's registered contact channel. The create call therefore only stages the record and sends a passcode to the mobile number held in HFR or the NHCX payer details; this validation call closes the loop by proving possession of that passcode. It is step 2 of the four-step production onboarding sequence and is what turns a staged participant into a confirmed one.

### When to use

Call it in production after `/v2/participant/create` returns a `transactionid` and the passcode arrives by SMS. Do it within 24 hours, and before any `/v2/participant/update`. The production address is `https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice/validate`.

### Preconditions

- You have the `transactionid` from the create call.
- You have the SMS passcode for that same transaction.
- You have a valid access token.

### Postconditions

The participant is confirmed in the registry. You can now upload the certificate and callback URL with `/v2/participant/update`.

### Common mistakes

- Waiting more than 24 hours, so both values expire.
- Calling create again while a passcode is pending, which replaces the earlier pair.
- Calling `/update/validate` instead. That one confirms updates.

### Best practices

- Treat the passcode like a one-time credential: never log it, and hand it from the phone holder to the integrator through a controlled channel.
- Store transactionid with a 24-hour expiry so the operator dashboard can show whether confirmation is still possible.
- Send parameters as query string values on a GET; there is no JSON body.
- After success, proceed straight to /v2/participant/update so the certificate and endpoint are in place before any counterparty tries to fetch them.

### Related scenario

A hospital's production onboarding started with /v2/participant/create, which returned transactionid 1vouv8tlz2tnl-1fpspjhwj07c6 and triggered a passcode to the medical superintendent's registered phone. The superintendent reads the passcode to the integration engineer, who calls GET /validate?transactionId=1vouv8tlz2tnl-1fpspjhwj07c6&passcode=482913 with the Bearer token. The registry returns 200 and the participant is confirmed. The engineer then calls /v2/participant/update with the Base64 certificate and callback URL, and completes that change with /update/validate.

### Specification

Chapter [Your certificate](/docs/nhcx/v1/getting-started/your-certificate) of the NHCX integration specification.

```bash
curl --request GET \
  --url "https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice/validate?transactionId=<TRANSACTIONID>&passcode=<PASSCODE>" \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Query parameters

- `transactionId` (string, required)
- `passcode` (string, required)

## Responses

- `200`: HTTP 200 with a bare string body; the OpenAPI declares the 200 response type as string and the operation (particiapntValidate) as validating approval from the participant for participant creation.
  - `_contentType` (string)
  - `_body` (string)

Example 200 response. The values are placeholders:

```json
{
  "_contentType": "string",
  "_body": "<confirmation string as declared by the OpenAPI 200 response>"
}
```


---

# Onboarding

Nothing moves through NHCX until both the sender and the recipient exist in the participant registry, which the platform treats as the source of truth for who may exchange claims data.

## APIs

Onboarding differs between the two environments. The sandbox registers a participant in one call. Production registers it in steps, each confirmed with a passcode sent to the registered mobile number.

### Sandbox

Base URL: `https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice`. Credentials: the client ID and secret you received when you registered on the ABDM sandbox.

| Call                                                                                            | Called by         | Method and path            | What it does                                                                                                          |
| ----------------------------------------------------------------------------------------------- | ----------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| [Participant create (v1)](/docs/nhcx/v1/api/onboarding/endpoints/onboarding-participant-create) | Provider or payer | `POST /participant/create` | Creates a participant record in the NHCX registry from a full v1 profile and returns the generated participant\_code. |

To change the record later in the sandbox, use [Submit the participant update (v1)](/docs/nhcx/v1/api/registry/endpoints/registry-participant-update) in the participant registry.

### Production

Base URL: `https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice`. Credentials: the production credentials issued after sandbox certification. The rows run in the order the steps happen.

| Call                                                                                                                             | Called by         | Method and path               | What it does                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| [Participant create (v2)](/docs/nhcx/v1/api/onboarding/endpoints/onboarding-v2-participant-create)                               | Provider or payer | `POST /v2/participant/create` | Registry-linked creation: registry type and ID, role codes, endpoint URL and contacts; returns participantid and a transactionid for /validate. |
| [Validate participant creation](/docs/nhcx/v1/api/onboarding/endpoints/onboarding-validate)                                      | Provider or payer | `GET /validate`               | Confirms a participant creation by presenting the SMS passcode and the transactionId returned by /v2/participant/create.                        |
| [Submit the participant certificate and bridge update (v2)](/docs/nhcx/v1/api/registry/endpoints/registry-v2-participant-update) | Provider or payer | `POST /v2/participant/update` | Stages the certificate and callback URL; the call sits in the participant registry.                                                             |
| [Validate participant update](/docs/nhcx/v1/api/onboarding/endpoints/onboarding-update-validate)                                 | Provider or payer | `GET /update/validate`        | Confirms a participant update by presenting the SMS passcode and the transactionId returned by /v2/participant/update.                          |

### Scheme hospital onboarding

No environment limit is published for this call. Use it when the scheme operator, for example PMJAY, asks for this form.

| Call                                                                                                               | Called by             | Method and path                         | What it does                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------ | --------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [HEM-entity participant create](/docs/nhcx/v1/api/onboarding/endpoints/onboarding-v2-participant-hementity-create) | Provider (a hospital) | `POST /v2/participant/hementity/create` | Creates a hospital (HEM-entity) participant from the full empanelment payload (bank, tax, beds, specialities, doctors); returns status and hospitalid. |

## Base URLs

| Environment                   | Base URL                                                        |
| ----------------------------- | --------------------------------------------------------------- |
| Sandbox, Participant service. | `https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice` |
| Production.                   | `https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice`   |

## Guides that use these calls

- [Creating and updating a participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant)
- [Your callback URL is rejected or never called](/docs/nhcx/v1/troubleshooting/your-callback-url-is-rejected)

The whole specification, with a request you can send from the page, is the [Onboarding API reference](/reference/nhcx-onboarding).


---

# Support: delete records by correlation ID

`POST /v1/delete`

Internal troubleshooting operation on the claim service that deletes records by correlationid and action; not part of the business transaction flows.

### Business purpose

`/v1/delete` is a troubleshooting operation on the claim service. It deletes the record identified by a correlation ID and an action, to clear a stuck or erroneous record during integration testing and support. It does not move a claim through its lifecycle.

### When to use

Only for troubleshooting, and only when NHCX support asks you to. It is not part of any claim flow.

### Preconditions

- You have a valid access token.
- You know the correlation ID and the action of the record to remove.
- NHCX support agrees that deleting it is the right fix.

### Postconditions

The record is removed. To carry on, start a new request with a new correlation ID.

### Common mistakes

- Using it to cancel a pre-authorisation. Cancel with a `Task` on `/v1/task/submit`, workflow `PC01`.
- Reusing the old correlation ID after a delete.
- Calling it in production without NHCX support.

### Best practices

- Reserve this call for sandbox troubleshooting and only on NHCX support's instruction.
- Record the correlation ID, action and reason for every deletion in your own audit log, since the docs describe no NHCX-side confirmation beyond the HTTP status.
- Prefer /v1/status to inspect a stuck correlation ID before deleting anything.
- Mint a new correlation UUID for any re-submission after a deletion.

### Related scenario

During sandbox testing a hospital's integrator submits a claim whose callback keeps failing because their endpoint returned 200 instead of 202. NHCX support asks them to fix the acknowledgement and then clears the stuck record by correlation ID and action using /v1/delete so the test case can be rerun cleanly. The integrator resubmits the claim to /v1/claim/submit under a new correlation UUID, receives a 202, and this time the on_submit callback is acknowledged correctly.

### Specification

No chapter of the current documentation covers this operation. It appears only in the claim service's OpenAPI.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/delete \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "correlationid": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "action": "/v1/claim/submit"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Body

- `correlationid` (string)
- `action` (string)

## Responses

- `200`: The endpoint sits in the claim service, whose domain operations all return 202 Accepted, 400 Request Validation failed, 404 Requested resource was not found and 500 Downstream systems down, each carrying StatusSuccessResponse.
  - `httpStatus` (integer)
  - `schema` (string)
  - `note` (string)

Example 200 response. The values are placeholders:

```json
{
  "httpStatus": 202,
  "schema": "StatusSuccessResponse",
  "note": "The claim service spec lists 202, 400, 404 and 500, all carrying StatusSuccessResponse; no worked response body is published for /v1/delete."
}
```


---

# NHCX: report a request it could not deliver

`POST /v1/error`

Where the exchange tells a sender that a request could not be delivered after five attempts. Received by every participant under its registered address. There is no outbound form.

### Business purpose

When the exchange cannot deliver a request, it tries five times, retires the correlation ID and tells the original sender here. A system without this endpoint never learns that its request died, and a dead request looks exactly like a case still under review. Every participant must host it.

### When to use

You host this path and never call it. Providers and payers both need it, so build it first.

### Preconditions

- Your callback URL is registered: a domain name over HTTPS, hosted in India, answering within 30 seconds.
- Your handler accepts a body it does not know. The report is plain JSON, not encrypted.

### Postconditions

Answer `202`. The original request is dead, so a retry needs a new correlation ID.

### Common mistakes

- Not hosting it, so failed deliveries go unseen.
- Rejecting the report because it does not match a fixed schema.
- Retrying the failed request on the old correlation ID.

### Best practices

- Store the report whole before doing anything with it.
- Mark the case it names as undelivered, so the desk does not wait for a decision that will not come.
- Check it first when a case goes quiet, before asking the exchange with `/v1/status`.

### Related scenario

A hospital posts a pre-authorisation and gets its receipt, but the payer's endpoint is down. The exchange tries five times, retires the correlation ID and posts a report to the hospital's `/v1/error`. The handler stores the report whole, answers 202 with the receipt, and marks the pre-authorisation undelivered. The desk resubmits it with a fresh correlation ID once the payer is reachable.

### Specification

Chapter [Building and sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/error \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "ProtocolResponse",
  "x-hcx-sender_code": "nhcx-gateway@hcx",
  "x-hcx-recipient_code": "<provider participant code>",
  "x-hcx-api_call_id": "<uuid>",
  "x-hcx-correlation_id": "<correlation id>",
  "x-hcx-workflow_id": "12",
  "x-hcx-timestamp": "<iso timestamp>",
  "x-hcx-status": "response.error",
  "x-hcx-error_details": {
    "code": "ERR_DELIVERY_FAILED",
    "message": "Recipient endpoint unreachable after five attempts",
    "trace": ""
  },
  "x-hcx-entity-type": "preauth"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.

## Body

- `type` (string)
- `x-hcx-sender_code` (string)
- `x-hcx-recipient_code` (string)
- `x-hcx-api_call_id` (string)
- `x-hcx-correlation_id` (string)
- `x-hcx-workflow_id` (string)
- `x-hcx-timestamp` (string)
- `x-hcx-status` (string)
- `x-hcx-error_details` (object)
- `x-hcx-error_details.code` (string)
- `x-hcx-error_details.message` (string)
- `x-hcx-error_details.trace` (string)
- `x-hcx-entity-type` (string)

## Responses

- `200`: Answer 202 with the receipt, like every other delivery, filling in whatever identifiers the report carries and leaving the rest empty.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 200 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "preauth",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Patient app: acknowledge a notification subscription

`POST /v1/notification/on_subscribe`

BSP-side subscription acknowledgement; the same name denotes the callback where NHCX pushes claim-event notifications for a subscribed ABHA ID.

### Business purpose

Two things share this name. The API reference defines an NHCX-side operation (operationId onSubscribe) that takes a NotificationOnSubscribePayload with the beneficiary's abhaid, optional domain_values and plain header values, and returns a SubscribeResponse; it is described as the BSP-side subscription persistence acknowledgement. The integration guide uses the same path on the BSP's own host as the callback where NHCX delivers notifications. Together they complete the beneficiary-facing loop: the patient's app learns, in plain language, that a preauth was approved, a claim adjudicated, a payment made or information requested. The caller is a Beneficiary Service Provider; the persona label is the nearest available.

### When to use

A beneficiary app hosts this path to receive notifications for the ABHA IDs it subscribed. NHCX calls it when a pre-authorisation, claim, payment or query event happens.

### Preconditions

- An active subscription exists for the ABHA ID, made through `/v1/notification/subscribe`.
- Your callback runs over HTTPS with TLS 1.2 or higher, at the registered `on_notification_URL`.
- You check the token NHCX sends and its sender code.

### Postconditions

Each notification carries a `message` you can show the user as it is. Nothing changes in the exchange between hospital and payer.

### Common mistakes

- Building the user message from `domain_values`, which may be missing, instead of showing `message`.
- Reading the status from `x-hcx-workflow_ID`. It lives in `x-hcx-status`.
- Assuming the subscription is still yours after it shows `replaced`.
- Accepting calls without checking the token or the sender code.

### Best practices

- Display message verbatim; keep domain_values for audit logging or advanced formatting only.
- Validate the JWT and sender_code on every inbound push, enforce TLS 1.2 or higher and rate limiting.
- Map event types (preauth_response, claim_response, payment_notice, communication) to in-app timelines using x-hcx-action and x-hcx-status.
- Show subscription status in settings so a replaced subscription is visible to the user; resubscribe on next login.
- Keep the endpoint fast and idempotent on notification_ID.

### Related scenario

A PHR app has subscribed ravi@ABDM to workflow_events. A hospital submits a claim on /v1/claim/submit for that beneficiary and the payer adjudicates it on /v1/claim/on_submit. NHCX forks the outcome to the app's registered on_subscribe callback with topic_code workflow_events, a message stating the claim was approved with the amount, and domain_values including x-hcx-action claim_response and x-hcx-status response.complete. The app validates the JWT and sender_code, shows the message on the patient's timeline, and when the payer later sends a payment notice on /v1/paymentnotice/request the next push reads paid.

### Specification

Chapter [Notifications and patient apps](/docs/nhcx/v1/reference/notifications-and-patient-apps) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/notification/on_subscribe \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "request": {
    "abhaid": "ravi@abdm",
    "domain_values": {
      "x-hcx-workflow_id": "wf_20260825_001",
      "x-hcx-correlation_id": "corr_20260825_12345",
      "x-hcx-timestamp": "2026-08-25T14:30:00+05:30",
      "x-hcx-sender_code": "payor.icici@nhcx",
      "x-hcx-recipient_code": "bsp.phrapp@nhcx",
      "x-hcx-status": "response.complete",
      "x-hcx-action": "preauth_response",
      "x-hcx-amount_submitted": "75000.00"
    }
  },
  "hvalues": {
    "senderid": "payor.icici@nhcx",
    "receiverid": "bsp.phrapp@nhcx",
    "correlationid": "corr_20260825_12345",
    "status": "response.complete",
    "workflowid": "wf_20260825_001"
  }
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Body

- `request` (object)
- `request.abhaid` (string)
- `request.domain_values` (object)
- `request.domain_values.x-hcx-workflow_id` (string)
- `request.domain_values.x-hcx-correlation_id` (string)
- `request.domain_values.x-hcx-timestamp` (string)
- `request.domain_values.x-hcx-sender_code` (string)
- `request.domain_values.x-hcx-recipient_code` (string)
- `request.domain_values.x-hcx-status` (string)
- `request.domain_values.x-hcx-action` (string)
- `request.domain_values.x-hcx-amount_submitted` (string)
- `hvalues` (object)
- `hvalues.senderid` (string)
- `hvalues.receiverid` (string)
- `hvalues.correlationid` (string)
- `hvalues.status` (string)
- `hvalues.workflowid` (string)

## Responses

- `200`: The NHCX-side operation returns HTTP 200 with a SubscribeResponse (timestamp, api_call_id, correlation_id, subscription_id, subscription_status active, replaced or expired, expiry, message); 400, 401, 403, 409 and 500 return a StatusSuccessResponse with the same descriptions as the subscribe table.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `subscription_id` (string)
  - `subscription_status` (string)
  - `expiry` (string)
  - `message` (string)

Example 200 response. The values are placeholders:

```json
{
  "timestamp": "2026-08-25T14:30:01+05:30",
  "api_call_id": "e7f8a9b0-c1d2-3456-0123-567890123456",
  "correlation_id": "corr_20260825_12345",
  "subscription_id": "sub_ravi_001",
  "subscription_status": "active",
  "expiry": "",
  "message": "Preauthorization approved for Rs. 50,000. Valid from 2026-08-25 to 2026-09-01. Reference: PA-2026-004567"
}
```


---

# Patient app: subscribe an ABHA number to notifications

`POST /v1/notification/subscribe`

A Beneficiary Service Provider (PHR app) subscribes an ABHA ID to notification topics; NHCX persists it synchronously, Last-Linked-Wins per ABHA ID.

### Business purpose

Every other flow is a two-party exchange between hospital and payer. Notifications let a third party, the beneficiary through a PHR app, watch a claim move without being a sender or recipient on the underlying preauth or claim. The caller is a Beneficiary Service Provider (BSP), not a hospital or insurer; the persona label here is the nearest available. The subscription is what routes human-readable messages such as a preauth approval with amount and validity to the patient's app, giving beneficiaries transparency and reducing calls to the hospital desk.

### When to use

Call it every time a beneficiary logs in to your app. The last app to subscribe an ABHA ID wins, so do not trust a stored subscription.

### Preconditions

- You have a valid access token, sent in the `Authorization` header.
- Your callback URL is registered over HTTPS, with TLS 1.2 or higher.
- The user has agreed to receive notifications.
- The body is encrypted and carries a new `x-hcx-correlation_ID`.

### Postconditions

NHCX saves the subscription and answers `200` with a `subscription_ID` and its status. From then on, claim events for that ABHA ID are pushed to your callback.

### Common mistakes

- Reusing a correlation ID on a retry, which returns `409`.
- Subscribing once and assuming it still holds after another app logs in.
- Sending it to the exchange host instead of `https://hcxsbx.abdm.gov.in/v1/notification/subscribe`.
- Sending the token on `bearer_auth` instead of `Authorization`.

### Best practices

- Subscribe on every login and refresh the token before its 20-minute (1200-second) expiry; store access_token encrypted and never log the secret.
- Generate a fresh UUID correlation ID per subscribe attempt, including retries; retry 500s with backoff, regenerate the token on 401, check the registry on 403.
- Subscribe only to the topics you need, typically workflow_events.
- Secure the callback: HTTPS with TLS 1.2 or higher, validate the JWT from NHCX, verify sender_code, rate-limit.
- Display the message field directly to users; treat domain_values as optional audit data and read status from x-hcx-status, not the workflow ID description.

### Related scenario

A beneficiary opens a PHR app and logs in with the ABHA address ravi@ABDM. The app confirms its NHCX token is valid, then posts /v1/notification/subscribe with subscription_ID sub_ravi_001, topic_code workflow_events, its BSP code and its on_notification_URL, under a fresh correlation ID. NHCX replies 200 with subscription_status active. Later that day a hospital submits a preauth for the same ABHA ID on /v1/preauth/submit and the payer approves it on /v1/preauth/on_submit; NHCX pushes a notification to the app's callback reading that the preauthorisation was approved for Rs. 50,000 with its validity dates, which the app displays as-is.

### Specification

Chapter [Notifications and patient apps](/docs/nhcx/v1/reference/notifications-and-patient-apps) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://hcxsbx.abdm.gov.in/v1/notification/subscribe \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00iLCJ4LWhjeC1zZW5kZXJfY29kZSI6InBoci1hcHAteHl6QGJzcCJ9.encrypted_key.iv.ciphertext.tag",
  "_payload_plaintext": {
    "subscription_id": "sub_ravi_001",
    "topic_code": [
      "workflow_events"
    ],
    "recipient_code": "phr-app-xyz@bsp",
    "subscriber": {
      "id": "ravi@abdm"
    },
    "on_notification_url": "https://api.phrapp.com/v1/hcx/notification/on_subscribe"
  }
}'
```

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.

## Body

- `payload` (string)
- `_payload_plaintext` (object)
- `_payload_plaintext.subscription_id` (string)
- `_payload_plaintext.topic_code` (string[])
- `_payload_plaintext.recipient_code` (string)
- `_payload_plaintext.subscriber` (object)
- `_payload_plaintext.subscriber.id` (string)
- `_payload_plaintext.on_notification_url` (string)

## Responses

- `200`: NHCX decrypts the request with its private key, validates headers and payload, persists the subscription with Last-Linked-Wins per ABHA id and returns the subscription state synchronously: HTTP 200 with a SubscribeResponse carrying timestamp, api_call_id, correlation_id, subscription_id, subscription_status (active, replaced or expired), expiry and message.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `subscription_id` (string)
  - `subscription_status` (string)
  - `expiry` (string)
  - `message` (string)

Example 200 response. The values are placeholders:

```json
{
  "timestamp": "2026-08-25T08:30:00+05:30",
  "api_call_id": "d6e7f8a9-b0c1-2345-9012-456789012345",
  "correlation_id": "8899aabb-ccdd-eeff-0011-223344556677",
  "subscription_id": "sub_ravi_001",
  "subscription_status": "active",
  "expiry": "",
  "message": "Subscription accepted"
}
```


---

# Recipient: answer a status check

`POST /v1/on_status`

The answer to a status request, delivered to the sender that asked. The `x-hcx-status` in the protected header says where the message you asked about got to. The payload is an empty string.

### Business purpose

It separates "did my message arrive" from "what did the payer decide". A sender learns whether a quiet case is still held by the exchange, has reached the recipient, or is dead, without resubmitting it and creating a duplicate.

### When to use

Every participant that sends `/v1/status` hosts this path. It carries the answer to your status request.

### Preconditions

- You sent `/v1/status` and kept track of which request it asked about.
- Your callback URL is registered and answers `202` within 30 seconds.

### Postconditions

Read `x-hcx-status` in the header. `request.dispatched` means the message reached the recipient, and `request.queued` means NHCX still holds it. `request.stopped` means the request is dead, so a retry needs a new correlation ID. Answer `202`.

### Common mistakes

- Expecting a bundle. The payload is an empty string.
- Matching on the original request's correlation ID instead of your status request's.
- Retrying a stopped request on its old correlation ID.

### Best practices

- Keep every `API_call_ID` you send. Without it you cannot ask the question at all.
- Act on `request.stopped` at once, and treat `request.dispatched` as a reason to wait for the payer.
- Ask from a support screen when a case has gone quiet for longer than the payer's expected turnaround, not on a timer.

### Related scenario

A pre-authorisation has had no answer for longer than the payer's usual turnaround. The support screen sends `/v1/status` with that request's `API_call_ID` as the correlation ID. The answer arrives here with an empty payload and `x-hcx-status` `request.stopped`, so the desk knows the request is dead rather than slow, and resubmits it with a fresh correlation ID.

### Specification

Chapter [NHCX adapter (Optional)](/docs/nhcx/v1/getting-started/nhcx-adapter) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/on_status \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "<compact JWE>"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `200`: Read `x-hcx-status` from the protected header.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 200 response. The values are placeholders:

```json
{
  "timestamp": "19/03/2026 11:46:35:120",
  "api_call_id": "{{$guid}}",
  "correlation_id": "{{correlationId}}",
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Participant receives an error report

`POST /v1/error`

Hosted by every participant. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/error`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Where the exchange tells a sender that a request could not be delivered after five attempts. Received by every participant under its registered address. There is no outbound form.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/error \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "ProtocolResponse",
  "x-hcx-sender_code": "nhcx-gateway@hcx",
  "x-hcx-recipient_code": "<provider participant code>",
  "x-hcx-api_call_id": "<uuid>",
  "x-hcx-correlation_id": "<correlation id>",
  "x-hcx-workflow_id": "12",
  "x-hcx-timestamp": "<iso timestamp>",
  "x-hcx-status": "response.error",
  "x-hcx-error_details": {
    "code": "ERR_DELIVERY_FAILED",
    "message": "Recipient endpoint unreachable after five attempts",
    "trace": ""
  },
  "x-hcx-entity-type": "preauth"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.

## Body

- `type` (string)
- `x-hcx-sender_code` (string)
- `x-hcx-recipient_code` (string)
- `x-hcx-api_call_id` (string)
- `x-hcx-correlation_id` (string)
- `x-hcx-workflow_id` (string)
- `x-hcx-timestamp` (string)
- `x-hcx-status` (string)
- `x-hcx-error_details` (object)
- `x-hcx-error_details.code` (string)
- `x-hcx-error_details.message` (string)
- `x-hcx-error_details.trace` (string)
- `x-hcx-entity-type` (string)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "preauth",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Sender receives the status answer

`POST /v1/on_status`

Hosted by every participant that sends `/v1/status`. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/on_status`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

The answer to a status request, delivered to the sender that asked. The `x-hcx-status` in the protected header says where the message you asked about got to. The payload is an empty string.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/on_status \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "<compact JWE>"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "preauth",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Other errors

A Other code arrives sealed inside the callback, not in the response to your call. These are the codes the Catalogue records on this module's paths.

## Codes

| Code                                                                    | What it means                                                            |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [`NHCX-401`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-401)   | The exchange does not accept your authorisation for this call            |
| [`NHCX-1001`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1001) | The recipient's system is not reachable                                  |
| [`NHCX-1002`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1002) | The sender is not a registered participant                               |
| [`NHCX-1003`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1003) | The recipient is not a registered participant                            |
| [`NHCX-1004`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1004) | No recipient is registered for the scheme you asked for                  |
| [`NHCX-1005`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1005) | A request header is missing or not valid                                 |
| [`NHCX-1006`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1006) | The correlation id has already been used                                 |
| [`NHCX-1007`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1007) | The exchange could not process the request's structure or values         |
| [`NHCX-1008`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1008) | The exchange had a temporary failure                                     |
| [`NHCX-1009`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1009) | The exchange failed and recorded the cause in its own logs               |
| [`NHCX-1010`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1010) | No request matches the correlation id on your answer                     |
| [`NHCX-1011`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1011) | The x-hcx-status value is not valid                                      |
| [`NHCX-1012`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1012) | No message matches the api\_call\_id you gave                            |
| [`NHCX-1013`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1013) | The request body is empty or not valid                                   |
| [`NHCX-1014`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1014) | The exchange could not deliver the response to its sender                |
| [`NHCX-1016`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1016) | The call does not fit the exchange open on this correlation id           |
| [`NHCX-1017`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1017) | The recipient answered a delivery in a form the exchange does not accept |
| [`NHCX-1018`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1018) | The ABHA number is not in the XX-XXXX-XXXX-XXXX form                     |
| [`PAYR-1516`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1516) | The payer cannot match your error response to any message                |
| [`PAYR-1517`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1517) | Your error was sent encrypted instead of as a protocol response          |

Every code above is recorded in the Catalogue. The aggregated list across modules is at [error codes](/docs/nhcx/v1/reference/pmjay-error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# Other

Calls that belong to no single use case: notification subscription, deletion, the status callback and the protocol error report.

Reprocess, cancellation and shortfall have their own group: [Reprocess, cancel and shortfall](/docs/nhcx/v1/api/task/).

## APIs

| Call                                                                                                                         | Called by                                        | Method and path                      | What it does                                                                                                                                          |
| ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Patient app: subscribe an ABHA number to notifications](/docs/nhcx/v1/api/other/endpoints/other-v1-notification-subscribe)  | Beneficiary app                                  | `POST /v1/notification/subscribe`    | A Beneficiary Service Provider (PHR app) subscribes an ABHA id to notification topics; NHCX persists it synchronously, Last-Linked-Wins per ABHA id.  |
| [Patient app: acknowledge a notification subscription](/docs/nhcx/v1/api/other/endpoints/other-v1-notification-on-subscribe) | NHCX, to the beneficiary app                     | `POST /v1/notification/on_subscribe` | BSP-side subscription acknowledgement; the same name denotes the callback where NHCX pushes claim-event notifications for a subscribed ABHA id.       |
| [Support: delete records by correlation ID](/docs/nhcx/v1/api/other/endpoints/other-v1-delete)                               | Any participant, when NHCX support asks          | `POST /v1/delete`                    | Internal troubleshooting operation on the claim service that deletes records by correlationid and action; not part of the business transaction flows. |
| [Recipient: answer a status check](/docs/nhcx/v1/api/other/endpoints/other-v1-on-status)                                     | NHCX or the recipient, in answer to `/v1/status` | `POST /v1/on_status`                 | The answer to a status request, delivered to the sender that asked.                                                                                   |
| [NHCX: report a request it could not deliver](/docs/nhcx/v1/api/other/endpoints/other-v1-error)                              | NHCX, to the sender                              | `POST /v1/error`                     | Where the exchange tells a sender that a request could not be delivered after five attempts.                                                          |

## Callbacks you host

The exchange posts these to the `endpoint_url` you registered. Answer each with HTTP 202 first.

| Path            | Hosted by                                 |
| --------------- | ----------------------------------------- |
| `/v1/on_status` | Every participant that sends `/v1/status` |
| `/v1/error`     | Every participant                         |

## Base URLs

| Environment             | Base URL                          |
| ----------------------- | --------------------------------- |
| Sandbox, NHCX exchange. | `https://apisbx.abdm.gov.in/hcx`  |
| Production.             | `https://apisprod.nha.gov.in/hcx` |

## Guides that use these calls

- [Building and sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe)
- [Status and search](/docs/nhcx/v1/reference/fhir/status-and-search)
- [Notifications and patient apps](/docs/nhcx/v1/reference/notifications-and-patient-apps)
- [Accepted with 202, and no callback arrives](/docs/nhcx/v1/troubleshooting/accepted-then-no-callback)

The whole specification, with a request you can send from the page, is the [Other API reference](/reference/nhcx-other).


---

# Provider: acknowledge the payment notice

`POST /v1/paymentnotice/on_request`

Provider acknowledges a payment notice with a Task bundle (status completed, output paymentack), closing the payment lifecycle via NHCX.

### Business purpose

The acknowledgement confirms to the payer that the provider has received and recorded the payment notice for a specific claim. It closes the payment lifecycle from the provider side and completes the audit trail from claim approval through settlement. Failure to acknowledge does not block the payer, but the acknowledgement is required for complete lifecycle tracking, which matters for reconciliation, dispute resolution and scheme reporting.

### When to use

The provider calls it after receiving a payment notice, with the same correlation ID and `x-hcx-status` `response.complete`. It tells the payer the payment was received and recorded.

### Preconditions

- A payment notice with this correlation ID has been received and answered with `202`.
- The provider has a valid access token and the payer's certificate, and encrypts the reply for the payer.
- The `Task` is `completed` and carries `paymentack` and the claim number from the notice.
- The provider is now the sender and requester. The payer is the recipient and owner.

### Postconditions

- NHCX answers `202` and forwards the acknowledgement to the payer.
- On success the payment for that claim is closed on both sides.

### Common mistakes

- Using other text such as `ACKNOWLEDGED` instead of `paymentack`.
- Keeping the notice's direction, with the payer still as requester.
- Creating a new correlation ID instead of reusing the notice's.
- Skipping the acknowledgement, which leaves the payment open.

### Best practices

- Send the acknowledgement only after the UTR, TDS and net amount have been persisted against the claim.
- Echo the claim number from PaymentNotice.identifier (type CLN) into Task.output[1].valueString so the payer can match it without decrypting the original.
- Confirm with the payer during onboarding whether it expects the acknowledgement here or on /v1/task/submit, given the documented source conflict.
- Be idempotent: if the same notice is redelivered, acknowledge again with the same content rather than creating a second ledger entry.
- Log API_call_ID and correlation ID for the acknowledgement so the closed lifecycle can be evidenced.

### Related scenario

The hospital finance team receives the settlement notice under workflow 33 for claim CL0000000001 with UTR UTR000000000001, net 2187 INR and TDS 243 INR. After matching the bank credit and persisting the UTR, the HMIS builds a Task with status completed, code status, output paymentack and claimNumber CL0000000001, encrypts it for the payer and posts it to /v1/paymentnotice/on_request under workflow 17 with the notice's correlation ID. NHCX returns 202 and delivers it to the payer's bridge, which acknowledges within 30 seconds; the claim is now closed on both ledgers.

### Specification

Chapter [Payment notice and acknowledgement](/docs/nhcx/v1/reference/fhir/payment-notice-and-acknowledgement) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/paymentnotice/on_request \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.
- `x-hcx-debug_flag` (string): `Error`, `Info` or `Debug`. A server may ignore it. Optional on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: NHCX returns HTTP 202 Accepted with a StatusSuccessResponse acknowledgement (entity_type payment) and forwards the Task to the payer asynchronously; the payer's endpoint must acknowledge with 202 within 30 seconds or NHCX retries up to five times.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "27/02/2026 10:06:19:310",
  "api_call_id": "b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "correlation_id": "c3d2e1f0-a9b8-4c7d-9e6f-5a4b3c2d1e0f",
  "result": {
    "sender_code": "<provider participant code>",
    "recipient_code": "<payer participant code>",
    "entity_type": "payment",
    "protocol_status": "request.dispatched"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Payer: send a payment notice

`POST /v1/paymentnotice/request`

Payer pushes a Task bundle with PaymentNotice and PaymentReconciliation (amount, TDS, UTR) to the provider via NHCX after approving a claim.

### Business purpose

Every other flow exchanges decisions; the payment notice is the only one that tells the hospital whether the money actually moved. It formally notifies the provider that a payment has been initiated, processed or settled against an approved claim, carrying the net amount, TDS deduction, payment date and the UTR. Hospitals need it to reconcile bank receipts to claims and close the episode; payers need it as the structured, auditable record of settlement.

### When to use

The payer calls it after the final claim is approved, to tell the hospital about the payment. It can be sent up to three times, as the payment is initiated, processed and settled: the workflow code in the header says which.

### Preconditions

- The claim has been approved and the payment has started on the payer's side.
- The payer has a valid access token and the provider's certificate, and encrypts the notice for the provider.
- The notice carries the net amount, the tax deducted and the claim number.
- The payer holds valid bank details for the hospital.

### Postconditions

- NHCX answers `202` and forwards the notice to the provider, who must reply `202` within 30 seconds.
- The payment is closed only after the provider acknowledges on `/v1/paymentnotice/on_request`.

### Common mistakes

- Provider side: expecting a `Claim` or `ClaimResponse`. The notice is a `Task` bundle, with the amounts in `PaymentReconciliation`.
- Provider side: looking for the bank reference (UTR) before the settled notice.
- Provider side: replying with `200` or a bad body, which triggers retries.
- Payer side: sending the notice before the claim is approved.

### Best practices

- Payer: send 30, 31 and 33 as the transfer progresses and populate paymentIdentifier with the UTR at 33; keep TDS and Payment detail lines consistent with the gross claim amount.
- Provider: persist the UTR, TDS and net amount against the claim for audit and dispute resolution, and mark the claim SETTLED only on 33.
- Provider: acknowledge with 202 within 30 seconds, be idempotent on correlation ID, then send the paymentack Task.
- Both: note the source conflict on whether the acknowledgement goes to /v1/paymentnotice/on_request or /v1/task/submit; the API contract supports on_request, so confirm with the counterparty during onboarding.
- Both: use IST timestamps and echo the correlation ID through the acknowledgement.

### Related scenario

Three days after approving claim CL0000000001 for 2430 INR, the state health agency initiates a bank transfer of 2187 INR after 243 INR TDS. Its bridge builds a Task bundle with code deliver, a PaymentNotice with amount 2187 and status paid, and a PaymentReconciliation with the TDS and Payment detail lines, and posts it to /v1/paymentnotice/request under workflow 30. NHCX returns 202 and delivers it to the hospital, which acknowledges within 30 seconds. When the transfer settles the payer sends a second notice under 33 carrying the UTR; the hospital persists it and responds on /v1/paymentnotice/on_request with a paymentack Task.

### Specification

Chapter [Payment notice and acknowledgement](/docs/nhcx/v1/reference/fhir/payment-notice-and-acknowledgement) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/paymentnotice/request \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: NHCX returns HTTP 202 Accepted with a StatusSuccessResponse acknowledgement (entity_type payment) and forwards the bundle asynchronously to the provider's registered callback endpoint, which must acknowledge with 202 within 30 seconds.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "27/02/2026 15:36:09:004",
  "api_call_id": "c3d2e1f0-a9b8-4c7d-9e6f-5a4b3c2d1e0f",
  "correlation_id": "c3d2e1f0-a9b8-4c7d-9e6f-5a4b3c2d1e0f",
  "result": {
    "sender_code": "<payer participant code>",
    "recipient_code": "<provider participant code>",
    "entity_type": "payment",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Payer receives the payment acknowledgement

`POST /v1/paymentnotice/on_request`

Hosted by the payer. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/paymentnotice/on_request`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Provider acknowledges a payment notice with a Task bundle (status completed, output paymentack), closing the payment lifecycle via NHCX.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/paymentnotice/on_request \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.
- `x-hcx-debug_flag` (string): `Error`, `Info` or `Debug`. A server may ignore it. Optional on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "payment",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Provider receives a payment notice

`POST /v1/paymentnotice/request`

Hosted by the provider. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/paymentnotice/request`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Payer pushes a Task bundle with PaymentNotice and PaymentReconciliation (amount, TDS, UTR) to the provider via NHCX after approving a claim.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/paymentnotice/request \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "payment",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Payment notice errors

A Payment notice code arrives sealed inside the callback, not in the response to your call. These are the codes the Catalogue records on this module's paths.

## Codes

| Code                                                                    | What it means                                                                                       |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [`PAYR-1020`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1020) | The payer holds no valid bank details for your facility, or a supporting info category is not valid |

Every code above is recorded in the Catalogue. The aggregated list across modules is at [error codes](/docs/nhcx/v1/reference/pmjay-error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# Payment notice

Every other flow exchanges decisions; the payment notice is the only one that tells the hospital whether the money actually moved.

## APIs

| Call                                                                                                                              | Called by | Method and path                     | What it does                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| [Payer: send a payment notice](/docs/nhcx/v1/api/payment-notice/endpoints/payment-notice-v1-paymentnotice-request)                | Payer     | `POST /v1/paymentnotice/request`    | Payer pushes a Task bundle with PaymentNotice and PaymentReconciliation (amount, TDS, UTR) to the provider via NHCX after approving a claim. |
| [Provider: acknowledge the payment notice](/docs/nhcx/v1/api/payment-notice/endpoints/payment-notice-v1-paymentnotice-on-request) | Provider  | `POST /v1/paymentnotice/on_request` | Provider acknowledges a payment notice with a Task bundle (status completed, output paymentack), closing the payment lifecycle via NHCX.     |

## Callbacks you host

The exchange posts these to the `endpoint_url` you registered. Answer each with HTTP 202 first.

| Path                           | Hosted by    |
| ------------------------------ | ------------ |
| `/v1/paymentnotice/request`    | The provider |
| `/v1/paymentnotice/on_request` | The payer    |

## Base URLs

| Environment             | Base URL                          |
| ----------------------- | --------------------------------- |
| Sandbox, NHCX exchange. | `https://apisbx.abdm.gov.in/hcx`  |
| Production.             | `https://apisprod.nha.gov.in/hcx` |

## Guides that use these calls

- [Building and sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe)
- [Payment notice and acknowledgement](/docs/nhcx/v1/reference/fhir/payment-notice-and-acknowledgement)

The whole specification, with a request you can send from the page, is the [Payment notice API reference](/reference/nhcx-payment-notice).


---

# Payer: send the pre-authorisation response

`POST /v1/preauth/on_submit`

Payer returns the ClaimResponseBundle for a pre-authorisation (approved, partially approved, queried or rejected) to the provider via NHCX.

### Business purpose

This callback carries the payer's decision on a preauth. For the hospital it is the moment the money question is settled: an approval with a preAuthRef lets treatment proceed under a binding commitment, a partial approval tells the desk the amount was capped and why, a query says what evidence is missing, and a rejection closes the request. For the payer it is the channel through which adjudication results, package-rate caps and query text reach the provider in a structured, auditable form.

### When to use

The payer calls it after deciding on a pre-authorisation, with the same correlation ID. It carries an approval, a partial approval, a query or a rejection: the workflow code in the header says which.

### Preconditions

- A pre-authorisation with this correlation ID exists in NHCX.
- The payer has a valid access token and the provider's certificate, and encrypts the decision for the provider.
- The correlation ID matches the request, the call ID is new, and sender and recipient are swapped.
- An approval carries the `preAuthRef`, and any cut in the amount is explained.

### Postconditions

- NHCX answers `202` and forwards the decision to the provider, who must reply `202` within 30 seconds.
- On approval the provider stores the `preAuthRef` and may treat. A query keeps the request open. A rejection closes it.

### Common mistakes

- Provider side: deciding on `outcome` alone. The adjudication reason says whether it was approved or rejected.
- Provider side: replying with `200` or a bare body, which triggers retries.
- Payer side: creating a new correlation ID instead of reusing the request's.

### Best practices

- Provider: acknowledge first, adjudicate later; queue the decrypt and state change and be idempotent on correlation ID.
- Provider: branch on x-hcx-workflow_ID, ClaimResponse.outcome and adjudication[0].reason.coding.code together, and surface processNote text to the desk.
- Provider: persist preAuthRef and the payer identifier (identifier[0].value) against the case for the claim stage.
- Payer: fill disposition, adjudication categories (submitted, eligible, copay, benefit) and processNote so a partial approval is explainable.
- Payer: put protocol errors in x-hcx-error_details with catalogued codes and business errors inside the encrypted ClaimResponse.
- Provider: expose the callback on a domain name on an India-based server and whitelist the NHCX NAT IPs.

### Related scenario

The insurer's adjudication engine reviews a corneal grafting preauth submitted for 25000 INR and caps it at the package rate of 13700 INR. Its bridge builds a ClaimResponseBundle with outcome partial, preAuthRef PREAUTH-HP-2026-78902 and a processNote explaining the cap, sets x-hcx-workflow_ID 21 and x-hcx-status response.complete with the request's correlation ID, encrypts it for the hospital and posts to /v1/preauth/on_submit. NHCX acknowledges with 202 and delivers it to the hospital, whose callback acknowledges inside 30 seconds and shows the desk the reduced amount and reason. Treatment proceeds, and after discharge the hospital submits the final claim on /v1/claim/submit referencing that preAuthRef.

### Specification

Chapter [Preauthorisation response](/docs/nhcx/v1/reference/fhir/preauthorisation-response) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/preauth/on_submit \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.
- `x-hcx-debug_flag` (string): `Error`, `Info` or `Debug`. A server may ignore it. Optional on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: HTTP 202 Accepted with the StatusSuccessResponse acknowledgement (entity_type preauth) from NHCX, then asynchronous delivery to the provider's registered /v1/preauth/on_submit.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "19/03/2026 11:46:35:120",
  "api_call_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "correlation_id": "11223344-5566-7788-99aa-bbccddeeff00",
  "result": {
    "sender_code": "<payer participant code>",
    "recipient_code": "<provider participant code>",
    "entity_type": "preauth",
    "protocol_status": "request.dispatched"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Provider: submit a pre-authorisation

`POST /v1/preauth/submit`

Provider submits, resubmits, enhances or answers a query on a pre-authorisation Claim bundle (Claim.use preauthorization); NHCX routes it to the payer.

### Business purpose

Pre-authorisation is the provider's formal request for the payer's approval to deliver a specific treatment to a covered beneficiary. An approved preAuthRef is the payer's binding commitment to reimburse the approved amount and is required before the final claim can proceed through NHCX. Settling the money question before the patient enters theatre protects the hospital from unpaid treatment, gives the payer control over admissibility, and gives the patient certainty about cashless cover.

### When to use

Use it to ask the payer to approve a treatment before it starts. The same call also sends a resubmission, an enhancement or an answer to a payer query: the workflow code in the header says which.

### Preconditions

- You have a valid access token and the payer's certificate.
- Coverage is confirmed and the documents the payer asks for are ready.
- The bundle is an FHIR `Claim` with `use` set to `preauthorization`, encrypted for the payer.

### Postconditions

- NHCX answers `202` at once. That only means the message was accepted, not approved.
- The payer's decision arrives later on `/v1/preauth/on_submit`.

### Common mistakes

- Sending to the insurer's code instead of the claims processor's.
- Treating the `202` as an approval.
- Reusing a correlation ID after a failed request.

### Best practices

- Build one ClaimBundle and switch Claim.use between preauthorization and claim; keep careTeamSequence, diagnosisSequence, procedureSequence and informationSequence internally consistent.
- Always send both x-hcx-workflow_ID and x-hcx-use_case, and persist them with the correlation ID and the case number.
- Attach every document the auth-requirements response listed (MAND codes) before submitting; the document list is per package, not static.
- Raise enhancements while the patient is admitted, not retrospectively at discharge (PAYR-1018 time limit expired).
- Persist preAuthRef from an approved or partially approved response; it is required at final claim.
- Implement v1/error and /v1/status so a preauth that never reached the payer is visible at the desk.

### Related scenario

After the eligibility callback confirms cover for corneal grafting (SE012A) and lists the required documents, the hospital builds a Claim bundle with use preauthorization, ICD-10 H18.6, a total of 13700 INR and the investigation and consent attachments, and posts it to /v1/preauth/submit under workflow 12 with use_case New. NHCX returns 202. The payer queries under 24 asking for detailed ICPs; the hospital answers on the same endpoint under 19 with the same correlation ID. Approval arrives under 21 with preAuthRef PREAUTH-HP-2026-78901. Two days later the surgeon needs a higher bed category, so the hospital posts an enhancement under 13 with use_case Enhancement, and after discharge it moves to /v1/claim/submit.

### Specification

Chapter [Preauthorisation request](/docs/nhcx/v1/reference/fhir/preauthorisation-request) of the NHCX integration specification.

### Also sent as pre-authorisation enhancement

The same address, with other headers and body.

Provider asks for more against an approved pre-authorisation, a longer stay or an added package, on the same endpoint and case number as the first request, under workflow 13 with x-hcx-use_case Enhancement.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/preauth/submit \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.
- `x-hcx-use_case` (string): Values differ by exchange. [Domain headers](/docs/nhcx/v1/reference/envelope-fields#domain-headers) lists them. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: NHCX returns HTTP 202 Accepted with a StatusSuccessResponse acknowledgement (entity_type preauth, protocol_status request.queued or request.dispatched).
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "19/03/2026 11:46:35:120",
  "api_call_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "correlation_id": "11223344-5566-7788-99aa-bbccddeeff00",
  "result": {
    "sender_code": "<provider participant code>",
    "recipient_code": "<payer participant code>",
    "entity_type": "preauth",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Provider receives the pre-authorisation response

`POST /v1/preauth/on_submit`

Hosted by the provider. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/preauth/on_submit`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Payer returns the ClaimResponseBundle for a pre-authorisation (approved, partially approved, queried or rejected) to the provider via NHCX.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/preauth/on_submit \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.
- `x-hcx-debug_flag` (string): `Error`, `Info` or `Debug`. A server may ignore it. Optional on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "preauth",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Payer receives a pre-authorisation

`POST /v1/preauth/submit`

Hosted by the payer. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/preauth/submit`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Provider submits, resubmits, enhances or answers a query on a pre-authorisation Claim bundle (Claim.use preauthorization); NHCX routes it to the payer.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/preauth/submit \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.
- `x-hcx-use_case` (string): Values differ by exchange. [Domain headers](/docs/nhcx/v1/reference/envelope-fields#domain-headers) lists them. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "preauth",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Pre-authorisation errors

A Pre-authorisation code arrives sealed inside the callback, not in the response to your call. These are the codes the Catalogue records on this module's paths.

## Codes

| Code                                                                    | What it means                                                                                                        |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [`PAYR-1001`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1001) | The recipient could not decrypt your request                                                                         |
| [`PAYR-1002`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1002) | The payer could not encrypt its answer to you                                                                        |
| [`PAYR-1003`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1003) | The payer's system could not reach the exchange and will resend, or the workflow requested is not valid              |
| [`PAYR-1004`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1004) | Your facility is not registered with the payer for the policy, or the FHIR bundle is malformed                       |
| [`PAYR-1005`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1005) | The beneficiary is not a covered member of the policy, or the request is more than 24 hours old                      |
| [`PAYR-1006`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1006) | The policy does not exist, or a name in the request is not valid                                                     |
| [`PAYR-1007`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1007) | The policy has expired, or the gender in the request is not valid                                                    |
| [`PAYR-1008`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1008) | The beneficiary's remaining cover is not enough for the request, or the FHIR bundle is not valid or cannot be parsed |
| [`PAYR-1009`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1009) | The requested items are not valid or not covered, or the Patient resource has no identifier                          |
| [`PAYR-1010`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1010) | A preauthorisation was required but not obtained, or the Patient identifier has no type                              |
| [`PAYR-1011`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1011) | The approved package does not support enhancement, or the Claim resource has no identifier                           |
| [`PAYR-1013`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1013) | The procedures or packages have no prior approval, or the provider Organization resource has no identifier           |
| [`PAYR-1014`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1014) | The date of birth is after the date of service, or the provider Organization identifier has no type                  |
| [`PAYR-1017`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1017) | The amount calculations are not correct, or the Task resource has no task code                                       |
| [`PAYR-1018`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1018) | The time limit for submission has expired, or the Task resource has no reason code                                   |
| [`PAYR-1019`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1019) | The additional information the payer asked for did not arrive in time, or a supporting info sequence is not valid    |
| [`PAYR-1021`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1021) | A supporting info entry has an invalid code                                                                          |
| [`PAYR-1023`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1023) | A procedure has an invalid category                                                                                  |
| [`PAYR-1024`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1024) | A procedure has an invalid status                                                                                    |
| [`PAYR-1025`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1025) | A procedure has an invalid sequence                                                                                  |
| [`PAYR-1026`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1026) | The claim references a procedure that is not in the bundle                                                           |
| [`PAYR-1027`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1027) | A claim item has an invalid id                                                                                       |
| [`PAYR-1028`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1028) | A claim item has an invalid sequence                                                                                 |
| [`PAYR-1029`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1029) | The bundle id is invalid                                                                                             |
| [`PAYR-1030`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1030) | A questionnaire id in the bundle is invalid                                                                          |
| [`PAYR-1031`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1031) | A bundle entry has an invalid URL                                                                                    |
| [`PAYR-1034`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1034) | A procedure code is invalid                                                                                          |
| [`PAYR-1035`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1035) | The policy code is invalid                                                                                           |
| [`PAYR-1036`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1036) | A supporting info entry lacks a valid attachment                                                                     |
| [`PAYR-1040`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1040) | A reference points at a resource that is not in the bundle                                                           |
| [`PAYR-1041`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1041) | A procedure has no identifier                                                                                        |
| [`PAYR-1042`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1042) | A procedure identifier has no type                                                                                   |
| [`PAYR-1043`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1043) | A date is in the wrong format                                                                                        |
| [`PAYR-1044`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1044) | A date and time is in the wrong format                                                                               |
| [`PAYR-1045`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1045) | A claim item has an invalid quantity                                                                                 |
| [`PAYR-1046`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1046) | A supporting info entry has no value or date                                                                         |
| [`PAYR-1047`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1047) | A supporting info entry has an invalid reference                                                                     |
| [`PAYR-1048`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1048) | A supporting info entry references a resource that is not in the bundle                                              |
| [`PAYR-1049`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1049) | The payer cannot accept the bundle                                                                                   |
| [`PAYR-1050`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1050) | A practitioner identifier has no type                                                                                |
| [`PAYR-1051`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1051) | A clinical record has no section                                                                                     |
| [`PAYR-1052`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1052) | A clinical record section has no references                                                                          |
| [`PAYR-1053`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1053) | A nested clinical record section has an invalid reference                                                            |
| [`PAYR-1054`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1054) | A clinical record section is empty                                                                                   |
| [`PAYR-1055`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1055) | A clinical record has no subject or its subject is not a patient                                                     |
| [`PAYR-1056`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1056) | The patient's contact organization is not an Organization                                                            |
| [`PAYR-1057`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1057) | The patient's general practitioner has the wrong type                                                                |
| [`PAYR-1058`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1058) | The patient's managing organization is not an Organization                                                           |
| [`PAYR-1059`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1059) | A clinical record points at something other than an encounter                                                        |
| [`PAYR-1060`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1060) | A clinical record has no encounter or its encounter has no subject                                                   |
| [`PAYR-1061`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1061) | An encounter's subject has the wrong resource type                                                                   |
| [`PAYR-1062`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1062) | An encounter has no episode of care the payer can find                                                               |
| [`PAYR-1063`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1063) | An encounter's episode of care has the wrong resource type                                                           |
| [`PAYR-1064`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1064) | An encounter has no based-on reference the payer can find                                                            |
| [`PAYR-1065`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1065) | An encounter's based-on reference has the wrong resource type                                                        |
| [`PAYR-1066`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1066) | An encounter has no appointment the payer can find                                                                   |
| [`PAYR-1067`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1067) | An encounter's appointment has the wrong resource type                                                               |
| [`PAYR-1068`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1068) | An encounter has no reason reference the payer can find                                                              |
| [`PAYR-1069`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1069) | An encounter's reason reference has the wrong resource type                                                          |
| [`PAYR-1070`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1070) | A composition has no author                                                                                          |
| [`PAYR-1071`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1071) | A composition's author has the wrong resource type                                                                   |
| [`PAYR-1072`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1072) | A claim procedure has no procedure reference                                                                         |
| [`PAYR-1073`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1073) | An observation has no based-on reference                                                                             |
| [`PAYR-1074`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1074) | An observation's based-on reference has the wrong resource type                                                      |
| [`PAYR-1075`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1075) | An observation has no part-of reference                                                                              |
| [`PAYR-1076`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1076) | An observation's part-of reference has the wrong resource type                                                       |
| [`PAYR-1077`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1077) | An observation has no subject                                                                                        |
| [`PAYR-1078`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1078) | An observation's subject is not a Patient                                                                            |
| [`PAYR-1079`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1079) | The claim has no care team                                                                                           |
| [`PAYR-1080`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1080) | A practitioner's HPR id is not valid                                                                                 |
| [`PAYR-1081`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1081) | An item's service date is not valid                                                                                  |
| [`PAYR-1082`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1082) | A composition linked from supporting info has an invalid title                                                       |
| [`PAYR-1083`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1083) | A practitioner has no HPR id                                                                                         |
| [`PAYR-1084`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1084) | A reference points at a questionnaire response that is not in the bundle                                             |
| [`PAYR-1085`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1085) | A questionnaire response reference points at the wrong resource type                                                 |
| [`PAYR-1086`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1086) | A reference points at a procedure that is not in the bundle                                                          |
| [`PAYR-1087`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1087) | A procedure reference points at the wrong resource type                                                              |
| [`PAYR-1088`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1088) | A composition failed the payer's checks                                                                              |
| [`PAYR-1089`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1089) | The claim has no billing items                                                                                       |
| [`PAYR-1090`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1090) | The coverage has no identifier                                                                                       |
| [`PAYR-1091`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1091) | The coverage identifier has no type                                                                                  |
| [`PAYR-1092`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1092) | The payer failed while processing your request                                                                       |
| [`PAYR-1093`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1093) | An encounter linked from a composition has no subject                                                                |
| [`PAYR-1094`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1094) | An encounter's subject has the wrong resource type                                                                   |
| [`PAYR-1097`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1097) | The request arrived with no encrypted payload                                                                        |
| [`PAYR-1098`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1098) | The registration date has the wrong value type                                                                       |
| [`PAYR-1101`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1101) | The eligibility purpose is not valid                                                                                 |
| [`PAYR-1102`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1102) | The id you searched with is not valid                                                                                |
| [`PAYR-1103`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1103) | The care plan id is not valid                                                                                        |
| [`PAYR-1104`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1104) | More than one beneficiary record matches                                                                             |
| [`PAYR-1201`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1201) | Claimed amount is zero or above the wallet balance                                                                   |
| [`PAYR-1202`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1202) | Speciality code is not in the insurance plan                                                                         |
| [`PAYR-1203`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1203) | Speciality description does not match the insurance plan                                                             |
| [`PAYR-1204`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1204) | Procedure code is not in the insurance plan                                                                          |
| [`PAYR-1205`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1205) | Procedure description does not match the insurance plan                                                              |
| [`PAYR-1206`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1206) | Procedure type is not accepted                                                                                       |
| [`PAYR-1207`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1207) | Procedure factor is not accepted                                                                                     |
| [`PAYR-1208`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1208) | Item quantity is not accepted                                                                                        |
| [`PAYR-1209`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1209) | Item net amount is zero or less                                                                                      |
| [`PAYR-1210`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1210) | Procedure status is not accepted                                                                                     |
| [`PAYR-1211`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1211) | Beneficiary and care plan match no rule at this hospital                                                             |
| [`PAYR-1212`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1212) | Enhancement has no approved preauthorisation                                                                         |
| [`PAYR-1213`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1213) | Enhancement sent while the case is still in progress                                                                 |
| [`PAYR-1214`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1214) | Resubmission has no approved preauthorisation                                                                        |
| [`PAYR-1215`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1215) | Resubmission sent while the case is still in progress                                                                |
| [`PAYR-1216`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1216) | New preauthorisation sent for a case already in progress                                                             |
| [`PAYR-1217`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1217) | New preauthorisation sent for a case already approved                                                                |
| [`PAYR-1218`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1218) | Query response sent for a case that was not queried                                                                  |
| [`PAYR-1219`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1219) | Case is not in the queried state                                                                                     |
| [`PAYR-1220`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1220) | Investigation description does not match its code                                                                    |
| [`PAYR-1221`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1221) | Investigation code is not valid                                                                                      |
| [`PAYR-1222`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1222) | Investigation status is not accepted                                                                                 |
| [`PAYR-1223`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1223) | Investigation attachment is not valid                                                                                |
| [`PAYR-1224`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1224) | Implant description does not match its code                                                                          |
| [`PAYR-1225`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1225) | Implant code is not valid                                                                                            |
| [`PAYR-1226`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1226) | Implant status is not accepted                                                                                       |
| [`PAYR-1227`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1227) | Implant attachment is not valid                                                                                      |
| [`PAYR-1228`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1228) | Implant quantity is not accepted                                                                                     |
| [`PAYR-1229`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1229) | Implant net amount is not accepted                                                                                   |
| [`PAYR-1230`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1230) | Implant unit price is not accepted                                                                                   |
| [`PAYR-1231`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1231) | Claim already raised for this case                                                                                   |
| [`PAYR-1232`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1232) | Investigations missing for a private hospital                                                                        |
| [`PAYR-1233`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1233) | Wallet short and patient liability not allowed                                                                       |
| [`PAYR-1234`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1234) | No preauthorisation found for the case number                                                                        |
| [`PAYR-1235`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1235) | Wallet balance is insufficient                                                                                       |
| [`PAYR-1236`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1236) | Claim type is not in-patient or out-patient                                                                          |
| [`PAYR-1237`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1237) | Beneficiary has an active preauthorisation at another hospital                                                       |
| [`PAYR-1238`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1238) | Beneficiary has an active preauthorisation at your hospital                                                          |
| [`PAYR-1239`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1239) | Hospital configuration not found                                                                                     |
| [`PAYR-1240`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1240) | Requested procedures not found                                                                                       |
| [`PAYR-1241`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1241) | Registration date is not valid                                                                                       |
| [`PAYR-1242`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1242) | Registration date format is not valid                                                                                |
| [`PAYR-1243`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1243) | Admission date is not valid                                                                                          |
| [`PAYR-1244`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1244) | Admission date format is not valid                                                                                   |
| [`PAYR-1245`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1245) | A scheme rule failed                                                                                                 |
| [`PAYR-1246`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1246) | Payer id is not valid                                                                                                |
| [`PAYR-1247`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1247) | Payer details not received from the exchange                                                                         |
| [`PAYR-1248`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1248) | Item code is not valid                                                                                               |
| [`PAYR-1249`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1249) | Item sequence is not valid                                                                                           |
| [`PAYR-1250`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1250) | Policy is not listed                                                                                                 |
| [`PAYR-1251`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1251) | No billable treatment plan                                                                                           |
| [`PAYR-1252`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1252) | Case is not in a state that can be cancelled                                                                         |
| [`PAYR-1253`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1253) | Case is already cancelled                                                                                            |
| [`PAYR-1254`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1254) | Treatment guideline questionnaire response missing                                                                   |
| [`PAYR-1255`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1255) | Case number already cancelled                                                                                        |
| [`PAYR-1256`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1256) | No biometric authentication and no consent questionnaire                                                             |
| [`PAYR-1257`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1257) | Payment already initiated for the case                                                                               |
| [`PAYR-1258`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1258) | Payment already cleared for the case                                                                                 |
| [`PAYR-1259`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1259) | Newborn date of birth missing                                                                                        |
| [`PAYR-1260`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1260) | Newborn date of birth is in the future                                                                               |
| [`PAYR-1261`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1261) | Newborn details are not valid                                                                                        |
| [`PAYR-1262`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1262) | Newborn gender missing                                                                                               |
| [`PAYR-1263`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1263) | Newborn documents missing                                                                                            |
| [`PAYR-1264`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1264) | Newborn documents missing                                                                                            |
| [`PAYR-1265`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1265) | Newborn documents missing                                                                                            |
| [`PAYR-1266`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1266) | Newborn documents missing                                                                                            |
| [`PAYR-1267`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1267) | Active newborn preauthorisation at your hospital                                                                     |
| [`PAYR-1268`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1268) | Active newborn preauthorisation at another hospital                                                                  |
| [`PAYR-1269`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1269) | Newborn is older than 6 years                                                                                        |
| [`PAYR-1270`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1270) | Item LM100 sent on a preauthorisation                                                                                |
| [`PAYR-1271`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1271) | Consent questionnaire answer missing                                                                                 |
| [`PAYR-1272`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1272) | Biometric user token is not valid                                                                                    |
| [`PAYR-1273`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1273) | Questionnaire not found for the selection                                                                            |
| [`PAYR-1501`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1501) | The surgery date entry carries the wrong kind of value                                                               |
| [`PAYR-1502`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1502) | The admission date entry carries the wrong kind of value                                                             |
| [`PAYR-1504`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1504) | The case remarks in your query response are not text                                                                 |
| [`PAYR-1505`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1505) | A questionnaire response is attached under the wrong category or code                                                |
| [`PAYR-1506`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1506) | The newborn's gender is not valid                                                                                    |
| [`PAYR-1507`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1507) | The newborn's date of birth is not valid                                                                             |
| [`PAYR-1508`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1508) | The newborn link does not lead to a Patient resource                                                                 |
| [`PAYR-1509`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1509) | The newborn's proof of birth attachment is not valid                                                                 |
| [`PAYR-1512`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1512) | A patient reference does not lead to a Patient resource                                                              |
| [`PAYR-1513`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1513) | A diagnosis is not sent as a coded concept                                                                           |
| [`PAYR-1515`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1515) | An organisation in your bundle has no name                                                                           |

Every code above is recorded in the Catalogue. The aggregated list across modules is at [error codes](/docs/nhcx/v1/reference/pmjay-error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# Pre-authorisation

Pre-authorisation is the provider's formal request for the payer's approval to deliver a specific treatment to a covered beneficiary.

## APIs

| Call                                                                                                           | Called by | Method and path              | What it does                                                                                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Provider: submit a pre-authorisation](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-submit)          | Provider  | `POST /v1/preauth/submit`    | Provider submits, resubmits, enhances or answers a query on a pre-authorisation Claim bundle (Claim.use preauthorization); NHCX routes it to the payer. Also sent as pre-authorisation enhancement. |
| [Payer: send the pre-authorisation response](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-on-submit) | Payer     | `POST /v1/preauth/on_submit` | Payer returns the ClaimResponseBundle for a pre-authorisation (approved, partially approved, queried or rejected) to the provider via NHCX.                                                         |

## Callbacks you host

The exchange posts these to the `endpoint_url` you registered. Answer each with HTTP 202 first.

| Path                    | Hosted by    |
| ----------------------- | ------------ |
| `/v1/preauth/submit`    | The payer    |
| `/v1/preauth/on_submit` | The provider |

## Base URLs

| Environment             | Base URL                          |
| ----------------------- | --------------------------------- |
| Sandbox, NHCX exchange. | `https://apisbx.abdm.gov.in/hcx`  |
| Production.             | `https://apisprod.nha.gov.in/hcx` |

## Guides that use these calls

- [Building and sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe)
- [Preauthorisation request](/docs/nhcx/v1/reference/fhir/preauthorisation-request)
- [Preauthorisation response](/docs/nhcx/v1/reference/fhir/preauthorisation-response)
- [Preauthorisation enhancement](/docs/nhcx/v1/reference/fhir/preauthorisation-enhancement)
- [Preauthorisation query and answer](/docs/nhcx/v1/reference/fhir/preauthorisation-query-and-answer)
- [Resubmission and cancellation of a pre-authorisation](/docs/nhcx/v1/roles/provider/preauthorisation#follow-ups-on-the-same-case): resubmission on workflow `121`, cancellation on `PC01`, answered on `PC02`
- [Cancelling a pre-authorisation with a Task](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall#cancel)
- [Reprocess, cancel and shortfall calls](/docs/nhcx/v1/api/task/): a cancellation is sent on `/v1/task/submit`, not on `/v1/preauth/submit`

The whole specification, with a request you can send from the page, is the [Pre-authorisation API reference](/reference/nhcx-preauth).


---

# Fetch certificate path

`POST /fetch/certs/path`

Companion to /fetch/certs: takes the same participantid body and returns a string described as the participant's certificate path.

### Business purpose

The registry stores a participant's encryption certificate as a URI or file path in the encryption_cert field, and this endpoint exposes that reference for a given participant. It exists alongside /fetch/certs, which the Integration Handbook names as the call to use when obtaining key material for encryption. Both serve the same underlying need, resolving a counterparty's public key before building a JWE, but the OpenAPI documents them identically and does not describe how their returned strings differ.

### When to use

Use it only if your NHCX instance tells you to. For encryption, use `/fetch/certs`.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- You send the target's code as `participantid`.

### Postconditions

You get a string back. What it contains beyond a certificate path is not documented.

### Common mistakes

- Treating the answer as the certificate that `/fetch/certs` returns.
- Using this instead of `/fetch/certs` without instructions from your instance.

### Best practices

- Prefer /fetch/certs for obtaining key material; use this endpoint only where the instance documents a use for the path form.
- If you do use it, log the returned string shape once so a change in behaviour is noticed.
- Apply the same 24-hour cache discipline keyed by participantid.
- Keep both calls behind one client function so the choice is a configuration switch.

### Related scenario

An integrator building a registry inspection tool for a TPA wants to show, for each payer, where the registry references its certificate as well as the certificate itself. The tool obtains a Bearer token, calls /fetch/certs/path with the payer's participant code and displays the returned path string, then calls /fetch/certs for the PEM used for actual encryption. The production claims engine itself only uses /fetch/certs, as the Integration Handbook prescribes, before each /v1/claim/submit.

### Specification

Chapter [Finding participants and policies](/docs/nhcx/v1/getting-started/finding-participants-and-policies) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/fetch/certs/path \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "participantid": "<payer participant code>"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `participantid` (string)

## Responses

- `200`: HTTP 200 with a string body.
  - `_contentType` (string)
  - `_body` (string)

Example 200 response. The values are placeholders:

```json
{
  "_contentType": "string",
  "_body": "<certificate path string as declared by the OpenAPI 200 response>"
}
```


---

# Fetch certificate

`POST /fetch/certs`

Returns a participant's public encryption certificate (PEM X.509 or SPKI key) by participantid; cache it for 24 hours and use it to build the JWE.

### Business purpose

Every NHCX payload is encrypted end-to-end for exactly one recipient so that even the exchange cannot read the clinical and financial content it routes. That guarantee rests on each participant publishing a public certificate in the registry at onboarding. This call is how a sender obtains a counterparty's certificate before encrypting a request or a callback for it. It is item 3 of both sandbox-exit checklists and the endpoint the Integration Handbook names in its encryption steps.

### When to use

Call it before you encrypt the first message to a recipient, then cache the certificate for 24 hours. Fetch it again if encryption or decryption with that recipient fails.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- You send the recipient's code as `participantid`.
- The recipient has registered a certificate.

### Postconditions

You get the recipient's certificate or public key. Use it to encrypt messages to that recipient.

### Common mistakes

- Fetching the certificate before every request instead of caching it.
- Encrypting with your own certificate instead of the recipient's.
- Assuming the answer is always a full certificate. It may be a bare public key.
- Keeping a cached certificate after the recipient changed it.

### Best practices

- Cache per participantid with a 24-hour TTL, plus a negative path that evicts and re-fetches on encrypt or decrypt failures.
- Implement the import routine as X.509 first, SPKI fallback, treating the 400-byte size hint as diagnostic rather than a hard branch.
- Use the documented algorithm pair RSA-OAEP-256 and A256GCM.
- Re-fetch from the production registry at go-live; sandbox certificates do not carry over.
- Expect annual key rotation by counterparties; the 24-hour cache bounds exposure to a rotation you were not told about.

### Related scenario

A hospital is about to send its first pre-authorisation to a payer. The engine checks its certificate cache, finds no entry, and calls /fetch/certs with the payer's participant code and a Bearer token. The response is a PEM X.509 certificate, which is parsed and cached for 24 hours. The engine builds the JWE protected header with x-hcx-sender_code, x-hcx-recipient_code set to that code and the other x-hcx headers, encrypts the FHIR bundle with RSA-OAEP-256 and A256GCM using the fetched key, and POSTs to /v1/preauth/submit. Later that week the payer rotates its certificate; a PAYR-1001 on the next submission triggers eviction and a fresh fetch.

### Specification

Chapter [Finding participants and policies](/docs/nhcx/v1/getting-started/finding-participants-and-policies) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/fetch/certs \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "participantid": "<payer participant code>"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `participantid` (string)

## Responses

- `200`: HTTP 200 with a string body containing a PEM-encoded X.509 certificate or an SPKI public key, as uploaded by that participant.
  - `_contentType` (string)
  - `_body` (string)

Example 200 response. The values are placeholders:

```json
{
  "_contentType": "string",
  "_body": "-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIEbXq...\n-----END CERTIFICATE-----"
}
```


---

# Fetch participants list

`POST /fetch/participants/list`

Payer discovery: lists participants filtered by role, registration date window and optional entity type; the first step of the cashless workflow.

### Business purpose

A patient is not cashless merely by having insurance. The hospital must first discover which payer to deal with, and that payer's participantcode becomes the payerId used for NHCX routing and the x-hcx-recipient_code header. This endpoint is the discovery workhorse: it returns every participant of a given role registered within a date window, which is how a hospital builds its payer picker and how a payer sees the providers on the exchange. It is item 1 of the provider sandbox-exit checklist.

### When to use

Use it first, to find the payers you can send to. Refresh the list from time to time, not for every patient.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- You send a role and a date range, with dates in `dd/MM/yyyy` format.
- The date range covers when the participants you expect were registered.

### Postconditions

You get a list of participants with their codes and names. The shape of the list can vary, so read it defensively.

### Common mistakes

- Sending dates in any format other than `dd/MM/yyyy`.
- Using a date range so narrow that some payers are missing.
- Expecting to filter by name. Filter the list yourself.

### Best practices

- Fetch once with a wide window, cache the list, and filter by name and scheme type locally, as the handbook's internal payers endpoint does.
- Accept all three response shapes defensively.
- Follow selection with /participant/search or /participant/details to confirm status and roles, and /fetch/certs to obtain the certificate before encrypting.
- Remove any hard-coded reference to 1000003538@hcx at go-live; production counterparties are resolved from this call.
- Refresh the cached list on a schedule so newly registered payers appear.

### Related scenario

A hospital's admission desk opens the cashless screen for a patient holding a government scheme card. The integration has already called /fetch/participants/list with role PAYER, a window from 01/04/2021 to today and entitytype Gov, and cached the result. The desk types the scheme name, the client filters the cached list, and the operator selects the state health agency's participantcode. The engine then calls /participant/get/policies to link the patient's policy, /fetch/certs for the payer certificate, and submits /v1/insuranceplan/request followed by /v1/preauth/submit.

### Specification

Chapter [Creating and updating a participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/fetch/participants/list \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "role": "PAYER",
  "fromdate": "01/04/2021",
  "todate": "20/03/2026",
  "entitytype": "Gov"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `role` (string)
- `fromdate` (string)
- `todate` (string)
- `entitytype` (string)

## Responses

- `200`: HTTP 200 with ParticipantListResponse: a participantdetails array of ParticipantDetails with participantcode, participantname, address and state.
  - `participantdetails` (object[])
  - `participantdetails.participantcode` (string)
  - `participantdetails.participantname` (string)
  - `participantdetails.address` (string)
  - `participantdetails.state` (string)

Example 200 response. The values are placeholders:

```json
{
  "participantdetails": [
    {
      "participantcode": "1000003538@hcx",
      "participantname": "NHCX Dummy Payer",
      "address": "New Delhi",
      "state": "Delhi"
    },
    {
      "participantcode": "<payer participant code>",
      "participantname": "Demo Insurance Company",
      "address": "Bengaluru",
      "state": "Karnataka"
    }
  ]
}
```


---

# Get session token

`POST /get/session`

Exchanges the participant's client_ID and client_secret (OAuth 2.0 client credentials) for a Bearer access_token valid for 1200 seconds.

### Business purpose

Every NHCX API call, whether a registry lookup, a certificate fetch or a claim submission, is rejected unless it carries a valid Bearer token, so this is the first call any integration makes and the first thing to check when a working integration starts failing. It answers the question of who is calling the gateway. It is deliberately separate from payload confidentiality: a request can be perfectly encrypted and still fail with 401, and vice versa.

### When to use

Call it when your system starts and again before the cached token expires. There is no refresh token: you simply call it again. Confirm the current host with your onboarding contact.

### Preconditions

- You have the `client_ID` and `client_secret` issued at onboarding.
- The credentials match the environment: sandbox and production credentials are separate.
- The body is form-encoded with `grant_type=client_credentials`.
- You do not need an access token for this call.

### Postconditions

You get an access token that lasts 20 minutes. Send it on every later call; after it expires, calls return `401`.

### Common mistakes

- Not renewing the token, so calls start failing with `401` after 20 minutes.
- Sending JSON instead of a form-encoded body.
- Asking for a new token on every request instead of caching it.
- Using a sandbox token against production.

### Best practices

- Cache the token in memory keyed by environment and refresh proactively at roughly 80 to 90 percent of the 1200-second (20-minute) lifetime, that is after 16 to 18 minutes.
- Serialise refresh behind a lock so concurrent workers do not fire simultaneous token requests.
- On any 401, discard the cached token, mint a new one and replay the original request exactly once; if the second attempt also fails, stop and alert, since the credentials are wrong or revoked.
- Never log the access_token or client_secret; log the expiry timestamp instead.
- Store secrets so they can be rotated without a code deploy.
- The token is validated by ABDM, so a 401 on any NHCX call carries no hint that expiry is the cause; treat 401 as refresh-and-retry first.

### Related scenario

At 09:00 a hospital's claims engine starts and POSTs its client_ID and client_secret to /get/session, receiving an access_token with expires_in 1200. It caches the token and immediately calls /fetch/certs for the payer it will submit to. At 09:17 a background timer renews the token before the 20-minute mark, so the /v1/preauth/submit sent at 09:21 carries a fresh Bearer header. Later a worker receives a 401 after a network stall; it drops the cached token, calls /get/session once more, replays the request and succeeds. Had the second attempt also failed, the engine would have alerted operations rather than looping.

### Specification

Chapter [Base URLs](/docs/nhcx/v1/getting-started/base-urls) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/get/session \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "_contentType": "application/x-www-form-urlencoded",
  "client_id": "<ABDM_CLIENT_ID>",
  "client_secret": "<ABDM_CLIENT_SECRET>",
  "grant_type": "client_credentials"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Body

- `_contentType` (string)
- `client_id` (string)
- `client_secret` (string)
- `grant_type` (string)

## Responses

- `200`: HTTP 200 with { access_token, expires_in: 1200, token_type: Bearer }.
  - `access_token` (string)
  - `expires_in` (integer)
  - `token_type` (string)

Example 200 response. The values are placeholders:

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 1200,
  "token_type": "Bearer"
}
```


---

# Submit the de-link ABHA policies

`POST /participant/delink/abha/policy`

Removes specific products from a member's policy link for a payer, keyed on payerid, memberid and the products listed.

### Business purpose

Policies lapse, members leave a product, and insurance companies move between TPAs. This call is the only documented way to reverse a link written through /participant/link/abha/policy, which keeps the registry honest so that providers do not route claims against coverage that no longer exists. Because there is no in-place re-parenting operation, de-link followed by a fresh link is also the documented procedure when a payer changes its processing TPA. The insurer and TPA control their own data; providers get accurate policy lookups.

### When to use

Use it when a member's policy should no longer be found: the policy ends, the member leaves, or the insurer changes TPA. To correct an ABHA number, use `/update/abhanumber` instead.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- You are the payer or TPA that linked the policies.
- The body names the payer, the member and the policies to remove.

### Postconditions

The policies are no longer returned for that member. Providers that cached them keep seeing them until they force a refresh.

### Common mistakes

- Calling as a participant that did not create the link.
- Listing a policy that is not linked.
- Adding an ABHA number to the body. De-link does not use it.
- Expecting provider caches to update by themselves.

### Best practices

- De-link only the specific products that need removing; the policies array is the unit of work.
- When moving an insurer to a new TPA, follow the documented order: de-link the existing policies, then link them again with the new TPA's participant code as processingid.
- Generate a fresh UUID for requestid on every call and log it with the response.
- Confirm the result with /participant/get/policies afterwards, and remember that providers may need a forced refresh of their own policy cache.
- Refresh the Bearer token proactively and retry once on 401 before escalating.

### Related scenario

An insurance company ends its contract with one TPA and appoints another. Its integration first calls /participant/get/policies to enumerate the products linked for each affected member, then calls /participant/delink/abha/policy for each member with the insurer's participant code as payerid, the member ID and the products to remove. Once every de-link returns success, it calls /participant/link/abha/policy again with the new TPA's participant code as processingid. Hospitals that have cached these members' policies are told to refresh, so that their next coverage-eligibility check is addressed to the new TPA.

### Specification

Chapter [Creating and updating a participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/delink/abha/policy \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "requestid": "9a7c5e3d-1b2f-4c8a-b6d4-0e9f8a7b6c55",
  "payerid": "100234@sbx",
  "memberid": "MEM-2026-000123",
  "policies": [
    {
      "productid": "PRD-FLOATER-01",
      "productname": "Family Floater Gold"
    }
  ],
  "processingid": "100235@sbx"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `requestid` (string)
- `payerid` (string)
- `memberid` (string)
- `policies` (object[])
- `policies.productid` (string)
- `policies.productname` (string)
- `processingid` (string)

## Responses

- `200`: A successful call returns HTTP 200 with ParticipantDeLinkAbhaResponse and the listed products are no longer returned by /participant/get/policies for that payer and member.
  - `result` (string)

Example 200 response. The values are placeholders:

```json
{
  "result": "success"
}
```


---

# Submit the participant details (v2 search)

`POST /participant/details`

v2 variant of participant search: takes participant_code and returns the matching full registry records.

### Business purpose

This is the second of two endpoints that read a single participant by code. It exists as the v2 generation of the registry lookup (operationId participantV2SearchPost) and serves the same business need as /participant/search: confirming that a counterparty exists, is active, holds the expected role and publishes an encryption certificate and callback endpoint before any encrypted transaction is addressed to it.

### When to use

Use it wherever you would use `/participant/search`. It takes the same request and returns the same response.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- You have the target's `participant_code`.

### Postconditions

You get the participant's full registry record. Nothing changes.

### Common mistakes

- Expecting a richer answer than `/participant/search` gives.
- Sending the code under a field name other than `participant_code`.
- Reading `encryption_cert` as the certificate itself instead of calling `/fetch/certs`.
- Leaving out the `Accept` header.

### Best practices

- Wrap both lookup endpoints behind one client function so the path can be switched by configuration.
- Check status and roles before choosing a recipient code.
- Cache the record and refresh on routing or decryption errors rather than on every transaction.
- Do not log payment_details.

### Related scenario

A payer's inbound gateway receives a /v1/claim/submit whose protected header names x-hcx-sender_code 100001@sbx. Before decrypting and processing, its integration calls /participant/details with that participant_code to confirm the sender is a registered provider with status Active and to record participant_name for the adjudication file. The claim is then decrypted with the payer's private key and passed to the claims team, whose decision goes back on /v1/claim/on_submit.

### Specification

Chapter [Creating and updating a participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/details \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "participant_code": "100001@sbx"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `participant_code` (string)

## Responses

- `200`: HTTP 200 with ParticipantSearchResponse: timestamp and a participants array of full participant records (participant_code, linked_registry_codes, participant_name, scheme_code, roles, address, contact fields, status, signing_cert_path, encryption_cert, endpoint_url, payment_details).
  - `timestamp` (integer)
  - `participants` (object[])
  - `participants.participant_code` (string)
  - `participants.participant_name` (string)
  - `participants.linked_registry_codes` (string[])
  - `participants.roles` (string[])
  - `participants.status` (string[])
  - `participants.primaryEmail` (string)
  - `participants.primaryMobile` (string)
  - `participants.encryption_cert` (string)
  - `participants.endpoint_url` (string)

Example 200 response. The values are placeholders:

```json
{
  "timestamp": 1716204567358,
  "participants": [
    {
      "participant_code": "100001@sbx",
      "participant_name": "Demo Multispeciality Hospital",
      "linked_registry_codes": [
        "IN2910001234@hfr"
      ],
      "roles": [
        "provider"
      ],
      "status": [
        "Active"
      ],
      "primaryEmail": "claims@demohospital.example.in",
      "primaryMobile": "9800000000",
      "encryption_cert": "https://registry.example.in/certs/100001.pem",
      "endpoint_url": "https://nhcx.demohospital.example.in"
    }
  ]
}
```


---

# Get beneficiary policies

`POST /participant/get/policies`

Looks up the policies linked to a beneficiary by ABHA number, member ID or mobile number, returning the payer and product details needed for claims.

### Business purpose

This is the provider's window into the member layer that payers populate through the link API. A hospital cannot submit a coverage-eligibility check, preauthorisation or claim until it knows the payer participant code, member ID and product for the patient, and this call is where those values come from. The handbook lists policy discovery as step three of the fixed cashless sequence (payer search, payer selection, policy discovery, cache normalisation, effective payer resolution, InsurancePlan retrieval, optional eligibility, preauth). Payers and TPAs also use it to verify that their links were recorded.

### When to use

Call it after registering or admitting a patient, to find their policy and payer. It comes before eligibility and pre-authorisation.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- The payer or TPA has already linked the member.
- You search by ABHA number, member ID or mobile number. Send the ABHA number without hyphens.

### Postconditions

You get the member's linked policies. Cache them, and force a refresh when something changes on the payer side.

### Common mistakes

- Using the payer ID as `x-hcx-recipient_code`. Use the processing ID from this response.
- Sending the ABHA number with hyphens.
- Trying only one identifier. Try ABHA number, then member ID, then mobile number.
- Trusting an old cached result after the payer changed something.

### Best practices

- Normalise the ABHA number (strip separators) before the call and try identifiers in the documented priority order: ABHA, then MemberId from the latest admission, then mobile number.
- Cache successful lookups keyed by patient, but expose a forceRefresh path and use it as the first diagnostic step when a preauth is rejected for a coverage mismatch.
- Store payerId, memberId, productId, productName and policyNumber from the result; these feed x-hcx-recipient_code, the Coverage and Patient identifiers and the InsurancePlan lookup.
- If the lookup yields nothing, fall back to a coverage-eligibility check with purpose discovery to obtain the active policy code.
- Keep the token fresh; retry once on 401.

### Related scenario

A patient is admitted to a network hospital and the registration desk captures an ABHA number and a member ID. The HMIS has already called /fetch/participants/list to discover payers, and now calls /participant/get/policies with identifiertype AbhaNumber and the hyphen-free ABHA value. The response is normalised and cached against the patient, and the processingID becomes the receiver code. The desk then requests the plan through /v1/insuranceplan/request, optionally runs /v1/coverageeligibility/check, and submits the preauthorisation with /v1/preauth/submit; when the payer later queries a coverage detail, the desk forces a refresh of this lookup before responding.

### Specification

Chapter [Creating and updating a participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/get/policies \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "identifiertype": "AbhaNumber",
  "identifiervalue": "12345678910111"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `identifiertype` (string)
- `identifiervalue` (string)

## Responses

- `200`: The service answers synchronously with HTTP 200 and ParticipantListResponse: an optional participantdetails array whose entries carry optional participantcode, participantname, address and state.
  - `participantdetails` (object[])
  - `participantdetails.participantcode` (string)
  - `participantdetails.participantname` (string)
  - `participantdetails.address` (string)
  - `participantdetails.state` (string)

Example 200 response. The values are placeholders:

```json
{
  "participantdetails": [
    {
      "participantcode": "100234@sbx",
      "participantname": "Demo Health Insurance Co",
      "address": "Plot 12, Sector 5, Gurugram",
      "state": "Haryana"
    }
  ]
}
```


---

# Get product ID and name

`POST /participant/getProductIdName`

Retrieving API described as generating the product ID and product name; declared with a bare string request body and a participant-code response.

### Business purpose

The OpenAPI document describes this endpoint with the same sentence as /product/getowner, "This API is to generate the product ID and product Name", and it belongs to the payer product lifecycle alongside /product/link, /product/delink and /product/getowner. Its documented purpose is to resolve product identity information within the participant service. The specification is thin: the request body is declared as a bare string, the response is ParticipantCreateResponse (participant_code only), and the operationId participantCreatePost is reused from the participant-creation endpoints, so treat the operationId as non-unique.

### When to use

Use it only if your NHCX instance documents how. To find a product's payer, use `/product/getowner`. To find a member's products, use `/participant/get/policies`.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- The body is a plain string, not a JSON object. What it should hold is not documented.

### Postconditions

The documented response holds only a participant code. Check what your instance really returns before you depend on it.

### Common mistakes

- Sending a JSON object instead of a string.
- Expecting a product ID and name in the answer.
- Confusing it with `/product/getowner`.

### Best practices

- Confirm the request and response contract against your instance's live OpenAPI document before integrating.
- Prefer /product/getowner for owner resolution and /participant/get/policies for member products; use this call only where it is specifically required.
- Log both the raw request string and the full response body so the actual behaviour can be reconciled with the specification.
- Keep the Bearer token fresh and retry once on 401.

### Related scenario

A TPA's integration team is generating a client from the participant service OpenAPI document and notices that /participant/getProductIdName shares its operationId with participant creation and its description with /product/getowner. Rather than wire it into the admission flow, they exercise it once in the sandbox with a product key, record the participant_code returned, and decide to rely on /product/getowner and /participant/get/policies for production. The member journey therefore runs link, get policies, InsurancePlan request and preauthorisation without this call.

### Specification

Chapter [Participants and policies](/docs/nhcx/v1/registries) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/getProductIdName \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "_note": "The OpenAPI document declares the request body as a bare JSON string; shown here as the string value that would be posted.",
  "_body": "PRD-FLOATER-01"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `_note` (string)
- `_body` (string)

## Responses

- `200`: Returns HTTP 200 with ParticipantCreateResponse, whose only field, participant_code, is optional.
  - `participant_code` (string)
- `400`: Client error. The body is the participant service's ErrorResponse.
  - `timestamp` (string, required): When the response was sent, as a Unix timestamp in milliseconds.
  - `error` (object, required)
  - `error.code` (string): The error code, namespaced by the system that raised it.
  - `error.message` (string): A short description of the error.
  - `error.trace` (string): A longer description supporting the code.
- `404`: Resource not found. The body is the participant service's ErrorResponse.
  - `timestamp` (string, required): When the response was sent, as a Unix timestamp in milliseconds.
  - `error` (object, required)
  - `error.code` (string): The error code, namespaced by the system that raised it.
  - `error.message` (string): A short description of the error.
  - `error.trace` (string): A longer description supporting the code.
- `500`: Downstream systems down, or an unhandled exception. The body is the participant service's ErrorResponse.
  - `timestamp` (string, required): When the response was sent, as a Unix timestamp in milliseconds.
  - `error` (object, required)
  - `error.code` (string): The error code, namespaced by the system that raised it.
  - `error.message` (string): A short description of the error.
  - `error.trace` (string): A longer description supporting the code.

Example 200 response. The values are placeholders:

```json
{
  "participant_code": "100234@sbx"
}
```


---

# Link ABHA number to policies

`POST /participant/link/abha/policy`

Payer-side write that links a beneficiary's ABHA number and member ID to one or more products, so provider policy lookups can find them.

### Business purpose

NHCX does not hold a national policy database of its own. Payers push their beneficiary-to-product links into the participant registry with this call, and providers pull them back with /participant/get/policies. Without a link, a hospital's policy lookup returns nothing and the patient cannot be processed as cashless on NHCX, regardless of what the admission record says. The insurer benefits by making its members discoverable; the hospital benefits by getting the payerId, memberId and productId it needs for every downstream claim call.

### When to use

Use it when a policy is issued or renewed, or a member is added. Also use it to link again after a de-link, for example when an insurer moves to a new TPA.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- You are the payer or its TPA, using the credentials that participant was created with.
- The payer, and the TPA if there is one, are already registered.

### Postconditions

The member's policies are linked at once. Providers can now find them through the get-policies lookups.

### Common mistakes

- Using a token from different credentials than the payer or TPA was created with.
- Mixing up `payerid` and `processingid`. `payerid` is always the insurer.
- Re-linking to change TPA. De-link first, then link with the new TPA.
- Leaving out a required field.

### Best practices

- Generate a fresh UUID for requestid on every call and log it with the response so a duplicate submission can be traced.
- Keep the ABHA number in the form the member layer expects (the identifier table and get/policies documentation both specify ABHA without hyphens) and store it in that form.
- Make sure productid and productname exactly match the payer's product catalogue as registered through /product/link, because providers will later match on these values.
- Cache and proactively refresh the Bearer token; retry once on 401 with a new token, then stop and alert.
- After linking, verify the result with /participant/get/policies using the same identifier before telling the provider the member is ready.

### Related scenario

A private insurer onboards a new group policy for a corporate client and issues a family floater to a beneficiary who already holds an ABHA. Its policy administration system has previously registered the product through /product/link and now calls /participant/link/abha/policy with the beneficiary's ABHA number, member ID, the insurer's own participant code as payerid and the TPA's code as processingid. A week later the beneficiary is admitted to a network hospital; the hospital's desk calls /participant/get/policies with the ABHA number, receives the linked details and uses the processingid as x-hcx-recipient_code for the coverage-eligibility check and the preauthorisation that follow.

### Specification

Chapter [Creating and updating a participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/link/abha/policy \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "requestid": "7f3f2a4e-0c6b-4b7a-9e2d-2c1f8a5b6d90",
  "abhanumber": "12345678910111",
  "mobilenumber": "9876543210",
  "memberid": "MEM-2026-000123",
  "payerid": "100234@sbx",
  "policies": [
    {
      "productid": "PRD-FLOATER-01",
      "productname": "Family Floater Gold"
    }
  ],
  "processingid": "100235@sbx"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `requestid` (string)
- `abhanumber` (string)
- `mobilenumber` (string)
- `memberid` (string)
- `payerid` (string)
- `policies` (object[])
- `policies.productid` (string)
- `policies.productname` (string)
- `processingid` (string)

## Responses

- `200`: On success the service returns HTTP 200 with ParticipantLinkAbhaResponse, whose two optional fields are result (a string) and errormessage (errorcode and errordescription).
  - `result` (string)

Example 200 response. The values are placeholders:

```json
{
  "result": "success"
}
```


---

# Submit the participant search

`POST /participant/search`

Reads a participant's full registry record by participant_code, including roles, status, encryption_cert and endpoint_URL.

### Business purpose

Before addressing a transaction to a counterparty, an integrator needs to know that the participant exists, is active, holds the expected role and publishes an encryption certificate and callback endpoint. The registry is the phone book of NHCX, and this call is the direct lookup by code. Providers use it to inspect a payer they have selected; payers use it to confirm the sender of an inbound request; everyone uses it to verify their own record after an update.

### When to use

Use it to check a participant's record once you know its code. Call it before you send the first message to a new recipient, or to confirm your own record after an update.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- You have the target's `participant_code`, the same value you will put in `x-hcx-recipient_code`.

### Postconditions

You get the participant's full registry record. Nothing changes, and an unknown code returns `404`.

### Common mistakes

- Sending the code under a field name other than `participant_code`.
- Assuming a record means the participant can transact: its status must be active.
- Reading `encryption_cert` as the certificate itself. Use `/fetch/certs` for that.
- Leaving out the `Accept` header.

### Best practices

- Cache the record for the session and re-read it when a transport error (NHCX-1001) or decrypt failure (PAYR-1001/PAYR-1002) suggests stale routing or key data.
- Check roles and status before selecting the counterparty for x-hcx-recipient_code.
- Call it against your own code after every registry update to confirm the change is live.
- Never log payment_details from the response.
- Treat the participants array as possibly empty and handle 404 gracefully.

### Related scenario

A hospital's TPA desk has selected a payer code from /fetch/participants/list for a PMJAY patient. Before submitting anything the integration calls /participant/search with that participant_code and receives the payer's record: roles include payer, status is Active, scheme_code matches, and endpoint_URL and encryption_cert are populated. The engine stores the code as the payerId that will become x-hcx-recipient_code, calls /fetch/certs to obtain the actual certificate, and then encrypts and sends /v1/coverageeligibility/check.

### Specification

Chapter [Creating and updating a participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/search \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "participant_code": "<payer participant code>"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `participant_code` (string)

## Responses

- `200`: HTTP 200 with ParticipantSearchResponse: timestamp (Unix timestamp when the request is sent) and participants, an array of full participant records with participant_code, linked_registry_codes, participant_name, scheme_code, roles, address, primaryEmail, additionalEmail, phone, primaryMobile, additionalMobile, status, signing_cert_path, encryption_cert, endpoint_url and payment_details.
  - `timestamp` (integer)
  - `participants` (object[])
  - `participants.participant_code` (string)
  - `participants.participant_name` (string)
  - `participants.linked_registry_codes` (string[])
  - `participants.scheme_code` (string)
  - `participants.roles` (string[])
  - `participants.status` (string[])
  - `participants.primaryEmail` (string)
  - `participants.primaryMobile` (string)
  - `participants.encryption_cert` (string)
  - `participants.endpoint_url` (string)

Example 200 response. The values are placeholders:

```json
{
  "timestamp": 1716204567358,
  "participants": [
    {
      "participant_code": "<payer participant code>",
      "participant_name": "Demo Insurance Company",
      "linked_registry_codes": [
        "125@payer"
      ],
      "scheme_code": "default",
      "roles": [
        "payer"
      ],
      "status": [
        "Active"
      ],
      "primaryEmail": "claims@demoinsurer.example.in",
      "primaryMobile": "9800000001",
      "encryption_cert": "https://registry.example.in/certs/1518.pem",
      "endpoint_url": "https://nhcx.demoinsurer.example.in"
    }
  ]
}
```


---

# Submit the participant update (v1)

`POST /participant/update`

Sandbox call. Updates a participant's registry record; participant_code and roles are mandatory, every other field (certificate, endpoint, contacts, status) is optional.

### Business purpose

Participant details change over the life of an integration: callback endpoints move, encryption certificates are rotated annually, contact numbers and payment details change. The registry is the source of truth that the gateway routes from, so those changes must land there, not just in the participant's own configuration. This v1 update lets an organisation amend any attribute of its full record in one synchronous call, and the sandbox onboarding document names it as the way to update the bridge URL, the encryption certificate or any other attribute.

### When to use

Use it in the sandbox, after registration, whenever a detail of your participant record must change. The sandbox address is `https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/update`. In production, use `/v2/participant/update` followed by `/update/validate` to change the certificate or the callback URL. For a certificate change alone, `/v2/update/cert` is simpler.

### Preconditions

- The participant already exists and you know its `participant_code`.
- You have a valid access token in the `bearer_auth` header.
- If you change the certificate, the new private key is already on your callback server.

### Postconditions

The registry record now holds the new values. Other participants see the change on their next lookup, though some may cache your certificate for up to 24 hours.

### Common mistakes

- Leaving out `roles`: it is required even when roles do not change.
- Using the v2 field names in this body.
- Publishing a new certificate before its private key is live, so callbacks cannot be decrypted.
- Setting a callback URL with an IP address or port.

### Best practices

- Read the current record with /participant/search first and send the full intended state, so a partial body does not unintentionally blank optional fields.
- Rotate certificates in two phases and keep the old private key for at least 24 hours, the documented certificate cache TTL.
- Confirm callback reachability (domain name, India-based host, NAT IPs 3.109.99.210, 13.126.152.0 and 13.200.129.223 whitelisted) before pointing endpoint_URL at a new host.
- Log the change with who requested it; registry changes affect where encrypted health data is delivered.

### Related scenario

A hospital migrates its claims callback service to a new domain. Before touching the registry the team deploys the service, verifies the NHCX NAT IPs are whitelisted and copies the existing PKCS8 private key across. They fetch a Bearer token via /get/session, read the current record with /participant/search, and call /participant/update with participant_code, roles and the new endpoint_URL. The registry returns 200. The next /v1/preauth/on_submit callback from the payer arrives at the new domain and is acknowledged with 202 within 30 seconds.

### Specification

Chapter [Your certificate](/docs/nhcx/v1/getting-started/your-certificate) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/update \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "participant_code": "<participant code>",
  "participant_name": "Test Hospital",
  "scheme_code": "PMJAY",
  "roles": [
    "10001"
  ],
  "primaryEmail": "integration@hospital.example",
  "phone": [
    "01123456789"
  ],
  "primaryMobile": "9876543210",
  "endpoint_url": "https://nhcx.hospital.example",
  "signing_cert_path": "",
  "encryption_cert": "<encryption cert>"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `participant_code` (string)
- `participant_name` (string)
- `scheme_code` (string)
- `roles` (string[])
- `primaryEmail` (string)
- `phone` (string[])
- `primaryMobile` (string)
- `endpoint_url` (string)
- `signing_cert_path` (string)
- `encryption_cert` (string)

## Responses

- `200`: HTTP 200 with a string body (the OpenAPI declares string; the sandbox onboarding document shows the participant code echoed back, for example 100001@sbx).
  - `_contentType` (string)
  - `_body` (string)

Example 200 response. The values are placeholders:

```json
{
  "_contentType": "string",
  "_body": "100001@sbx"
}
```


---

# Submit the de-link payer product

`POST /product/delink`

Removes a product (product ID and name) from a payer's participant code in the registry.

### Business purpose

When a payer withdraws a product from the market or replaces it, the registry entry created by /product/link should be removed so that it is no longer resolvable and cannot be referenced by new member links. The OpenAPI document describes this Retrieving API call as the API to de-link products by the payers or insurance companies. Keeping the catalogue accurate protects providers from matching on retired products when they resolve coverage for InsurancePlan and preauthorisation.

### When to use

Use it when a product is withdrawn. Remove the member links to it first.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- Member links to the product are already removed.
- You send `productid`, `productname` and `participantcode`.

### Postconditions

The product no longer belongs to the payer in the registry. Providers that cached it keep seeing it until they force a refresh.

### Common mistakes

- Sending only `productid`. All three fields are required.
- Removing a product while members are still linked to it.
- Expecting providers to see the change at once.

### Best practices

- Enumerate and de-link affected member policies before removing the product.
- Use the exact productid and productname that were registered with /product/link.
- Verify afterwards with /product/getowner that the product no longer resolves to your participant code.
- Log the request and the returned participant_code for audit.
- Refresh the Bearer token proactively and retry once on 401.

### Related scenario

An insurer retires its old Individual Health Silver product at the end of a policy year, having migrated every member to a successor product. Its system first runs /participant/delink/abha/policy for each member still linked to the old product, then calls /product/delink with the product ID, product name and the insurer's participant code. A confirmation call to /product/getowner shows the product no longer resolves. The insurer notifies its network hospitals, whose desks force a refresh of cached policies so that the next coverage-eligibility check and preauthorisation reference the successor product.

### Specification

Chapter [Participants and policies](/docs/nhcx/v1/registries) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/product/delink \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "productid": "PRD-INDIV-07",
  "productname": "Individual Health Silver",
  "participantcode": "100234@sbx"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `productid` (string)
- `productname` (string)
- `participantcode` (string)

## Responses

- `200`: On success the endpoint returns HTTP 200 with ParticipantCreateResponse containing the optional participant_code.
  - `participant_code` (string)

Example 200 response. The values are placeholders:

```json
{
  "participant_code": "100234@sbx"
}
```


---

# Get product owner

`POST /product/getowner`

Resolves a product ID to the participant code of the payer that owns it.

### Business purpose

Given only a product identifier, an integrator often needs to know which payer stands behind it. This Retrieving API call takes a ProductOwnerRequest with productid and returns ParticipantCreateResponse, whose participant_code is the owning participant's identifier on the HCX instance. That makes it a useful bridge between a product seen on a policy document or in a policy lookup and the participant code that must go into routing. Note that the OpenAPI description reads "This API is to generate the product ID and product Name", which does not match the response schema; the source does not resolve this conflict.

### When to use

Use it when you have a product ID and need the payer that owns it. Payers use it after `/product/link` or `/product/delink` to confirm the registry state.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- You send the `productid`.
- The payer has registered the product.

### Postconditions

You get the owning payer's participant code. Nothing changes.

### Common mistakes

- Using this code as `x-hcx-recipient_code` when a TPA processes the payer's claims. Use the processing ID from get-policies.
- Expecting product details in the answer.
- Sending an empty body.

### Best practices

- Treat the result as the product owner (payerid), then resolve the effective receiver through the policy lookup.
- Cache owner lookups by productid; ownership changes rarely and only through /product/link and /product/delink.
- Handle a missing participant_code gracefully; every field in the response is optional.
- Refresh the Bearer token proactively and retry once on 401.

### Related scenario

A hospital receives a scanned policy card that shows only a product ID, and the patient's ABHA-based policy lookup returned more than one payer. The HMIS calls /product/getowner with the product ID and gets back the participant code of the insurer that owns it, which lets the desk pick the right entry from the /participant/get/policies result. With the matched policy in hand the system reads the processingID as the receiver code, requests the plan through /v1/insuranceplan/request and goes on to submit the preauthorisation.

### Specification

Chapter [Participants and policies](/docs/nhcx/v1/registries) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/product/getowner \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "productid": "PRD-FLOATER-01"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `productid` (string)

## Responses

- `200`: Returns HTTP 200 with ParticipantCreateResponse containing the optional participant_code of the owning participant.
  - `participant_code` (string)
- `400`: Client error. The body is the participant service's ErrorResponse.
  - `timestamp` (string, required): When the response was sent, as a Unix timestamp in milliseconds.
  - `error` (object, required)
  - `error.code` (string): The error code, namespaced by the system that raised it.
  - `error.message` (string): A short description of the error.
  - `error.trace` (string): A longer description supporting the code.
- `404`: Resource not found. The body is the participant service's ErrorResponse.
  - `timestamp` (string, required): When the response was sent, as a Unix timestamp in milliseconds.
  - `error` (object, required)
  - `error.code` (string): The error code, namespaced by the system that raised it.
  - `error.message` (string): A short description of the error.
  - `error.trace` (string): A longer description supporting the code.
- `500`: Downstream systems down, or an unhandled exception. The body is the participant service's ErrorResponse.
  - `timestamp` (string, required): When the response was sent, as a Unix timestamp in milliseconds.
  - `error` (object, required)
  - `error.code` (string): The error code, namespaced by the system that raised it.
  - `error.message` (string): A short description of the error.
  - `error.trace` (string): A longer description supporting the code.

Example 200 response. The values are placeholders:

```json
{
  "participant_code": "100234@sbx"
}
```


---

# Link payer product

`POST /product/link`

Registers a product (product ID and name) against a payer's participant code, so that it can be referenced in ABHA policy links.

### Business purpose

Products are the payer's catalogue entries that policies[].productid and productname refer to when a beneficiary is linked. This Retrieving API call, described in the OpenAPI document as the API to list products by the payers or insurance companies, is how an insurer places a product in the registry under its own participant code. Doing so makes the product ownership resolvable through /product/getowner and gives providers a stable productId and productName to match against when they resolve coverage for InsurancePlan and preauth.

### When to use

Use it when a payer launches a new product, before any member is linked to it.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- The payer is already registered.
- You send `productid`, `productname` and `participantcode`. All three are required.

### Postconditions

The product is registered to the payer, and policy links can now refer to it.

### Common mistakes

- Leaving out one of the three fields.
- Using a participant code from the wrong environment.
- Linking members to a product before registering it here.

### Best practices

- Keep productid values stable and unique within the payer; providers use productId for product-level matching and productName as the practical policy or coverage code for plan lookup.
- Register products before linking members, and verify with /product/getowner that the product resolves to your participant code.
- Log the participant_code returned with the product identifiers for reconciliation.
- Refresh the Bearer token proactively and retry once on 401.

### Related scenario

An insurer launches a new family floater plan. Before its policy administration system can link any member, it calls /product/link with the product ID, the product name that hospitals will see, and the insurer's participant code, receiving its participant_code back in the response. It then checks /product/getowner with the product ID to confirm ownership, and begins linking members with /participant/link/abha/policy. Hospitals that later call /participant/get/policies will see the product ID and name, use productName for the InsurancePlan lookup and productId for coverage matching in the preauth.

### Specification

Chapter [Participants and policies](/docs/nhcx/v1/registries) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/product/link \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "productid": "PRD-FLOATER-01",
  "productname": "Family Floater Gold",
  "participantcode": "100234@sbx"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `productid` (string)
- `productname` (string)
- `participantcode` (string)

## Responses

- `200`: On success the endpoint returns HTTP 200 with ParticipantCreateResponse, whose single optional field participant_code is the machine-generated participant identifier on the HCX instance.
  - `participant_code` (string)

Example 200 response. The values are placeholders:

```json
{
  "participant_code": "100234@sbx"
}
```


---

# Submit the de-link ABHA policies (v2)

`POST /v2/participant/delink/abha/policy`

v2 variant of the ABHA policy de-link; same ParticipantDeLinkAbhaRequest body and response as the unversioned call.

### Business purpose

This endpoint performs the same member-layer removal as /participant/delink/abha/policy: it takes products out of a member's link for a given payer so that providers stop discovering lapsed or migrated coverage. The OpenAPI document exposes it as participantDeLinkAbhaPolicyV2 with an identical request and response schema; the documentation does not describe any behavioural difference beyond the path and operationId. It is the natural partner of /v2/participant/link/abha/policy for integrations that have standardised on the v2 paths.

### When to use

Use it in the same cases as the v1 de-link. Pair it with the v2 link and get-policies calls.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- You are the payer or TPA that linked the policies.

### Postconditions

The policies are no longer returned for that member. Providers that cached them keep seeing them until they force a refresh.

### Common mistakes

- Calling as a participant that did not create the link.
- Listing a policy that is not linked.
- Adding an ABHA number to the body.

### Best practices

- De-link only the specific products that need removing; the policies array is the unit of work.
- When moving an insurer to a new TPA, follow the documented order: de-link the existing policies, then link them again with the new TPA's participant code as processingid.
- Generate a fresh UUID for requestid on every call and log it with the response.
- Confirm the result with /participant/get/policies afterwards, and remember that providers may need a forced refresh of their own policy cache.
- Refresh the Bearer token proactively and retry once on 401 before escalating.

### Related scenario

A TPA is informed by one of its insurers that a corporate group policy has been cancelled mid-term. The TPA's system lists the affected members from its own records, calls /v2/participant/get/policies to confirm what NHCX currently holds, and then calls /v2/participant/delink/abha/policy per member with the insurer's participant code as payerid, its own code as processingid and the cancelled product. Each success is logged against the member. When a former member later presents at a hospital, the provider's policy lookup (after a forced cache refresh) no longer shows the product, and the desk proceeds as a self-pay case rather than submitting a coverage-eligibility check.

### Specification

Chapter [Creating and updating a participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/v2/participant/delink/abha/policy \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "requestid": "c4d2e1f0-8b7a-4c6d-9e5f-1a2b3c4d5e66",
  "payerid": "100234@sbx",
  "memberid": "MEM-2026-000123",
  "policies": [
    {
      "productid": "PRD-INDIV-07",
      "productname": "Individual Health Silver"
    }
  ],
  "processingid": "100235@sbx"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `requestid` (string)
- `payerid` (string)
- `memberid` (string)
- `policies` (object[])
- `policies.productid` (string)
- `policies.productname` (string)
- `processingid` (string)

## Responses

- `200`: On success the service returns HTTP 200 with ParticipantDeLinkAbhaResponse and the products are no longer visible through the get-policies endpoints for that payer and member.
  - `result` (string)

Example 200 response. The values are placeholders:

```json
{
  "result": "success"
}
```


---

# Get beneficiary policies (v2)

`POST /v2/participant/get/policies`

v2 variant of the beneficiary policy lookup; same FetchParticipantPoliciesRequest body and ParticipantListResponse as the unversioned call.

### Business purpose

This endpoint answers the same question as /participant/get/policies: which payer products is this beneficiary linked to, and therefore which payer or TPA should the hospital address. The OpenAPI document exposes it as getParticipantGetPoliciesV2 with an identical request and response schema and the same Registry APIs tag; the documentation records no behavioural difference beyond the path. Integrations that use the v2 link and de-link calls typically read back through this endpoint.

### When to use

Use it at the same point as the v1 lookup, before eligibility and pre-authorisation. Payers also use it to check a link they just made.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- The payer or TPA has already linked the member.
- Send the ABHA number without hyphens.

### Postconditions

You get the member's linked policies. Cache them, and force a refresh when something changes on the payer side.

### Common mistakes

- Using the payer ID as `x-hcx-recipient_code`. Use the processing ID from this response.
- Sending the ABHA number with hyphens.
- Trying only one identifier type.

### Best practices

- Normalise the ABHA number (strip separators) before the call and try identifiers in the documented priority order: ABHA, then MemberId from the latest admission, then mobile number.
- Cache successful lookups keyed by patient, but expose a forceRefresh path and use it as the first diagnostic step when a preauth is rejected for a coverage mismatch.
- Store payerId, memberId, productId, productName and policyNumber from the result; these feed x-hcx-recipient_code, the Coverage and Patient identifiers and the InsurancePlan lookup.
- If the lookup yields nothing, fall back to a coverage-eligibility check with purpose discovery to obtain the active policy code.
- Keep the token fresh; retry once on 401.

### Related scenario

A TPA has just linked a new member through /v2/participant/link/abha/policy and wants to verify the write before closing the ticket. It calls /v2/participant/get/policies with identifiertype AbhaNumber and the member's hyphen-free ABHA number and sees the product returned. Months later the same member is admitted; the hospital's HMIS runs the identifier cascade (ABHA, then member ID, then mobile) against this endpoint, caches the result, and proceeds to /v1/insuranceplan/request and /v1/preauth/submit addressed to the TPA's participant code taken from processingID.

### Specification

Chapter [Creating and updating a participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/v2/participant/get/policies \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "identifiertype": "MemberId",
  "identifiervalue": "MEM-2026-000123"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `identifiertype` (string)
- `identifiervalue` (string)

## Responses

- `200`: Returns HTTP 200 with ParticipantListResponse (optional participantdetails array of participantcode, participantname, address, state).
  - `participantdetails` (object[])
  - `participantdetails.participantcode` (string)
  - `participantdetails.participantname` (string)
  - `participantdetails.address` (string)
  - `participantdetails.state` (string)

Example 200 response. The values are placeholders:

```json
{
  "participantdetails": [
    {
      "participantcode": "100234@sbx",
      "participantname": "Demo Health Insurance Co",
      "address": "Plot 12, Sector 5, Gurugram",
      "state": "Haryana"
    }
  ]
}
```


---

# Initiate ABHA policy link (v2)

`POST /v2/participant/link/abha/policy/init`

First half of the two-step v2 link: submits the ABHA policy link request, to be confirmed with a passcode via the validate endpoint.

### Business purpose

The init variant exists so that a policy link can be confirmed out of band before it takes effect. It takes the same ParticipantLinkAbhaRequest as the direct link calls but pairs with GET /v2/participant/link/abha/policy/validate, which accepts a passcode and transactionId. This mirrors the passcode-confirmed pattern already used for participant creation (/validate) and update (/update/validate), giving payers and TPAs an approval gate on member-layer writes. The documentation describes the pairing but does not detail how the passcode is delivered for this endpoint.

### When to use

Use it when your NHCX instance needs linking confirmed with a passcode. Start the link here, then finish it with the validate call.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- You are the payer or its TPA, using the credentials that participant was created with.
- The body carries the member, the payer and the policies to link.

### Postconditions

The link is started but not confirmed. Do not rely on it until the validate call succeeds.

### Common mistakes

- Stopping here and never calling the validate step.
- Using a token from different credentials than the payer or TPA was created with.
- Mixing up `payerid` and `processingid`.

### Best practices

- Persist the requestid you sent and the transaction identifier you receive together, so the validate step can be completed by a different process or after a restart.
- Complete the validate step promptly; the sibling participant create and update passcodes expire after 24 hours, so do not assume a longer window here.
- Use the same product identifiers as registered through /product/link.
- Confirm the outcome with /participant/get/policies before informing the provider or beneficiary.
- Refresh the Bearer token proactively and retry once on 401.

### Related scenario

An insurer's policy administration team is required by its NHCX instance to confirm member links by passcode. When a new policy is issued, the system posts the ParticipantLinkAbhaRequest to /v2/participant/link/abha/policy/init and records the transaction identifier. The authorised operator receives the passcode and the system calls GET /v2/participant/link/abha/policy/validate with passcode and transactionId to complete the link. The team then checks /v2/participant/get/policies for the member's ABHA number and, satisfied, closes the case; the hospital will discover the policy on the beneficiary's next admission.

### Specification

Chapter [Creating and updating a participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/v2/participant/link/abha/policy/init \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "requestid": "3c9e8d2f-5b4a-4e1c-9f7d-8a6b5c4d3e21",
  "abhanumber": "12345678910111",
  "mobilenumber": "9876543210",
  "memberid": "MEM-2026-000123",
  "payerid": "100234@sbx",
  "policies": [
    {
      "productid": "PRD-FLOATER-01",
      "productname": "Family Floater Gold"
    }
  ],
  "processingid": "100235@sbx"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `requestid` (string)
- `abhanumber` (string)
- `mobilenumber` (string)
- `memberid` (string)
- `payerid` (string)
- `policies` (object[])
- `policies.productid` (string)
- `policies.productname` (string)
- `processingid` (string)

## Responses

- `200`: The service answers synchronously with HTTP 200 and ParticipantLinkAbhaResponse (optional result and errormessage).
  - `result` (string)

Example 200 response. The values are placeholders:

```json
{
  "result": "success"
}
```


---

# Validate ABHA policy link (v2)

`GET /v2/participant/link/abha/policy/validate`

Second half of the two-step v2 link: confirms an initiated ABHA policy link with the passcode and transactionId query parameters.

### Business purpose

This GET endpoint closes the approval loop opened by /v2/participant/link/abha/policy/init. By requiring a passcode tied to a transactionId, it ensures that a member-layer write attributed to a payer or TPA was actually authorised by that organisation, in the same way that participant creation and update are confirmed through /validate and /update/validate. The value to the ecosystem is trust in the registry: providers rely on the policy lookup, so the links behind it should be deliberate and traceable.

### When to use

Call it after the init call, once you have the passcode. It confirms the link.

### Preconditions

- An init call has returned a transaction ID.
- You have the passcode for that transaction.
- You have a valid access token in the `bearer_auth` header.

### Postconditions

The link is confirmed and providers can find the member's policies. If the passcode or transaction is wrong, start again with init.

### Common mistakes

- Sending `passcode` and `transactionId` in a body. They go in the query string.
- Using a transaction ID from a different call.
- Waiting until the passcode expires.

### Best practices

- URL-encode both query parameters and log the transactionId with the outcome.
- Treat a 404 or an errormessage as a signal to restart from init rather than retrying the same passcode indefinitely.
- Verify the confirmed link with /participant/get/policies using the same ABHA number.
- Keep the init and validate calls under the same participant token so the identity check passes.

### Related scenario

A TPA's operations desk initiated a policy link for a new member earlier in the day through /v2/participant/link/abha/policy/init and stored the transaction identifier against the case. When the authorised approver supplies the passcode, the system calls GET /v2/participant/link/abha/policy/validate?passcode=...&transactionId=... and receives a 200 with a result string. The desk then runs /v2/participant/get/policies for the member's ABHA number, sees the product listed, and closes the linking task; the next call in the member's journey will be the hospital's coverage-eligibility check.

### Specification

Chapter [Creating and updating a participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant) of the NHCX integration specification.

```bash
curl --request GET \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/v2/participant/link/abha/policy/validate \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Responses

- `200`: On success the endpoint returns HTTP 200 with ParticipantLinkAbhaResponse (optional result and errormessage).
  - `result` (string)

Example 200 response. The values are placeholders:

```json
{
  "result": "success"
}
```


---

# Link ABHA number to policies (v2)

`POST /v2/participant/link/abha/policy`

v2 variant of the ABHA policy link; same ParticipantLinkAbhaRequest body and ParticipantLinkAbhaResponse as the unversioned call.

### Business purpose

This endpoint serves the same business need as /participant/link/abha/policy: it lets a payer (or the TPA processing on its behalf) record which products a beneficiary holds, keyed by ABHA number and member ID, so that providers can discover the policy and route claims correctly. The OpenAPI document exposes it as operation participantLinkAbhaPolicyV2 with an identical request and response schema to the v1 path; the documentation does not describe any behavioural difference beyond the path and operationId.

### When to use

Use it in the same cases as the v1 link call. Pick the v1 or v2 path and use it throughout your integration.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- You are the payer or its TPA, using the credentials that participant was created with.

### Postconditions

The member's policies are linked at once and providers can find them. Only the de-link calls reverse it.

### Common mistakes

- Using a token from different credentials than the payer or TPA was created with.
- Mixing up `payerid` and `processingid`.
- Leaving out a required field.

### Best practices

- Generate a fresh UUID for requestid on every call and log it with the response so a duplicate submission can be traced.
- Keep the ABHA number in the form the member layer expects (the identifier table and get/policies documentation both specify ABHA without hyphens) and store it in that form.
- Make sure productid and productname exactly match the payer's product catalogue as registered through /product/link, because providers will later match on these values.
- Cache and proactively refresh the Bearer token; retry once on 401 with a new token, then stop and alert.
- After linking, verify the result with /participant/get/policies using the same identifier before telling the provider the member is ready.

### Related scenario

A TPA that processes claims for several insurers migrates its integration to the v2 participant APIs. When one of its insurers issues a new individual health policy, the TPA's system calls /v2/participant/link/abha/policy with the insurer's participant code as payerid and its own code as processingid, listing the product from the insurer's catalogue. The TPA then confirms the link with /v2/participant/get/policies using the member's ABHA number. When the beneficiary later visits a hospital, the provider resolves the processingid as the receiver code and submits the coverage-eligibility check and preauthorisation to the TPA.

### Specification

Chapter [Creating and updating a participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/v2/participant/link/abha/policy \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "requestid": "0b1d6c1e-6a5f-4d3c-8b9a-4f2e7c0d1a22",
  "abhanumber": "12345678910111",
  "mobilenumber": "9876543210",
  "memberid": "MEM-2026-000123",
  "payerid": "100234@sbx",
  "policies": [
    {
      "productid": "PRD-INDIV-07",
      "productname": "Individual Health Silver"
    }
  ],
  "processingid": "100235@sbx"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `requestid` (string)
- `abhanumber` (string)
- `mobilenumber` (string)
- `memberid` (string)
- `payerid` (string)
- `policies` (object[])
- `policies.productid` (string)
- `policies.productname` (string)
- `processingid` (string)

## Responses

- `200`: A successful call returns HTTP 200 with ParticipantLinkAbhaResponse (optional result string and optional errormessage with errorcode and errordescription).
  - `result` (string)

Example 200 response. The values are placeholders:

```json
{
  "result": "success"
}
```


---

# Submit the participant certificate and bridge update (v2)

`POST /v2/participant/update`

Production call. Stages a change to a participant encryption certificate and/or endpoint URL; returns a transactionid for passcode confirmation via /update/validate.

### Business purpose

Exactly two operational values rotate over a participant's life: the public encryption certificate that counterparties encrypt claims data with, and the endpoint (bridge) URL that the gateway delivers callbacks to. Both are security-sensitive, so the v2 update takes only those fields and gates the change behind an SMS passcode to the registered mobile number. It is step 3 of the production onboarding sequence, where a newly confirmed participant publishes its certificate for the first time, and the documented route for annual key rotation thereafter.

### When to use

Use it in production, right after your participant is confirmed, to upload your certificate and callback URL. Use it again whenever either changes, then confirm with `/update/validate` within 24 hours. The production address is `https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice/v2/participant/update`. In the sandbox, use `/participant/update`.

### Preconditions

- Your participant code exists and creation has been confirmed.
- The certificate is Base64-encoded.
- You have a valid access token in the `bearer_auth` header.
- The new private key is already on your callback server.

### Postconditions

- You get a transaction ID, and a passcode goes to your registered mobile number.
- Nothing changes until `/update/validate` succeeds with that passcode.

### Common mistakes

- Treating the `200` as done and skipping `/update/validate`.
- Sending the raw certificate instead of the Base64-encoded one.
- Using the v1 field names in this body.
- Starting a new update while a passcode is pending, which cancels the earlier one.

### Best practices

- Prepare the new key pair, deploy the PKCS8 private key to the callback host and only then publish the certificate.
- Keep the previous private key available for at least 24 hours after validation to decrypt callbacks encrypted against a cached certificate.
- Persist transactionid with its 24-hour expiry and complete /update/validate promptly.
- Rotate encryption keys once a year, matching the 365-day validity of the self-signed certificate.
- Verify the new endpointurl is a domain name on an India-based server with the NHCX NAT IPs whitelisted before submitting.

### Related scenario

A TPA has just confirmed its production participant with /validate. Its engineers generate a 2048-bit RSA key, a 365-day self-signed X.509 certificate, Base64-encode it and deploy the private key to the callback host. They call /v2/participant/update with participantcode, encryptioncert and endpointurl; the response returns status and a transactionid, and the registered phone receives a passcode. After GET /update/validate succeeds, the first provider to call /fetch/certs for the TPA receives the new certificate and can encrypt a pre-authorisation for it.

### Specification

Chapter [Your certificate](/docs/nhcx/v1/getting-started/your-certificate) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice/v2/participant/update \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "participantcode": "XXXXX7583@hcx",
  "encryptioncert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...",
  "endpointurl": "https://nhcx.demotpa.example.in"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `participantcode` (string)
- `encryptioncert` (string)
- `endpointurl` (string)

## Responses

- `200`: HTTP 200 with ParticipantCertUpdateResp: participant_code, status and transactionid.
  - `participant_code` (string)
  - `status` (string)
  - `transactionid` (string)

Example 200 response. The values are placeholders:

```json
{
  "participant_code": "XXXXX7583@hcx",
  "status": "Update initiated",
  "transactionid": "1vouv8tlz2tnl-1fpspjhwj07c6"
}
```


---

# Update certificate (v2, no passcode)

`POST /v2/update/cert`

Replaces a participant's public encryption certificate by participantId without passcode validation; the same schema is echoed back on success.

### Business purpose

Encryption keys are recommended to be rotated once a year, and a compromised key must be replaced immediately. The passcode-gated /v2/participant/update is the safer general route, but it needs a person with the registered phone and a 24-hour confirmation step. This endpoint exists for certificate-only updates without that validation, so an organisation can publish a new public certificate quickly. Only the certificate changes; the endpoint URL is untouched.

### When to use

Use it to replace your certificate, on schedule or in an emergency, without a passcode step. To change your callback URL too, use `/v2/participant/update`.

### Preconditions

- You have a valid access token in the `bearer_auth` header.
- You send `participantId` and the new certificate, Base64-encoded.
- The matching new private key is already on your callback server.

### Postconditions

Your certificate is replaced at once, with no validation step. Some participants may keep the old one cached for up to 24 hours.

### Common mistakes

- Sending the raw certificate instead of the Base64-encoded one.
- Publishing the certificate before its private key is live.
- Deleting the old private key straight away. Keep it for 24 hours.
- Trying to change the callback URL here.

### Best practices

- Rotate in two phases: deploy the new PKCS8 private key, publish the certificate, and keep the old key for at least 24 hours.
- Generate a 2048-bit RSA key and a 365-day self-signed X.509 certificate so the validity matches the annual rotation recommendation.
- Verify with /participant/search or a /fetch/certs call against your own code that the new certificate is served.
- Restrict who can call this endpoint inside your organisation, since it replaces the key that protects all inbound health data without a passcode.
- Notify the ecosystem promptly if rotation is due to suspected compromise, as the protocol expects.

### Related scenario

A hospital's security audit finds its NHCX private key was copied to a shared drive. The team generates a new 2048-bit RSA key pair and 365-day self-signed certificate, deploys the PKCS8 private key to the callback host and Base64-encodes the certificate. With a Bearer token they call /v2/update/cert with participantId XXXXX7583@hcx and the certificate; the registry echoes the schema back. They keep the old key available for one day so payers still holding the cached certificate can be decrypted, then destroy it. The next /v1/preauth/on_submit from the payer, encrypted against the new certificate, decrypts cleanly.

### Specification

Chapter [Your certificate](/docs/nhcx/v1/getting-started/your-certificate) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/v2/update/cert \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "participantId": "XXXX@hcx",
  "certificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Headers

- `Accept` (string, required): Always `application/json` on the participant service.

## Body

- `participantId` (string)
- `certificate` (string)

## Responses

- `200`: HTTP 200 with the UpdateCertV2 schema echoed back (participantId and certificate).
  - `participantId` (string)
  - `certificate` (string)

Example 200 response. The values are placeholders:

```json
{
  "participantId": "XXXX@hcx",
  "certificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
}
```


---

# Participant registry

The participant service holds the registry: who is on the exchange, their certificates and callback addresses, and the policies linked to a beneficiary.

## Two things to know before you call

**`/get/session` is not the gateway sessions call.** The participant service publishes its own token call under the same name other documents use for the ABDM gateway session. The two differ in address, headers, body encoding and response field names. Use the gateway call by default. The differences are set out in [Session token](/docs/nhcx/v1/getting-started/session-token#the-other-call-named-session).

## APIs

The rows run in the order the calls happen: your token and your own record, then the payer's products and policy links, then the lookups a provider makes before it sends a message. **Environment** is Sandbox or Production when a call belongs to one environment. Both means no environment limit is published, so the path goes after either base.

| Call                                                                                                                     | Called by                                                             | Environment | Method and path                                 | What it does                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Get session token](/docs/nhcx/v1/api/registry/endpoints/registry-get-session)                                           | Any participant                                                       | Both        | `POST /get/session`                             | Exchanges the participant's client\_id and client\_secret (OAuth 2.0 client credentials) for a Bearer access\_token valid for 1200 seconds.                  |
| [Participant update (v1)](/docs/nhcx/v1/api/registry/endpoints/registry-participant-update)                              | Any participant                                                       | Sandbox     | `POST /participant/update`                      | Updates a participant's registry record; participant\_code and roles are mandatory, every other field (certificate, endpoint, contacts, status) is optional. |
| [Participant certificate and bridge update (v2)](/docs/nhcx/v1/api/registry/endpoints/registry-v2-participant-update)    | Any participant                                                       | Production  | `POST /v2/participant/update`                   | Stages a change to a participant encryption certificate and/or endpoint URL; returns a transactionid for passcode confirmation via /update/validate.         |
| [Update certificate (v2, no passcode)](/docs/nhcx/v1/api/registry/endpoints/registry-v2-update-cert)                     | Any participant                                                       | Both        | `POST /v2/update/cert`                          | Replaces a participant's public encryption certificate by participantId without passcode validation; the same schema is echoed back on success.              |
| [Link payer product](/docs/nhcx/v1/api/registry/endpoints/registry-product-link)                                         | Payer                                                                 | Both        | `POST /product/link`                            | Registers a product (product id and name) against a payer's participant code, so that it can be referenced in ABHA policy links.                             |
| [De-link payer product](/docs/nhcx/v1/api/registry/endpoints/registry-product-delink)                                    | Payer                                                                 | Both        | `POST /product/delink`                          | Removes a product (product id and name) from a payer's participant code in the registry.                                                                     |
| [Get product owner](/docs/nhcx/v1/api/registry/endpoints/registry-product-getowner)                                      | Payer, to confirm its products; a provider, to find a product's payer | Both        | `POST /product/getowner`                        | Resolves a product id to the participant code of the payer that owns it.                                                                                     |
| [Get product id and name](/docs/nhcx/v1/api/registry/endpoints/registry-participant-getproductidname)                    | Not stated                                                            | Both        | `POST /participant/getProductIdName`            | Retrieving API described as generating the product id and product name; declared with a bare string request body and a participant-code response.            |
| [Link ABHA number to policies](/docs/nhcx/v1/api/registry/endpoints/registry-participant-link-abha-policy)               | Payer                                                                 | Both        | `POST /participant/link/abha/policy`            | Payer-side write that links a beneficiary's ABHA number and member id to one or more products, so provider policy lookups can find them.                     |
| [Link ABHA number to policies (v2)](/docs/nhcx/v1/api/registry/endpoints/registry-v2-participant-link-abha-policy)       | Payer                                                                 | Both        | `POST /v2/participant/link/abha/policy`         | v2 variant of the ABHA policy link; same ParticipantLinkAbhaRequest body and ParticipantLinkAbhaResponse as the unversioned call.                            |
| [Initiate ABHA policy link (v2)](/docs/nhcx/v1/api/registry/endpoints/registry-v2-participant-link-abha-policy-init)     | Payer                                                                 | Both        | `POST /v2/participant/link/abha/policy/init`    | First half of the two-step v2 link: submits the ABHA policy link request, to be confirmed with a passcode via the validate endpoint.                         |
| [Validate ABHA policy link (v2)](/docs/nhcx/v1/api/registry/endpoints/registry-v2-participant-link-abha-policy-validate) | Payer                                                                 | Both        | `GET /v2/participant/link/abha/policy/validate` | Second half of the two-step v2 link: confirms an initiated ABHA policy link with the passcode and transactionId query parameters.                            |
| [De-link ABHA policies](/docs/nhcx/v1/api/registry/endpoints/registry-participant-delink-abha-policy)                    | Payer                                                                 | Both        | `POST /participant/delink/abha/policy`          | Removes specific products from a member's policy link for a payer, keyed on payerid, memberid and the products listed.                                       |
| [De-link ABHA policies (v2)](/docs/nhcx/v1/api/registry/endpoints/registry-v2-participant-delink-abha-policy)            | Payer                                                                 | Both        | `POST /v2/participant/delink/abha/policy`       | v2 variant of the ABHA policy de-link; same ParticipantDeLinkAbhaRequest body and response as the unversioned call.                                          |
| [Fetch participants list](/docs/nhcx/v1/api/registry/endpoints/registry-fetch-participants-list)                         | Any participant                                                       | Both        | `POST /fetch/participants/list`                 | Payer discovery: lists participants filtered by role, registration date window and optional entity type; the first step of the cashless workflow.            |
| [Participant search](/docs/nhcx/v1/api/registry/endpoints/registry-participant-search)                                   | Any participant                                                       | Both        | `POST /participant/search`                      | Reads a participant's full registry record by participant\_code, including roles, status, encryption\_cert and endpoint\_url.                                |
| [Participant details (v2 search)](/docs/nhcx/v1/api/registry/endpoints/registry-participant-details)                     | Any participant                                                       | Both        | `POST /participant/details`                     | v2 variant of participant search: takes participant\_code and returns the matching full registry records.                                                    |
| [Get beneficiary policies](/docs/nhcx/v1/api/registry/endpoints/registry-participant-get-policies)                       | Provider                                                              | Both        | `POST /participant/get/policies`                | Looks up the policies linked to a beneficiary by ABHA number, member id or mobile number, returning the payer and product details needed for claims.         |
| [Get beneficiary policies (v2)](/docs/nhcx/v1/api/registry/endpoints/registry-v2-participant-get-policies)               | Provider                                                              | Both        | `POST /v2/participant/get/policies`             | v2 variant of the beneficiary policy lookup; same FetchParticipantPoliciesRequest body and ParticipantListResponse as the unversioned call.                  |
| [Fetch certificate](/docs/nhcx/v1/api/registry/endpoints/registry-fetch-certs)                                           | Any participant, before it seals a message                            | Both        | `POST /fetch/certs`                             | Returns a participant's public encryption certificate (PEM X.509 or SPKI key) by participantid; cache it for 24 hours and use it to build the JWE.           |
| [Fetch certificate path](/docs/nhcx/v1/api/registry/endpoints/registry-fetch-certs-path)                                 | Any participant                                                       | Both        | `POST /fetch/certs/path`                        | Companion to /fetch/certs: takes the same participantid body and returns a string described as the participant's certificate path.                           |

## Base URLs

| Environment                   | Base URL                                                        |
| ----------------------------- | --------------------------------------------------------------- |
| Sandbox, Participant service. | `https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice` |
| Production.                   | `https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice`   |

## Guides that use these calls

- [Creating and updating a participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant)
- [Finding participants and policies](/docs/nhcx/v1/getting-started/finding-participants-and-policies)
- [Fetching a recipient certificate](/docs/nhcx/v1/getting-started/fetching-a-recipient-certificate)
- [Get your sandbox credentials](/docs/nhcx/v1/getting-started/get-your-sandbox-credentials)
- [Quickstart](/docs/nhcx/v1/getting-started/quickstart)
- [The recipient cannot decrypt your message](/docs/nhcx/v1/troubleshooting/the-recipient-cannot-decrypt)

The whole specification, with a request you can send from the page, is the [Participant registry API reference](/reference/nhcx-registry).


---

# Submit the session token

`POST /api/hiecm/gateway/v3/sessions`

Mints the ABDM gateway session token that every NHCX call carries, from the client ID and secret you received when you registered on the ABDM sandbox (`ABDM_CLIENT_ID` and `ABDM_CLIENT_SECRET`).

### Business purpose

The token does not come from NHCX. It comes from the ABDM gateway, and one token serves every call: the participant service, the use-case endpoints and the status check. Nothing else in this collection works without it, which is why the post-response script below stores it in `token`, so that running this request once arms the rest of the collection.

### When to use

Call it before your first NHCX call. Call it again when your token is more than about 18 minutes old, ahead of its 20-minute (1200-second) expiry, or when any call answers `401`.

### Preconditions

- You hold the client ID and secret you received when you registered on the ABDM sandbox (`ABDM_CLIENT_ID` and `ABDM_CLIENT_SECRET`).
- `REQUEST-ID` is a new UUID and `TIMESTAMP` is the current UTC time from a synced clock.
- `X-CM-ID` is `sbx` on the sandbox.
- The body sets `grantType` to `client_credentials`.

### Postconditions

The gateway returns an access token in `accessToken`. Send it on every NHCX call in the `bearer_auth` header, as `Bearer <token>`. The token lasts 1200 seconds (20 minutes), stated in `expiresIn`.

### Common mistakes

- Copying a `REQUEST-ID` from an example instead of making a new one.
- Typing the `TIMESTAMP` by hand, or reading it from a clock that has drifted.
- Leaving out `grantType`, as older samples do.
- Sending the token without the `Bearer ` prefix.

### Best practices

- Keep the token together with the time you got it, and fetch a new one before a call if it is more than about 18 minutes old, ahead of the 20-minute expiry.
- On any `401`, get a new token and retry that call once.
- Send the token in `bearer_auth` on every NHCX call.
- Keep the clock synchronised with NTP and let a date library format the timestamp.

### Related scenario

A hospital's integration starts its first eligibility check of the day. It posts this request with a new `REQUEST-ID`, the current UTC `TIMESTAMP` and `X-CM-ID` `sbx`, stores the `accessToken` with the time it arrived, and sends it on the check as `bearer_auth: Bearer <token>`. Later a claim call answers `401 Sender is not authorized to execute the operation`. The integration mints a fresh token, retries the claim once, and it goes through.

### Specification

Chapter [Base URLs](/docs/nhcx/v1/getting-started/base-urls) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://dev.abdm.gov.in/api/hiecm/gateway/v3/sessions \
  --header 'REQUEST-ID: <uuid>' \
  --header 'TIMESTAMP: <iso timestamp>' \
  --header 'X-CM-ID: sbx' \
  --header 'Content-Type: application/json' \
  --data '{
  "clientId": "<client id>",
  "clientSecret": "<client secret>",
  "grantType": "client_credentials"
}'
```

## Headers

- `REQUEST-ID` (string, required): `REQUEST-ID` is a fresh UUID that you generate for every call. Sending the same one twice is the mistake to avoid; generate it, do not copy it from an example.
- `TIMESTAMP` (string, required): `TIMESTAMP` is the current time in UTC, ISO 8601 with milliseconds and a trailing `Z`, as in `2026-09-04T06:15:51.975Z`. A clock that has drifted will be refused, so take the time from the system rather than constructing it by hand. How to produce it in each language is at the end of this chapter.
- `X-CM-ID` (string, required): `X-CM-ID` names the environment. It is `sbx` on the sandbox. The mirror and the adapter both use lowercase.

## Body

- `clientId` (string)
- `clientSecret` (string)
- `grantType` (string)

## Responses

- `200`: The gateway returns `accessToken`, `expiresIn` `1200` (20 minutes), `refreshToken` and `tokenType` `bearer`.
  - `accessToken` (string)
  - `expiresIn` (integer)
  - `refreshTokenIn` (integer)
  - `refreshToken` (string)
  - `tokenType` (string)

Example 200 response. The values are placeholders:

```json
{
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "expiresIn": 1200,
  "refreshTokenIn": 300,
  "refreshToken": "eyJhbGciOiJSUzI1NiIs...",
  "tokenType": "bearer"
}
```


---

# Session

The token does not come from NHCX.

## APIs

| Call                                                                                       | Called by       | Method and path                       | What it does                                                                                                                                           |
| ------------------------------------------------------------------------------------------ | --------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Session token](/docs/nhcx/v1/api/session/endpoints/session-api-hiecm-gateway-v3-sessions) | Any participant | `POST /api/hiecm/gateway/v3/sessions` | Mints the ABDM gateway session token that every NHCX call carries, from the client ID and secret you received when you registered on the ABDM sandbox. |

## Base URLs

| Environment                  | Base URL                   |
| ---------------------------- | -------------------------- |
| Sandbox, ABDM session token. | `https://dev.abdm.gov.in`  |
| Production.                  | `https://apis.abdm.gov.in` |

## Guides that use these calls

- [Session token](/docs/nhcx/v1/getting-started/session-token)
- [Quickstart](/docs/nhcx/v1/getting-started/quickstart)

The whole specification, with a request you can send from the page, is the [Session API reference](/reference/nhcx-session).


---

# Payer: send the search result

`POST /v1/search/on_submit`

Callback returning a search result for task type code=poll; for a claim-document search the payload is the ClaimResponse for the reference number.

### Business purpose

This is how a payer answers an authorised entity's search. It completes the oversight loop: the regulator or scheme authority asked for the claim documents for a case, and the payer returns the adjudication record through NHCX rather than by email or portal download. That keeps the answer encrypted, correlated to the original request and auditable. Providers benefit indirectly, because disputes and audits can be resolved from the record of what was actually submitted and decided rather than from reconstructed paperwork.

### When to use

The payer calls it to answer a `/v1/search/submit` request. For a claim document search, the payload is the `ClaimResponse` for the case.

### Preconditions

- You received and decrypted the search `Task`, and answered it with `202`.
- You have a valid access token and the requester's certificate.
- The header repeats the search's `x-hcx-correlation_ID`.

### Postconditions

NHCX answers `202` and passes the result to the requester. The claim itself does not change.

### Common mistakes

- Returning the result in the `202` instead of on this callback.
- Making a new correlation ID, so the requester cannot match the answer.
- Sending a `Task` or a bare bundle instead of the `ClaimResponse`.
- Missing the 30-second window on the incoming search, which causes redeliveries.

### Best practices

- Key the search on the sender's reference ID from Task.about and echo it in basedOn.
- Populate about with your own reference ID and the current status so the requester needs no further call.
- Return 202 to the inbound search first, resolve documents asynchronously, then post this callback.
- Be idempotent on correlation ID; the same search may be redelivered up to five times.
- Use a fresh API_call_ID, IST timestamp and a responder status from response.complete, response.partial or response.error.

### Related scenario

An insurer receives a search Task from the scheme authority for a claim its TPA rejected last quarter. The gateway-facing endpoint acknowledges with 202, and a worker retrieves the stored ClaimResponse for the reference number. The TPA posts /v1/search/on_submit with the ClaimResponse, basedOn set to the authority's reference ID and about set to the insurer's claim ID and current status, under the same correlation ID as the search. The authority's system acknowledges within 30 seconds and the reviewer compares the adjudication against the provider's original claim and any reprocess Task submitted on /v1/task/submit.

### Specification

Chapter [NHCX adapter (Optional)](/docs/nhcx/v1/getting-started/nhcx-adapter) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/search/on_submit \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: The gateway returns HTTP 202 with the StatusSuccessResponse envelope (or 400, 404, 500 in the same shape) and delivers the result to the requester's registered endpoint, which must acknowledge with 202 within 30 seconds.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "25/08/2026 14:20:00:341",
  "api_call_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
  "correlation_id": "33445566-7788-99aa-bbcc-ddeeff001122",
  "result": {
    "sender_code": "<payer participant code>",
    "recipient_code": "<provider participant code>",
    "entity_type": "task",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Authorised entity: search for claim information

`POST /v1/search/submit`

Authorised entity such as NHA or IRDAI sends a Task to retrieve claim information for a case; the payer returns the documents on the search callback.

### Business purpose

Regulators and scheme authorities need to see what was actually claimed and decided for a given case without being a party to the original exchange. The Search API is that privileged pull path: an authorised entity submits a Task naming the case, and the payer supplies the claim documents. It supports oversight, audit and dispute review, and it lets payers answer such requests through the same encrypted, correlated channel as everything else on NHCX. The documented callers are NHA and IRDAI; a provider integration usually implements only the responding side.

### When to use

Use it when an authorised body such as NHA or IRDAI needs the claim documents for a known case, for example during an audit. The result arrives later on `/v1/search/on_submit`.

### Preconditions

- You are an entity allowed to search, registered on NHCX, with a valid access token.
- The payload is an encrypted FHIR `Task` that points to the case being queried.
- `x-hcx-correlation_ID` carries the correlation ID of the request being queried.

### Postconditions

NHCX answers `202` at once. The payer sends the documents later on `/v1/search/on_submit`. Search only reads, so nothing about the case changes.

### Common mistakes

- Using search to ask where a request is. Use `/v1/status` for that.
- Sending a `CommunicationRequest` instead of a `Task`.
- Making a new correlation ID instead of carrying the one being queried.
- Expecting the documents in the `202`.

### Best practices

- Reference the case in Task.about using the sender's own reference ID and keep it consistent with the correlation ID you carry.
- Persist the correlation ID so the on_submit result can be matched.
- Use fresh API_call_ID values, IST timestamps and request.initiated on the outbound header.
- Handle 404 as a signal that the correlation ID is unknown to the gateway, not as a retry trigger.
- Implement v1/error and the on_submit receiver before submitting searches.

### Related scenario

A scheme authority reviewing a grievance about a rejected claim needs the payer's adjudication record. Its integration posts /v1/search/submit with a Task whose about element names the case and whose header carries the claim's correlation ID. The gateway acknowledges with 202 and forwards the Task to the payer. The payer's system locates the ClaimResponse for the reference number and returns it on /v1/search/on_submit with basedOn holding the authority's reference and about holding the payer's reference and current status. The authority then compares it with the provider's original /v1/claim/submit bundle.

### Specification

Chapter [NHCX adapter (Optional)](/docs/nhcx/v1/getting-started/nhcx-adapter) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/search/submit \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOiJOSEExQGhjeCJ9.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: The gateway returns HTTP 202 with a StatusSuccessResponse (timestamp, api_call_id, correlation_id, result with sender_code, recipient_code, entity_type and protocol_status, and error), or 400, 404 or 500 in the same envelope.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "25/08/2026 14:00:00:098",
  "api_call_id": "f6a7b8c9-d0e1-2345-f012-456789012345",
  "correlation_id": "33445566-7788-99aa-bbcc-ddeeff001122",
  "result": {
    "sender_code": "<provider participant code>",
    "recipient_code": "<payer participant code>",
    "entity_type": "task",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Sender: check the status of a request

`POST /v1/status`

Sender asks NHCX where its own in-flight request stands; the gateway answers request.queued or request.dispatched, and only dispatched yields a callback.

### Business purpose

Asynchronous exchanges lose messages, stall in queues and outlive the shift of the desk operator who started them. The Status API exists so the original sender can find out which side of the exchange is holding a request without resubmitting it and creating a duplicate. It answers the hospital desk's most common question, where is my preauth, by telling it whether the gateway has forwarded the request to the payer at all. Providers, payers and TPAs all benefit because it separates gateway delay from payer delay before anyone escalates.

### When to use

Use it when the callback for a request you sent has not arrived. Set `x-hcx-correlation_ID` to the `x-hcx-API_call_ID` of that request. You can only check requests you sent yourself.

### Preconditions

- You sent the original request and kept its `API_call_ID`.
- You have a valid access token.
- The encrypted payload is an empty string, and the header status is `request.initiated`.

### Postconditions

NHCX answers at once with `request.queued` or `request.dispatched`. Queued means the payer has not seen the request, and no callback follows. Dispatched means the payer has it and will answer on the status callback.

### Common mistakes

- Making a new correlation ID instead of using the original request's `API_call_ID`.
- Polling in a tight loop.
- Resubmitting the original request after `request.queued`, which creates a duplicate.

### Best practices

- Persist the correlation ID against the case record before every submission so a status check is always possible.
- Use a bounded, spaced schedule tied to the correlation ID, then escalate; do not poll aggressively.
- Branch on protocol_status: wait on request.queued, expect the status callback on request.dispatched.
- Use a fresh x-hcx-API_call_ID per status call and IST timestamps.
- Treat Status as transport position only; the decision lives in the original on_ callback or a Search for the claim document.
- Implement the status callback and v1/error so both branches of the answer have somewhere to land.

### Related scenario

A hospital's TPA desk submitted a preauth on /v1/preauth/submit at 09:00 and by 13:00 nothing has arrived on /v1/preauth/on_submit. Rather than resubmit, the integration posts /v1/status with the preauth's correlation ID. The synchronous reply shows protocol_status request.dispatched, so the request is with the payer, not stuck at the gateway; the desk stops worrying about a lost message and waits for the status callback and the eventual preauth decision. Had the reply been request.queued, the desk would have waited on the gateway and, if the delay persisted, escalated to NHCX support with the correlation ID.

### Specification

Chapter [NHCX adapter (Optional)](/docs/nhcx/v1/getting-started/nhcx-adapter) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/status \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: The gateway validates the request and returns the protocol status synchronously in the HTTP response: HTTP 202 with a StatusSuccessResponse whose result carries sender_code, recipient_code, entity_type and protocol_status of request.queued or request.dispatched.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "25/08/2026 13:00:00:215",
  "api_call_id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
  "correlation_id": "11223344-5566-7788-99aa-bbccddeeff00",
  "result": {
    "sender_code": "<provider participant code>",
    "recipient_code": "<payer participant code>",
    "entity_type": "preauth",
    "protocol_status": "request.dispatched"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Authorised entity receives the search result

`POST /v1/search/on_submit`

Hosted by the participant that sent the search, such as NHA or a regulator. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/search/on_submit`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Callback returning a search result for task type code=poll; for a claim-document search the payload is the ClaimResponse for the reference number.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/search/on_submit \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "task",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Payer receives a claim search

`POST /v1/search/submit`

Hosted by the payer. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/search/submit`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Authorised entity such as NHA or IRDAI sends a Task to retrieve claim information for a case; the payer returns the documents on the search callback.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/search/submit \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOiJOSEExQGhjeCJ9.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "task",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Payer receives a status check

`POST /v1/status`

Hosted by the payer. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/status`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Sender asks NHCX where its own in-flight request stands; the gateway answers request.queued or request.dispatched, and only dispatched yields a callback.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/status \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "preauth",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Status and search errors

A Status and search code arrives sealed inside the callback, not in the response to your call. These are the codes the Catalogue records on this module's paths.

## Codes

| Code                                                                    | What it means                                        |
| ----------------------------------------------------------------------- | ---------------------------------------------------- |
| [`NHCX-1010`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1010) | No request matches the correlation id on your answer |
| [`NHCX-1012`](/docs/nhcx/v1/reference/pmjay-error-codes?code=NHCX-1012) | No message matches the api\_call\_id you gave        |

Every code above is recorded in the Catalogue. The aggregated list across modules is at [error codes](/docs/nhcx/v1/reference/pmjay-error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# Status and search

Asynchronous exchanges lose messages, stall in queues and outlive the shift of the desk operator who started them.

## APIs

| Call                                                                                                          | Called by                                | Method and path             | What it does                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Sender: check the status of a request](/docs/nhcx/v1/api/status/endpoints/status-v1-status)                  | Any participant, about a request it sent | `POST /v1/status`           | Sender asks NHCX where its own in-flight request stands; the gateway answers request.queued or request.dispatched, and only dispatched yields a callback. |
| [Authorised entity: search for claim information](/docs/nhcx/v1/api/status/endpoints/status-v1-search-submit) | NHA or a regulator                       | `POST /v1/search/submit`    | Authorised entity such as NHA or IRDAI sends a Task to retrieve claim information for a case; the payer returns the documents on the search callback.     |
| [Payer: send the search result](/docs/nhcx/v1/api/status/endpoints/status-v1-search-on-submit)                | Payer                                    | `POST /v1/search/on_submit` | Callback returning a search result for task type code=poll; for a claim-document search the payload is the ClaimResponse for the reference number.        |

## Callbacks you host

The exchange posts these to the `endpoint_url` you registered. Answer each with HTTP 202 first.

| Path                   | Hosted by                                                        |
| ---------------------- | ---------------------------------------------------------------- |
| `/v1/status`           | The payer                                                        |
| `/v1/search/submit`    | The payer                                                        |
| `/v1/search/on_submit` | The participant that sent the search, such as NHA or a regulator |

## Base URLs

| Environment             | Base URL                          |
| ----------------------- | --------------------------------- |
| Sandbox, NHCX exchange. | `https://apisbx.abdm.gov.in/hcx`  |
| Production.             | `https://apisprod.nha.gov.in/hcx` |

## Guides that use these calls

- [Building and sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe)
- [Status and search](/docs/nhcx/v1/reference/fhir/status-and-search)
- [Accepted with 202, and no callback arrives](/docs/nhcx/v1/troubleshooting/accepted-then-no-callback)
- [Responses arrive against the wrong request](/docs/nhcx/v1/troubleshooting/responses-arrive-against-the-wrong-request)

The whole specification, with a request you can send from the page, is the [Status and search API reference](/reference/nhcx-status).


---

# Payer: send the task outcome

`POST /v1/task/on_submit`

Payer returns a Task bundle with Task.status completed whose Task.output references a ClaimResponse carrying the reprocess or cancellation outcome.

### Business purpose

This callback closes the appeal or cancellation the provider opened on /v1/task/submit. It carries the payer's final decision on a reprocess (approved, partially approved, queried or rejected) or confirms a pre-authorisation cancellation, in the same ClaimResponse shape used for ordinary adjudication so hospitals can reuse their parsers. Because the reprocess response is final within the workflow, it delivers closure, a clean audit trail and reduced ambiguity for both sides, which is the point of moving disputes inside NHCX.

### When to use

The payer calls it to answer a reprocess or cancellation Task. The answer is a completed Task that points at a `ClaimResponse` with the new decision. A cancellation is confirmed on workflow `PC02`.

### Preconditions

- The payer answered the incoming Task with `202` within 30 seconds.
- A valid access token and the provider's certificate.
- The header reuses the Task's `x-hcx-correlation_ID`.
- The `ClaimResponse` inside is built like any other decision.

### Postconditions

- NHCX answers `202` and forwards the answer to the provider.
- The provider reads the `ClaimResponse` the Task points at, like any other decision.
- The reprocess decision is final. A cancelled pre-authorisation needs a new one if treatment resumes.

### Common mistakes

- Looking for the `ClaimResponse` directly in the bundle instead of following the Task's output.
- Reading outcome `complete` as approval. A rejection is also `complete`.
- Sending a new correlation ID on the answer.
- Sending a bare `ClaimResponse` without the Task around it.

### Best practices

- Payer: acknowledge first, re-adjudicate asynchronously, then post the Task bundle with the outcome workflow ID and ClaimResponse nested in Task.output.
- Provider: share the ClaimResponse parser between /v1/claim/on_submit and this callback; only the extraction path differs.
- Branch on adjudication reason as well as outcome; check processNote for reductions or query text.
- "Terminate the appeal branch of the case state machine on 252 or 253. On 254, note that NHCX publishes no workflow code for the answer: the handbook's 19 is the preauthorisation query response code, so confirm with the payer how it wants the answer sent."
- Be idempotent on correlation ID; expect redeliveries.
- Fresh API_call_ID, IST timestamp, responder status on the callback header.

### Related scenario

A scheme payer's TPA receives a reprocess Task on a rejected claim with the missing implant invoice attached. Its endpoint returns 202 and the case reopens for re-adjudication with the original claim, the new document and the justification. The reviewer approves at the package rate, and the TPA posts /v1/task/on_submit: a Task bundle, status completed, Task.output referencing a ClaimResponse with outcome complete, workflow 252, under the claim's correlation ID. The hospital acknowledges within 30 seconds, extracts the ClaimResponse from Task.output, marks the appeal closed and awaits the payment notice on /v1/paymentnotice/request.

### Specification

Chapter [Cancel, reprocess and shortfall](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/task/on_submit \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: The gateway returns HTTP 202 with the StatusSuccessResponse envelope (400, 404, 500 in the same shape) and forwards the bundle to the provider, which must acknowledge within 30 seconds.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "26/08/2026 16:30:00:611",
  "api_call_id": "a3b4c5d6-e7f8-9012-6789-123456789012",
  "correlation_id": "66778899-aabb-ccdd-eeff-001122334455",
  "result": {
    "sender_code": "<payer participant code>",
    "recipient_code": "<provider participant code>",
    "entity_type": "task",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Provider: submit a reprocess or cancel task

`POST /v1/task/submit`

Provider sends an FHIR Task asking the payer to reprocess a rejected or short-paid claim or to cancel a preauth; Task.code and reasonCode set the intent.

### Business purpose

Claims are often not fully approved first time, for mundane reasons: missing documents, policy interpretation differences, package or pricing discrepancies. Without a formal appeal path, disputes leave the system and become phone calls and email. The Task flow gives providers a structured, auditable way to contest a decision with new evidence, and to withdraw a pre-authorisation that will never be used. Payers get a controlled re-adjudication workflow with SLA adherence, aligned with NHA and IRDAI expectations of transparent dispute resolution.

### When to use

Use it to ask the payer to reprocess a rejected or short-paid claim, or to cancel a pre-authorisation. Reprocess uses workflow `36`. Cancel uses workflow `PC01` and is answered on `PC02`.

### Preconditions

- You have a valid access token and the payer's certificate.
- The original claim or pre-authorisation exists, and the Task points to it.
- A reprocess has a clear reason and new supporting documents attached.
- The header carries the correlation ID of the original claim or pre-authorisation.

### Postconditions

- NHCX answers `202` at once. That only means the message was accepted.
- The payer's answer arrives later on `/v1/task/on_submit`.
- Only a submitted or approved pre-authorisation can be cancelled.

### Common mistakes

- Leaving out the reference to the original claim or pre-authorisation.
- Using a new correlation ID instead of the original one.
- Spelling the input anything other than `intimationNumber`.
- Cancelling a pre-authorisation that is already cancelled or paid.

### Best practices

- Link the Task to the original entity twice: basedOn with the sender's reference ID and Task.input with claimNumber and intimation number.
- Use reasonCode other only with a clear Task.description.
- Persist the correlation ID and workflow ID so the on_submit Task bundle can be matched and the ClaimResponse extracted from Task.output.
- Design the case state machine so 252 or 253 terminates the appeal branch.
- Fresh API_call_ID per call, IST timestamps, request.initiated on the outbound header.
- Implement v1/error; a Task that never reaches the payer is otherwise silent.

### Related scenario

A hospital's claim for a cardiac package, submitted on /v1/claim/submit, comes back on /v1/claim/on_submit rejected for a missing implant invoice. The billing team obtains the invoice and the integration builds a Task: code reprocess, reasonCode claimrejected, basedOn the original claim, input claimNumber and intimation number, the invoice attached, workflow 18, and the claim's correlation ID. It posts /v1/task/submit and receives 202. The payer acknowledges (251), re-adjudicates and returns a Task bundle on /v1/task/on_submit whose Task.output wraps a ClaimResponse with outcome complete and workflow 252; a payment notice follows on /v1/paymentnotice/request.

### Specification

Chapter [Cancel, reprocess and shortfall](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall) of the NHCX integration specification.

```bash
curl --request POST \
  --url https://apisbx.abdm.gov.in/hcx/v1/task/submit \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: The gateway returns HTTP 202 with a StatusSuccessResponse whose result carries entity_type task and a protocol_status; 400, 404 and 500 use the same envelope.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "25/08/2026 10:00:00:154",
  "api_call_id": "f2a3b4c5-d6e7-8901-5678-012345678901",
  "correlation_id": "66778899-aabb-ccdd-eeff-001122334455",
  "result": {
    "sender_code": "<provider participant code>",
    "recipient_code": "<payer participant code>",
    "entity_type": "task",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Provider receives the task outcome

`POST /v1/task/on_submit`

Hosted by the provider. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/task/on_submit`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Payer returns a Task bundle with Task.status completed whose Task.output references a ClaimResponse carrying the reprocess or cancellation outcome.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/task/on_submit \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "JWEPayload",
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `type` (string, required): Always `JWEPayload`. Every response (`on_`) call sends it beside `payload`. One of: JWEPayload.
- `payload` (string, required)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "task",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Payer receives a reprocess or cancel task

`POST /v1/task/submit`

Hosted by the payer. The exchange posts this message to the `endpoint_URL` you registered, at `/v1/task/submit`, with the headers and the sealed payload the sender posted. Answer HTTP 202 with the receipt first and process afterwards; [Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the rules.

Provider sends an FHIR Task asking the payer to reprocess a rejected or short-paid claim or to cancel a preauth; Task.code and reasonCode set the intent.

```bash
curl --request POST \
  --url {bridgeUrl}/v1/task/submit \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"
}'
```

## Authorization

- `bearer_auth` (apiKey, required): Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

## Protected header

These fields go in the JWE protected header of `payload`, not as HTTP headers.

- `alg` (string, required): Key management algorithm. Always `RSA-OAEP-256`: the content key is wrapped with the recipient's RSA public key.
- `enc` (string, required): Content encryption algorithm. Always `A256GCM`.
- `x-hcx-sender_code` (string, required): Your participant code. Mandatory on the envelope.
- `x-hcx-recipient_code` (string, required): The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.
- `x-hcx-api_call_id` (string, required): Fresh on every message, including responses. Mandatory on the envelope.
- `x-hcx-request_id` (string): One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.
- `x-hcx-correlation_id` (string, required): The thread that ties a request to its answers. [The correlation ID rule](/docs/nhcx/v1/reference/envelope-fields#the-correlation-id-rule-in-full) says when to reuse it. Mandatory on the envelope.
- `x-hcx-workflow_id` (string): Which step, or which case. [The workflow code](/docs/nhcx/v1/reference/envelope-fields#the-workflow-code-means-two-different-things) explains both readings. Optional on the envelope.
- `x-hcx-timestamp` (string, required): The time the message was made. [Timestamp](/docs/nhcx/v1/reference/envelope-fields#timestamp) gives the format. Mandatory on the envelope.
- `x-hcx-status` (string, required): Where this message stands. [Status words](/docs/nhcx/v1/reference/envelope-fields#status-words) lists the values. Mandatory on the envelope.
- `x-hcx-ben-abha-id` (string): The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

## Body

- `payload` (string)

## Responses

- `202`: Received. The receipt names the message it answers; the answer itself follows as a call of your own.
  - `timestamp` (string)
  - `api_call_id` (string)
  - `correlation_id` (string)
  - `result` (object)
  - `result.sender_code` (string)
  - `result.recipient_code` (string)
  - `result.entity_type` (string)
  - `result.protocol_status` (string)
  - `error` (object)
  - `error.code` (string)
  - `error.message` (string)

Example 202 response. The values are placeholders:

```json
{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "task",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}
```


---

# Reprocess, cancel and shortfall errors

A Reprocess, cancel and shortfall code arrives sealed inside the callback, not in the response to your call. These are the codes the Catalogue records on this module's paths.

## Codes

| Code                                                                    | What it means                                                                      |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [`PAYR-1017`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1017) | The amount calculations are not correct, or the Task resource has no task code     |
| [`PAYR-1018`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1018) | The time limit for submission has expired, or the Task resource has no reason code |
| [`PAYR-1252`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1252) | Case is not in a state that can be cancelled                                       |
| [`PAYR-1253`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1253) | Case is already cancelled                                                          |
| [`PAYR-1257`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1257) | Payment already initiated for the case                                             |
| [`PAYR-1258`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1258) | Payment already cleared for the case                                               |
| [`PAYR-1510`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1510) | A parameter code in your request is not valid                                      |
| [`PAYR-1511`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1511) | A parameter value in your request is not valid                                     |
| [`PAYR-1518`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1518) | Your Task resource carries no input parameters                                     |
| [`PAYR-1519`](/docs/nhcx/v1/reference/pmjay-error-codes?code=PAYR-1519) | A Task input parameter has no type                                                 |

Every code above is recorded in the Catalogue. The aggregated list across modules is at [error codes](/docs/nhcx/v1/reference/pmjay-error-codes).

[Next Still stuck? Ask for help Where to file what you hit, so the answer lands back in these pages.](/docs/support)


---

# Reprocess, cancel and shortfall

Claims are often not fully approved first time, for mundane reasons: missing documents, policy interpretation differences, package or pricing discrepancies.

One pair of calls carries every request a provider makes after a decision. `Task.code` and its reason say which one it is, and [one endpoint, five requests](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall#one-endpoint-five-requests) lists the valid combinations.

## APIs

| Call                                                                                                | Called by | Method and path           | What it does                                                                                                                                             |
| --------------------------------------------------------------------------------------------------- | --------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Provider: submit a reprocess or cancel task](/docs/nhcx/v1/api/task/endpoints/task-v1-task-submit) | Provider  | `POST /v1/task/submit`    | Provider sends a FHIR Task asking the payer to reprocess a rejected or short-paid claim or to cancel a preauth; Task.code and reasonCode set the intent. |
| [Payer: send the task outcome](/docs/nhcx/v1/api/task/endpoints/task-v1-task-on-submit)             | Payer     | `POST /v1/task/on_submit` | Payer returns a Task bundle with Task.status completed whose Task.output references a ClaimResponse carrying the reprocess or cancellation outcome.      |

The callback does not carry the decision as its leading resource. It carries a `Task` whose output points at the `ClaimResponse`, as [the answer is nested](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall#the-answer-is-nested-unlike-every-other-callback) sets out.

## Callbacks you host

The exchange posts these to the `endpoint_url` you registered. Answer each with HTTP 202 first.

| Path                 | Hosted by    |
| -------------------- | ------------ |
| `/v1/task/submit`    | The payer    |
| `/v1/task/on_submit` | The provider |

## Base URLs

| Environment             | Base URL                          |
| ----------------------- | --------------------------------- |
| Sandbox, NHCX exchange. | `https://apisbx.abdm.gov.in/hcx`  |
| Production.             | `https://apisprod.nha.gov.in/hcx` |

## Guides that use these calls

- [Building and sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe)
- [Cancel, reprocess and shortfall](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall)

The whole specification, with a request you can send from the page, is the [Reprocess, cancel and shortfall API reference](/reference/nhcx-task).


---

# Claim Settlement

Claim settlement is the end-to-end process by which an insurer or State Health Agency (SHA) evaluates, approves, and pays a request for medical expenses raised by a policyholder or treating hospital. Three participants are involved. The Provider is the treating hospital and its HMIS. The Payer is the insurance company, SHA, or TPA that adjudicates and settles the claim.

### What is Health Insurance?

Health insurance, or an Insurance Policy, is a contract between an individual and a promisor. The promisor pledges to pay the individual's medical bills, up to a set limit, in case of any ailments. The individual is commonly known as a policyholder or beneficiary whereas the promisor can be an insurance company acting by itself or on behalf of Government or any organisation or Corporate entity. It protects one’s personal savings from being drained by unexpected hospital stays, surgeries, and medicines.

### What is an Insurance Claim?

A health insurance claim is a formal request, by a policyholder or by the treating hospital, asking an insurance company to pay or refund money for medical care. The insurance company may act by itself or on behalf of Government or any organisation or Corporate entity.

### Types of Health Insurance Claim

- **Cashless** - A patient who is a beneficiary of a policy can avail treatment in a hospital without paying any amount out of one’s pocket. This applies when the hospital is in a “Preferred Network” for the Insurance Company, under an existing agreement between them. It also applies when the hospital is “Empaneled” under a specific scheme governing the policy. However, the amount of expenses incurred during treatment is capped either by “Sum Assured” under the policy or some mutually agreed upon “Package Rates” earmarked for a specific medical or surgical procedure.
- **Reimbursement** - Here a patient is required to pay the bills directly to the treating hospital and later get such an amount reimbursed by Insurance Company upon submission of all relevant documents. This is a common practice if the treating hospital is not a part of “Preferred Network” for that Insurance Company, but this model is not considered in the current scope.

### Who is a Provider?

A Provider is the treating hospital “providing” the healthcare services to a patient, who is a beneficiary under a policy. And the HMIS software that the Provider hospital is using is known as the Provider Application. In common parlance this Provider Application is called just the “Provider”.

### Who is a Payer?

A Payer is the Insurance Company who has issued the policy and is liable to make payments for medical expenses incurred for treatment of the policyholder. In some cases independent TPAs act on behalf of an Insurance Company to settle such medical bills and thereby assume the role of a Payer. On a similar note as above the software used by a Payer is called the Payer Application or simply “Payer”.

### Claim Settlement Process

This is a two-way communication between the Hospital and the Insurance Company, that is, between the Provider and the Payer. It concerns the policy, the treatment rendered to the policyholder patient, and finally the payment of hospital bills after proper scrutiny of all relevant documents. It starts with the treating hospital informing the Insurance Company of an imminent claim for a patient who is to be admitted for treatment. It ends with the realisation of payment from the Insurance Company for all expenses incurred while treating the patient. The entire journey of claim settlement can be broken down into the following distinct flows or use cases.

## The Stages of Claim Settlement on NHCX

The traditional ten stages of claim settlement map directly onto NHCX exchanges. They run in the order below, from intimation to payment.

#### Intimation

The hospital informs the insurance company that a patient holding one of its policies is going to be treated for the diagnosed ailments.

#### Policy verification by the hospital

The hospital checks that the patient to be treated holds a valid policy from that insurance company and that the ailments to be treated are covered under the policy.

#### Beneficiary and tie-up verification by the payer

The insurance company checks that a bona fide policyholder has come for treatment and that a proper tie-up is in place with the hospital for providing such cashless treatment.

#### Treatment plan intimation

The hospital sends the insurance company an initial intimation of the treatment plan, any procedures to be carried out, and the expected length of stay needed for treatment.

#### Preauthorisation

Once satisfied with the genuineness of the case, the insurance company sends a preliminary approval, commonly known as Preauthorisation or "PreAuth". This authorises the hospital to go ahead with treatment for the policyholder patient, and the patient is then admitted.

#### Enhancement

During the course of treatment, the hospital may approach the insurance company again to notify it that additional procedures may be required or that an extension of stay is needed. This is commonly known as "Enhancement".

#### Discharge and document submission

The patient is discharged, and the hospital submits all necessary documents to the insurance company, including consultation and clinical notes, diagnostic reports, medication details, the discharge summary and all bills.

#### Payer query and resolution

At this stage, the insurance company may ask for further explanation or for documents it considers necessary to substantiate the claim and support its adjudication. Such a communication from the insurance company to the hospital is called a "Query".

#### Claim adjudication

The insurance company carries out the final adjudication and conveys the outcome to the hospital, stating whether the claimed amount is "Granted", "Denied" or "Partially Granted", along with the reasons.

#### Payment and reconciliation

The insurance company pays the hospital the granted amount for the claim. It also notifies the hospital of the bank transaction details along with other details such as applicable tax or deductions.

#### End-to-End Claim Lifecycle Flow

```mermaid
flowchart TD

  A[Patient Arrives at Hospital] --> B[Coverage Eligibility Check]
  B --> C[Fetch Insurance Plan & Tariff Master]
  C --> D[Submit Preauthorisation Request]
  D --> Q1{Payer Adjudication}
  Q1 -- Query Raised --> D3[Answer Query with Documents] --> Q1
  Q1 -- Approved --> E[Inpatient Admission & Treatment]
  E --> E2{Case Requires Extension?}
  E2 -- Yes --> F[Submit Enhancement Request] --> Q1
  E2 -- No --> G[Discharge Patient & Submit Claim]
  G --> Q2{Payer Adjudication}
  Q2 -- Query Raised --> G3[Submit Additional Documents] --> Q2
  Q2 -- Decided --> H[Claim Adjudication Decision]
  H --> I[Payer Issues Payment Notice with UTR]
  I --> J[Hospital Acknowledges Settlement]
  H -. Rejected or Partial Shortfall .-> K["Task: Reprocess or Arbitration"]
  D -. Voluntary Withdrawal .-> L["Task: Cancel Preauth"]
```

## NHCX Platform

### What is NHCX?

The National Health Claims Exchange (NHCX) irons out the challenges depicted above. It is developed under the Ayushman Bharat Digital Mission (ABDM) by the National Health Authority (NHA), in consultation with the Insurance Regulatory and Development Authority of India (IRDAI). The idea is to introduce a platform of exchange to the Providers and Payers so that both can transfer digitised health records and other pertinent information directly in a machine readable format to its counterpart.

### What NHCX aims to achieve?

The primary objective of NHCX is to streamline and standardise the processing of health insurance claims across the country, ensuring absolute interoperability across diverse systems. Provider and Payer applications may operate on completely different technology stacks. Even so, one system can seamlessly remit health information to the other in a comprehensive, digitised, machine readable format, with the very exact interpretation at both ends. It is achieved by leveraging the Fast Healthcare Interoperability Resources (FHIR) standard protocols and using international coding practices, wiping out even the slightest ambiguity in the understanding.

### NHCX Operating Framework

On securities exchanges like NSE & BSE, anyone can buy or sell independently by merely getting connected to the platform. In the same way, the entire idea of NHCX is to connect Providers and Payers on either side. Once Providers and Payers become compliant to the NHCX protocols like using prescribed FHIR bundles and implementing universally accepted coding practices they can independently connect to one another using NHCX as a medium of exchange. The protocols and standards ensure that a health information does not lose any of its essence during the transfer.

### Benefits of using NHCX

- It is imperative that in the present day context almost every healthcare provider or hospital is generating digitised health records. But there is no point if the hospital has to convert that data into a “pdf” or a “jpg” file and transmit the same to the insurance company in a human readable format. NHCX is the only solution to this widespread problem
- Let us consider a diagnostic report of a patient like “Lipid Profile” that has some 10 parameter values, all very important to understand the criticality of the case. It would be very helpful for the insurance company to have those 10 different values for the individual parameters of Lipid Profile in adjudication of the case. Using NHCX such values for each of these parameters under Lipid Profile can be passed on from Provider to Payer
- Since any standard hospital HMIS already captures data pertaining to a patient like medical history, allergies, medication, line of treatment, etc. it would be apt to convey those same details to the insurance company instead of taking a printout and scanning them again for email attachments or uploads, thereby ensuring chastity of data
- Data precision is also safeguarded as the intervention of data entry operators is only limited to the first level entry into HMIS, rendering this to be the only source of truth. Eventually this translates to lesser queries and rejection of claims on flimsy grounds
- NHCX enables maximum data transfer in the digitised format, thus allowing a Payer run AI tools and conduct automated adjudication to the maximum possible extent
- Government social security schemes like Ayushman Bharat are gaining momentum, and IRDAI is advocating “Cashless Everywhere”. More and more healthcare providers are entering the arena, and only a universal model like NHCX can support this extent of scalability

### The Asynchronous Request and Callback Pattern

Claim decisions can't be made instantly. A pre-authorisation review may take minutes to hours, and a complex claim review may take days. So NHCX handles every major action in two separate steps.

#### Request

The sender calls an action endpoint, such as `preauth/submit`. NHCX checks the message headers, confirms who sent it, and immediately replies with an HTTP 202 Accepted receipt. This receipt only confirms that the message was received. It is not a decision on the case.

#### Response

```mermaid
sequenceDiagram
  box Provider side
    participant P as Hospital (Provider)
  end
  box Exchange
    participant X as NHCX Gateway
  end
  box Payer side
    participant Y as Insurer / SHA (Payer)
  end
  P->>X: POST preauth/submit
  X-->>P: 202 Accepted (Receipt: queued & routed)
  X->>Y: Delivers encrypted payload
  Y-->>X: 202 Accepted
  Note over Y: Clinical & financial adjudication
  Y->>X: POST preauth/on_submit (Decision)
  X-->>Y: 202 Accepted
  X->>P: Delivers decision to Provider callback
  P-->>X: 202 Accepted
```

The receiver opens the message, makes its decision, and sends the result later to the matching callback endpoint, such as `preauth/on_submit`. NHCX forwards this response to the sender's registered webhook, which replies with its own HTTP 202 receipt.


---

# Introduction

## What it is

The National Health Claims Exchange is a single road between hospitals and insurers. A hospital asks whether a patient is covered, asks permission to treat, sends the bill, and gets paid. Today each of those steps runs differently for every insurer. On the exchange they run the same way for all of them.

It carries the whole journey: checking cover before admission, getting treatment approved, submitting the claim at discharge, being paid, and arguing when the answer is wrong. Every step is a message out and an answer back later, so nothing is left hanging and there is a record of both halves.

Hospitals, insurers, patients, regulators and observers all connect to it the same way.

NHCX is developed under the Ayushman Bharat Digital Mission (ABDM) by the National Health Authority (NHA), in consultation with the Insurance Regulatory and Development Authority of India (IRDAI). The idea is to introduce a platform of exchange to Providers and Payers so that both can transfer digitised health records and other pertinent information directly, in a machine readable format, to their counterpart.

## What NHCX aims to achieve

NHA states five objectives for the exchange.

- **Wider cover.** Bring new kinds of claim onto the network, including outpatient (OPD) visits and pharmacy bills, so insurance is not only about hospital stays.
- **Faster money.** Shorten the time between treatment and payment, and make cashless treatment workable even in small hospitals.
- **Room to innovate.** Give insurers the structured data they need to automate decisions and to spot fraud.
- **One way of doing things.** A single, rule-based process that both sides trust, instead of every insurer running its own.
- **A better patient experience.** Fewer forms, fewer delays, fewer surprises at discharge.

Underneath all five sits one requirement. A hospital's software and an insurer's software are built by different people on different technology, and a message has to mean exactly the same thing at both ends. That is why everything on the exchange is written in one agreed format, with agreed words for diagnoses, procedures and test results. How Claims Move on NHCX introduces that format, and Bundles and Conventions in the FHIR Reference sets out its rules.

## NHCX operating framework

A stock exchange works because a buyer and a seller each connect to the exchange rather than to each other. NHCX works the same way. A hospital connects once, an insurer connects once, and from then on either can reach the other without having built anything specific to them.

## What NHCX is made of

It helps to think of NHCX as three rulebooks and one referee.

- **The protocol** says how a message travels: how it is addressed, sealed, acknowledged and answered. It is deliberately like email: a message goes to the exchange, the exchange passes it on, and the reply comes back the same way.
- **The data specifications** say what goes inside a message. Claims, policies, payments and the rest are written as FHIR records, using profiles published by NRCeS, so that both sides read the same thing.
- **The operational guidelines** say who may join, how they are checked, what they may do, and how they can be removed.
- **NHA is the referee.** It publishes the rules, runs the exchange, and works with NRCeS and IRDAI to change them.

The portal also publishes a sandbox Swagger specification for each of the exchange's services, and Environments and Addresses in the Reference section lists them.

Five principles run through all of it. The rules are **open**, published under a permissive licence so anyone can build against them. They are **evolvable**, so a scheme can add what it needs without breaking everyone else. They are **minimal**, so they are easy to understand and do not hold back innovation. They protect **privacy and security**, with sealed contents and tamper-proof records. And they are **unbundled**, so a participant can adopt one part without adopting all of it.

## Who is on the network

```mermaid
flowchart LR
  H1[Hospital] --- X((NHCX))
  H2[Clinic] --- X
  A[Patient app] --- X
  X --- P1[Insurer]
  X --- P2[Government scheme]
  X --- T[TPA]
  X --- R[Regulator]
  X --- N[Another exchange]
```

Most of this documentation talks about two parties, the hospital and the insurer. The network recognises more.

- **Providers.** Hospitals and clinics, identified by their Health Facility Registry entry.
- **Payers.** Insurance companies, and the government agencies that pay for schemes.
- **TPAs.** Third-party administrators who process claims on an insurer's behalf. On the network a TPA behaves like a payer.
- **Regulators.** IRDAI and bodies like it, who can search claims across every payer.
- **Scheme sponsors.** The owner of a programme, for example NHA for Ayushman Bharat, with payer-level access.
- **Researchers and insurance marketplaces.** Given aggregated or consented data only.
- **Patient apps.** Personal health record apps that receive notifications on a beneficiary's behalf.
- **Other exchanges.** NHCX is designed so that more than one instance can exist and relay to each other.

Each role comes with a fixed list of what it may send and receive. A hospital can ask about eligibility and submit claims; it cannot search another hospital's claims. A regulator can search; it cannot submit.

## What changes in practice

Four things are different once a hospital is on the exchange, and the rest of this documentation is about making them work.

**Records go across as records.** A hospital's software already holds the diagnosis, the test results and the treatment as data. Today most of it is printed or turned into a picture before it is sent, and the insurer's software cannot read a picture. On the exchange it goes across as data and stays readable.

**That makes automatic decisions possible.** An insurer can only decide a claim by machine if it can read the values. A blood test sent as ten separate results can be checked automatically; the same test sent as a scan cannot.

**One place to type things.** The hospital's own system becomes the single place the information is entered, rather than being re-keyed into an insurer's portal afterwards. Most rejections on technical grounds come from that second typing.

**Any hospital can reach any insurer.** A small hospital that could never afford to integrate with thirty insurers separately can integrate once.

How Claims Move on NHCX follows a claim from admission to payment, in the ordinary language of the people who do it, before any of this becomes technical.


---

# JWE Secure Messaging

Every message on NHCX is sealed so that only the participant it is addressed to can read it. The exchange carries the message, reads its address, and never sees what is inside. This page explains that model in plain terms. The fields, algorithms and exact values are in [The JWE message format](/docs/nhcx/v1/getting-started/jwe-message-format).

## Envelope and letter

Picture a sealed letter inside an addressed envelope.

The envelope is what the exchange reads. It says who sent the message and who it is for. It carries a number for this call and a number for the whole conversation. It also says which step of the claim this is, when it was sent, and whether it is a request or an answer. The exchange uses these to route and to keep records.

The letter is the FHIR bundle. The sender seals it with the receiver's public key before it leaves, so the exchange can carry it but cannot read it. Only the receiver can open it.

A few facts can also be written on the outside of the envelope, for example the amount claimed. These are called domain headers. They let the exchange keep an audit trail without opening anything.

## One exchange or several

```mermaid
sequenceDiagram
  participant P as Provider (on instance A)
  participant A as NHCX instance A
  participant B as NHCX instance B
  participant Y as Payer (on instance B)
  P->>A: Sealed request
  A->>A: Registry lookup, validation, audit
  A->>B: Relay the sealed request
  B->>B: Registry lookup, validation, audit
  B->>Y: Deliver to the payer's callback
  Y->>B: Sealed answer
  B->>A: Relay the sealed answer
  A->>P: Deliver to the provider's callback
```

NHCX is designed so that more than one exchange instance can run, relaying messages between them. A participant's address carries the instance after the `@`, as in `1518@hcx`. When a hospital and its payer are on the same instance, that instance delivers the message. When they are on different instances, the hospital's instance relays it to the payer's. Each instance does its own registry lookup, validation, audit and routing. The relaying exchange is a participant with the role `HIE`, and it cannot read the letter either.

A relay is needed whenever the two participants in an exchange sit on different instances. Three cases lead to that:

- **Payer on another instance.** The hospital is on instance A. The payer that runs the policy's scheme is on instance B. Instance A passes the hospital's message to instance B, which delivers it to the payer.
- **Treatment in another state.** A beneficiary is treated at a network hospital in another state. That hospital is on instance A, and the beneficiary's payer is on instance B. The relay works as in the first case.
- **Top-up cover.** The patient has a primary and a secondary insurance. The primary payer is on instance A and the secondary payer is on instance B. A hospital on instance A reaches the primary payer directly, and its messages to the secondary payer are relayed to instance B.

In every case the answer travels back along the same path, from instance B to instance A and then to the hospital.

Neither instance can open the letter at any point on this path.

## Protected Headers

Think of the address written on the outside of an envelope. The postman and the post office can read it, and they use it to decide where the letter goes, but they never open the letter itself. Protected headers work the same way. They are written on the outside of every NHCX message so the exchange can read them, route the message and keep records, while the contents stay sealed. Every NHCX header name starts with `x-hcx-`

- **Sender Code** - Who is sending. Your participant ID
- **Recipient Code** - Who it is for. For a provider, the processor code from the policy lookup
- **Correlation Id** - A number for the whole conversation. The same on the request and on every answer to it.
- **Workflow Id** - Which step of the claim this is. The codes are listed in the Workflow Codes chapter
- **Timestamp** - When it was sent

There are a few other fields as well, such as the call and request IDs, the status and the beneficiary's ABHA number. The full list, with the rules for each, is in Envelope Fields in the Reference section.

Along with these, the message must meet a few requirements specific to JWE, the format used to seal it `A256GCM`.

## How a message is sealed

Sealing uses two keys, each doing the job it is good at. The format that packages the result is JSON Web Encryption, or JWE.

1. **Write the letter.** The sender builds the FHIR bundle.
2. **Address the envelope.** The sender writes the protected header: sender, recipient, identifiers, step, status and time.
3. **Find the recipient's lock.** The sender fetches the recipient's public certificate from the registry. Anyone may hold a public key. Only its owner holds the matching private key.
4. **Make a one-time key.** The sender generates a fresh random key for this message alone.
5. **Lock the letter.** The bundle is encrypted with the one-time key. The envelope is bound into this step, so changing any header later breaks the seal.
6. **Lock the key.** The one-time key is encrypted with the recipient's public key.
7. **Package it.** The header, the locked key and the locked letter are joined into one string and posted to the exchange.

Why two keys? Public key encryption proves only one party can open something, but it is slow and handles small inputs. Shared key encryption is fast for a large bundle, but both sides would need the key in advance. Locking the letter with a one-time key, and locking only that small key with the public key, gives both properties.

## How a message is opened

```mermaid
sequenceDiagram
  participant S as Sender
  participant X as NHCX exchange
  participant R as Recipient
  S->>S: Build bundle and header
  S->>S: Lock bundle with a one-time key
  S->>S: Lock the one-time key with the recipient's public key
  S->>X: Sealed message
  X->>X: Read and check the header only
  X->>R: Deliver sealed message
  R->>R: Unlock the one-time key with its private key
  R->>R: Unlock and check the bundle
```

The exchange reads the envelope, checks it, and delivers the whole message to the recipient's callback. It cannot unlock the one-time key, because it does not hold the recipient's private key.

1. **Check the address.** The recipient reads the header and confirms the message is for it.
2. **Unlock the key.** It uses its own private key to recover the one-time key.
3. **Unlock the letter.** It decrypts the bundle with the one-time key. The same step checks that neither the bundle nor the header changed on the way. Any change makes decryption fail.
4. **Read and check the bundle.** The recipient parses the FHIR and validates it.
5. **Answer the same way.** The reply is sealed with the original sender's public key, and the cycle runs in reverse.

The most common failure is sealing with the wrong public key: your own, or a stale one. The exchange accepts the message, because the envelope is fine, and the recipient cannot open it. [The recipient cannot decrypt](/docs/nhcx/v1/troubleshooting/the-recipient-cannot-decrypt) covers that case.

## Where a message stands

Every envelope carries a status word. The sender sets it to say whether this is a new request, an interim answer, a final answer or a refusal. The exchange tracks its own states too: queued, delivered, or stopped after delivery failed. The values and the rules for each are in [The JWE message format](/docs/nhcx/v1/getting-started/jwe-message-format).

## When a message is refused

A message can be refused for three kinds of reason. The first two follow the envelope and letter split. The third is a business decision on a message that was delivered and read correctly.

- **The exchange refuses the envelope.** A missing header, an unknown recipient or an expired token. The sender hears at once, in the response to its own call.

- **The receiver refuses the letter.** It could not decrypt the bundle, or the bundle failed validation. It answers on the callback with a short error in the envelope, and the sender hears later.

- **The payer refuses on business grounds.** The message arrived and was valid, but the payer will not accept the request. For example:

  - The patient is not covered by the policy
  - The beneficiary already has an active preauthorisation open
  - The coverage balance is not enough for the amount asked
  - The claim amount is more than the preauthorisation approved
  - The claim is a duplicate of one already sent

Each refusal carries a code. [Error codes](/docs/nhcx/v1/reference/error-codes) lists every code with its message and what to do. [Reading error codes](/docs/nhcx/v1/reference/error-code-guide) explains the code families.

## Everything is logged

The exchange records every call it receives: the envelope, the encryption details, sender and recipient, and whether validation passed. It never records the letter. Participants can query the audit trail for their own transactions, and NHA publishes reports from it for payers, providers, regulators and observers.

## Where to go next

- [The JWE message format](/docs/nhcx/v1/getting-started/jwe-message-format): every field, status value, receipt and error code.
- [Building and sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe): seal and post your first message.
- [Envelope fields](/docs/nhcx/v1/reference/envelope-fields): each header checked against its sources.


---

# NHCX Use Cases

A use case covers each stage of the claims lifecycle: onboarding providers and payers onto the network, verifying coverage, seeking preauthorisation, submitting claims, exchanging supporting information, and reconciling payments. Between them they deliver the core objectives of standardisation, traceability, and predictable auto-adjudication across India's National Health Claims Exchange (NHCX).

## Key Use Cases Overview

- **Onboarding Providers and Payers**: Onboard participants onto NHCX to validate and route requests to target applications.
- **Check Coverage Eligibility**: Called by providers to verify beneficiary coverage, policy validity, sum insured, sub-limits, and document requirements.
- **Preauth Request Submission**: Submitted by providers before admission or planned surgery. Payers respond with a line-item decision.
- **Claim Request Submission**: Submitted by providers upon discharge with final bill, discharge summary, and itemised claims.
- **Communication Request**: Enables payers to query providers for additional documents, flag turnaround-time breaches, or issue policy updates.
- **Payment Notice & Reconciliation**: Payers notify providers of bank transfers, detailing claimed, approved, TDS, and settled amounts.
- **Reprocess / Cancel / Shortfall**: Providers appeal rejected claims, request the balance of a partial payment, or cancel approved preauthorisations.
- **Beneficiary Notifications**: Push notifications to personal health record (PHR) apps on claim status changes.

---

## Master Use Cases Matrix

All 38 use cases by role. Open one to see what it does in plain words, its full detail, the API it calls and where the answer comes back.

### Shared

The following use cases are common to both Payer and Provider participants on the NHCX platform. None of them carries a workflow code, because they are registry and session calls rather than claim transactions.

A1Get participant list

Looks up who is on the network. A hospital uses it to find an insurer, and an insurer uses it to find a hospital.

The participants in the registry, by role. How a provider finds a payer and a payer finds a provider.

**What information goes in and out**

- **You send:** the kind of participant you are looking for, such as insurers.
- **You get back:** each participant's ID, its name, the address it receives messages on, and where to find its encryption certificate.

API call[`/fetch/participants/list`API reference](/docs/nhcx/v1/api/registry/endpoints/registry-fetch-participants-list)

CallbackNone

A2Get policy

Finds the insurance policies a patient holds, using their ABHA number, member ID or mobile number. Each policy names the insurer and the company that processes its claims. Claims are always sent to that processing company.

The policies a beneficiary holds, by ABHA number, member ID or mobile number. Each names the insurer and the processor, and the processor is the recipient for every claim-side call.

**What information goes in and out**

- **You send:** the patient's ABHA number, member ID or mobile number, as `identifiertype` (`AbhaNumber`, `MemberId` or `MobileNo`) and `identifiervalue`.
- **You get back:** each policy number, with the insurer and the claims processor for that policy.

API call[`/participant/get/policies`API reference](/docs/nhcx/v1/api/registry/endpoints/registry-participant-get-policies)

CallbackNone

A3Get public key

Fetches the other side's public key. Every message is locked with the receiver's key, so this comes before sending anything to them.

The recipient's certificate, which is what the bundle is encrypted with. Fetched before anything is addressed to a participant.

**What information goes in and out**

- **You send:** the participant ID of the one you want to write to.
- **You get back:** its public key certificate.

API call[`/fetch/certs`API reference](/docs/nhcx/v1/api/registry/endpoints/registry-fetch-certs)

CallbackNone

A4Get auth token

Gets the pass that every call to the exchange must carry. It is issued with the same client ID and secret used for ABDM.

The ABDM session token every NHCX call carries, minted with your ABDM sandbox client ID and secret.

**What information goes in and out**

- **You send:** your client ID and client secret.
- **You get back:** an access token and how long it stays valid.

API call[`/get/session`API reference](/docs/nhcx/v1/api/registry/endpoints/registry-get-session)

CallbackNone

A5Get status

Asks where an earlier request has got to. Useful when an answer is slow to arrive.

- **FHIR Reference:** [Status and Search, A5](/docs/nhcx/v1/reference/fhir/status-and-search#a5-get-status-shared)

Where any request you made got to, by its correlation id. The sandbox's own status page answers without a token.

API call[`/v1/status`API reference](/docs/nhcx/v1/api/status/endpoints/status-v1-status)

Callback[`/v1/on_status`API reference](/docs/nhcx/v1/api/other/endpoints/other-webhook-v1-on-status)

A6Receive errors

Where the exchange reports that it could not deliver one of your requests after five tries. Without it, a failed request looks exactly like one still under review, so every participant must have it.

Where the exchange tells you a request could not be delivered after five attempts. Without it a sender never learns that a request died, which looks exactly like a case still under review.

**What information goes in and out**

- **The exchange sends you:** the ID of the request that failed, an error code, and a description of what went wrong.

API callhosted only

Callback[`/v1/error`API reference](/docs/nhcx/v1/api/other/endpoints/other-webhook-v1-error)

### Provider

The following use cases are initiated by Provider participants (hospitals, daycare centers) to verify coverage, submit preauthorisations, answer queries, submit claims, and reconcile payments.

B1Check coverage eligibility

Checks that the patient's policy is active, how much cover is left, and which documents the insurer will need. It is usually the first thing a hospital does.

- **Workflow ID:** None
- **FHIR Reference:** [Coverage Eligibility Request, B1](/docs/nhcx/v1/reference/fhir/coverage-eligibility-request#b1-check-coverage-eligibility-provider)

Is the policy in force, what is left in the wallet, and what must be attached. One endpoint, four purposes: discovery, validation, benefits, auth-requirements.

API call[`/v1/coverageeligibility/check`API reference](/docs/nhcx/v1/api/eligibility/endpoints/eligibility-v1-coverageeligibility-check)

Callback[`/v1/coverageeligibility/on_check`API reference](/docs/nhcx/v1/api/eligibility/endpoints/eligibility-webhook-v1-coverageeligibility-on-check)

B2Request insurance plan

Downloads the details of the patient's plan: the treatments it covers, the rates it pays, and the documents and forms each one needs.

- **FHIR Reference:** [Insurance Plan Request, B2](/docs/nhcx/v1/reference/fhir/insurance-plan-request#b2-request-insurance-plan-provider)

A Task with code poll, keyed on policy number and provider id. The answer is the policy as a benefit structure: packages, rates, documents, questionnaires.

API call[`/v1/insuranceplan/request`API reference](/docs/nhcx/v1/api/insurance-plan/endpoints/insurance-plan-v1-insuranceplan-request)

Callback[`/v1/insuranceplan/on_request`API reference](/docs/nhcx/v1/api/insurance-plan/endpoints/insurance-plan-webhook-v1-insuranceplan-on-request)

B3Submit pre-authorisation

Asks the insurer for approval before treatment. The same request is also used to send a revised request, ask for more money, or answer a question from the insurer. The insurer's first reply gives the case its own reference number, and everything after is filed under it.

- **Workflow ID:** [`12`](/docs/nhcx/v1/concepts/workflow-codes?code=12#every-workflow-code), [`121`](/docs/nhcx/v1/concepts/workflow-codes?code=121#every-workflow-code), [`13`](/docs/nhcx/v1/concepts/workflow-codes?code=13#every-workflow-code), [`19`](/docs/nhcx/v1/concepts/workflow-codes?code=19#every-workflow-code), [`131`](/docs/nhcx/v1/concepts/workflow-codes?code=131#every-workflow-code)
- **FHIR Reference:** [Preauthorisation Request, B3](/docs/nhcx/v1/reference/fhir/preauthorisation-request#b3-submit-pre-authorisation-provider)

Permission to treat. A resubmission, an enhancement and a query answer all reuse the same bundle with a new correlation id and the original reference; only the workflow code tells them apart. The acknowledgement on 20 brings the payer's own case number, and the desk files everything under it.

API call[`/v1/preauth/submit`API reference](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-submit)

Callback[`/v1/preauth/on_submit`API reference](/docs/nhcx/v1/api/preauth/endpoints/preauth-webhook-v1-preauth-on-submit)

B4Respond to a communication

Replies to a message the insurer sent about a case, such as a request for more documents. The answer goes back on the same case.

- **Workflow ID:** [`24`](/docs/nhcx/v1/concepts/workflow-codes?code=24#every-workflow-code), [`241`](/docs/nhcx/v1/concepts/workflow-codes?code=241#every-workflow-code), [`27`](/docs/nhcx/v1/concepts/workflow-codes?code=27#every-workflow-code)
- **FHIR Reference:** [Communication, B4](/docs/nhcx/v1/reference/fhir/communication#b4-respond-to-a-communication-provider)

Acknowledge or answer a message the payer sent about a case. A generic or IRDAI payer raises its query here, as a CommunicationRequest task bundle carrying 24, 241 or 27. The answer is a Communication task bundle on on\_request that echoes the request's correlation id and workflow id. The payer's reason code says what kind of message it was.

API call[`/v1/communication/on_request`API reference](/docs/nhcx/v1/api/communication/endpoints/communication-v1-communication-on-request)

Callback[`/v1/communication/request`API reference](/docs/nhcx/v1/api/communication/endpoints/communication-webhook-v1-communication-request)

B5Submit claim

Claims payment after the patient is discharged. The amount cannot be more than what was approved before treatment. The insurer's first reply gives the claim its reference number.

- **Workflow ID:** [`15`](/docs/nhcx/v1/concepts/workflow-codes?code=15#every-workflow-code), [`161`](/docs/nhcx/v1/concepts/workflow-codes?code=161#every-workflow-code), [`14`](/docs/nhcx/v1/concepts/workflow-codes?code=14#every-workflow-code)
- **FHIR Reference:** [Claim Request, B5](/docs/nhcx/v1/reference/fhir/claim-request#b5-submit-claim-provider)

Reimbursement after discharge. The amount may not exceed what the pre-authorisation approved. The acknowledgement on 25 brings the payer's case number. PMJAY takes a claim query answer on 161 only; 151, 19 and 16 are refused with PAYR-1321.

API call[`/v1/claim/submit`API reference](/docs/nhcx/v1/api/claim/endpoints/claim-v1-claim-submit)

Callback[`/v1/claim/on_submit`API reference](/docs/nhcx/v1/api/claim/endpoints/claim-webhook-v1-claim-on-submit)

B6Search claims

Looks up claims that match some criteria. The published sources do not agree on which address a hospital uses to search its own claims, so confirm it before building.

- **FHIR Reference:** [Status and Search, B6](/docs/nhcx/v1/reference/fhir/status-and-search#b6-search-claims-provider)

Look up claim information by criteria. The provider sandbox exit checklist names /v1/search/submit for claim search, while the Technical Specifications route /search/submit from NHA through NHCX to the payer: a cross-payer search for NHA or a regulator. A provider's search over its own cases is /claim/search in the protocol, which the access-control policy allows for requests that originated from the provider. No source confirms which of the two the sandbox accepts from a provider.

API call[`/v1/search/submit`API reference](/docs/nhcx/v1/api/status/endpoints/status-v1-search-submit)

Callback[`/v1/search/on_submit`API reference](/docs/nhcx/v1/api/status/endpoints/status-webhook-v1-search-on-submit)

B7Acknowledge payment notice

Confirms that the hospital received the insurer's payment notice. Every notice must be acknowledged.

- **Workflow ID:** [`30`](/docs/nhcx/v1/concepts/workflow-codes?code=30#every-workflow-code), [`17`](/docs/nhcx/v1/concepts/workflow-codes?code=17#every-workflow-code)
- **FHIR Reference:** [Payment Notice and Acknowledgement, B7](/docs/nhcx/v1/reference/fhir/payment-notice-and-acknowledgement#b7-acknowledge-payment-notice-provider)

The receipt for a payment notice, as a Task on this endpoint. The notice arrives on a new thread of its own; a generic payer takes the acknowledgement with the notice's 30 echoed, PMJAY with 17.

API call[`/v1/paymentnotice/on_request`API reference](/docs/nhcx/v1/api/payment-notice/endpoints/payment-notice-v1-paymentnotice-on-request)

Callback[`/v1/paymentnotice/request`API reference](/docs/nhcx/v1/api/payment-notice/endpoints/payment-notice-webhook-v1-paymentnotice-request)

B8Reprocess or cancel

One request for three jobs: appeal a rejected claim, ask for the rest of a part-paid claim, or cancel an approval. An appeal must include a supporting document.

- **Workflow ID:** [`PC01`](/docs/nhcx/v1/concepts/workflow-codes?code=PC01#every-workflow-code), [`36`](/docs/nhcx/v1/concepts/workflow-codes?code=36#every-workflow-code)
- **FHIR Reference:** [Cancel, Reprocess and Shortfall, B8](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall#b8-reprocess-or-cancel-provider)

One endpoint, several jobs, told apart by the Task's code and reason: reprocess with claimrejected, shortfall with partialpayment, cancel. A reprocess goes on 36 and is acknowledged on 37; a cancel goes on PC01 and is done on PC02. Both carry the input intimationNumber. A supporting document is mandatory on a reprocess.

API call[`/v1/task/submit`API reference](/docs/nhcx/v1/api/task/endpoints/task-v1-task-submit)

Callback[`/v1/task/on_submit`API reference](/docs/nhcx/v1/api/task/endpoints/task-webhook-v1-task-on-submit)

### PMJAY

The following use cases govern the Pradhan Mantri Jan Arogya Yojana (AB PM-JAY) cashless lifecycle as detailed in the official NHA PMJAY Handbook. They follow strict Standard Treatment Guidelines (STG), mandatory biometrics, package rules, and Turnaround Time (TAT) auto-approvals.

D1Fetch the insurance plan

Downloads the scheme's setup for this hospital: the specialities and packages it may offer, their rates, and the documents and forms each one needs. The file is large, so keep a copy and refresh it weekly or whenever the scheme announces a change.

- **FHIR Reference:** [Insurance Plan Request, D1](/docs/nhcx/v1/reference/fhir/insurance-plan-request#d1-fetch-the-insurance-plan-pmjay)

Keyed on provider id, policy code and participant id. The answer is the scheme configuration for this hospital: specialities, packages, rates, Claim-Condition flags, mandatory documents and questionnaires. Over twenty megabytes; store it queryable, version it, refresh weekly and on any policychange communication.

API call[`/v1/insuranceplan/request`API reference](/docs/nhcx/v1/api/insurance-plan/endpoints/insurance-plan-v1-insuranceplan-request)

Callback[`/v1/insuranceplan/on_request`API reference](/docs/nhcx/v1/api/insurance-plan/endpoints/insurance-plan-webhook-v1-insuranceplan-on-request)

D2Authenticate the beneficiary

Confirms the patient is who they say, by fingerprint, iris or face scan. A successful check gives a pass valid for thirty minutes, used on the cover check and the approval request. A fresh one is needed for the claim. If a scan is impossible, a signed consent form can stand in, except on repeating treatments.

Fingerprint, iris or face; all three must be built. Success yields a user token valid thirty minutes that rides on the eligibility check and the pre-authorisation; a fresh one rides on the claim. Where biometrics are impossible, a signed exemption consent and the matching questionnaire stand in, except on a cyclic case.

**What information goes in and out**

- **It carries:** the patient's ABHA number and the method used to check them.
- **You get back:** a token that the later requests for this patient carry.

API callABHA biometric auth init and verify (not NHCX)

CallbackNone

D3Check coverage eligibility

Shows how much cover is left and what the chosen package needs attached. Register the patient only after cover is confirmed, and check again whenever treatment is added.

- **FHIR Reference:** [Coverage Eligibility Request, D3](/docs/nhcx/v1/reference/fhir/coverage-eligibility-request#d3-check-coverage-eligibility-pmjay)

Validation after registration returns the wallet, one benefit entry per wallet with allowed and used. Benefits and auth-requirements before a pre-authorisation return what the package needs attached. Register only after coverage is validated, and validate again every time treatment is added.

API call[`/v1/coverageeligibility/check`API reference](/docs/nhcx/v1/api/eligibility/endpoints/eligibility-v1-coverageeligibility-check)

Callback[`/v1/coverageeligibility/on_check`API reference](/docs/nhcx/v1/api/eligibility/endpoints/eligibility-webhook-v1-coverageeligibility-on-check)

D4Submit pre-authorisation

Asks the scheme for approval, no earlier than one day before admission. It includes the biometric pass or consent, the documents asked for, the treatment guideline form for each package, and the registration and admission dates. It is approved automatically only when it is the first request for the case and every package allows it.

- **Workflow ID:** [`12`](/docs/nhcx/v1/concepts/workflow-codes?code=12#every-workflow-code)
- **FHIR Reference:** [Preauthorisation Request, D4](/docs/nhcx/v1/reference/fhir/preauthorisation-request#d4-submit-pre-authorisation-pmjay)

Sent not more than one day before admission. It carries:

- the biometric token or the consent response
- the documents the auth-requirements answer asked for
- the STG questionnaire for each package
- the registration and admission dates as supporting info

Auto-approved only if it is the first pre-authorisation for the case and every package allows it.

API call[`/v1/preauth/submit`API reference](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-submit)

Callback[`/v1/preauth/on_submit`API reference](/docs/nhcx/v1/api/preauth/endpoints/preauth-webhook-v1-preauth-on-submit)

D5Resubmit pre-authorisation

Changes an approved or rejected request to a different amount or package. The new request replaces all earlier ones.

- **Workflow ID:** [`121`](/docs/nhcx/v1/concepts/workflow-codes?code=121#every-workflow-code)
- **FHIR Reference:** [Preauthorisation Request, D5](/docs/nhcx/v1/reference/fhir/preauthorisation-request#d5-resubmit-pre-authorisation-pmjay)

Revises an approved or rejected case for a different amount or package. Nullifies every earlier instance; the payer treats it as the new base request.

API call[`/v1/preauth/submit`API reference](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-submit)

Callback[`/v1/preauth/on_submit`API reference](/docs/nhcx/v1/api/preauth/endpoints/preauth-webhook-v1-preauth-on-submit)

D6Raise an enhancement

Asks for more on an approved case. It can be raised as often as needed until discharge, one at a time, and only for packages that allow it. Questions about it arrive on the same case and are answered there.

- **Workflow ID:** [`13`](/docs/nhcx/v1/concepts/workflow-codes?code=13#every-workflow-code), [`131`](/docs/nhcx/v1/concepts/workflow-codes?code=131#every-workflow-code), [`241`](/docs/nhcx/v1/concepts/workflow-codes?code=241#every-workflow-code)
- **FHIR Reference:** [Preauthorisation Enhancement, D6](/docs/nhcx/v1/reference/fhir/preauthorisation-enhancement#d6-raise-an-enhancement-pmjay)

Adds to an approved pre-authorisation, as many times as needed until discharge, one at a time, and only for packages whose plan flag allows it. The bundle carries the approved items and the ones now sought. A query on it arrives as a ClaimResponse on 241, on the case's own thread, and is answered by a fresh submit on 131.

API call[`/v1/preauth/submit`API reference](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-submit)

Callback[`/v1/preauth/on_submit`API reference](/docs/nhcx/v1/api/preauth/endpoints/preauth-webhook-v1-preauth-on-submit)

D7Answer a pre-authorisation query

Replies to a question the scheme raised on an approval request. The answer goes on the same case. Sending it as a new request would open a second case by mistake.

- **Workflow ID:** [`19`](/docs/nhcx/v1/concepts/workflow-codes?code=19#every-workflow-code)
- **FHIR Reference:** [Preauthorisation Query and Answer, D7](/docs/nhcx/v1/reference/fhir/preauthorisation-query-and-answer#d7-answer-a-pre-authorisation-query-pmjay)

The query arrived as a ClaimResponse on 24, on the case's own thread, with the question in the item adjudication, not on the communication API. Answer with a fresh submit of the same bundle shape on this code, never as a new 12, which opens a second case.

API call[`/v1/preauth/submit`API reference](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-submit)

Callback[`/v1/preauth/on_submit`API reference](/docs/nhcx/v1/api/preauth/endpoints/preauth-webhook-v1-preauth-on-submit)

D8Cancel pre-authorisation

Withdraws an approval request, with a reason such as a change in the treatment plan or the patient's request. Allowed any time before the claim is sent.

- **Workflow ID:** [`PC01`](/docs/nhcx/v1/concepts/workflow-codes?code=PC01#every-workflow-code)
- **FHIR Reference:** [Cancel, Reprocess and Shortfall, D8](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall#d8-cancel-pre-authorisation-pmjay)

A Task with code cancel, the case number as input and one of seven reasons: treatmentplanchanged, patientrequest, financialconstraints, alternativetreatment, duplicateclaim, administrativeerror, other. Allowed at any point until the claim is raised.

API call[`/v1/task/submit`API reference](/docs/nhcx/v1/api/task/endpoints/task-v1-task-submit)

Callback[`/v1/task/on_submit`API reference](/docs/nhcx/v1/api/task/endpoints/task-webhook-v1-task-on-submit)

D9Submit claim

Claims payment after discharge. There is no separate discharge message: the claim itself records the discharge, with its dates, how the patient left, and a fresh biometric pass. The amount cannot be more than what was approved.

- **Workflow ID:** [`15`](/docs/nhcx/v1/concepts/workflow-codes?code=15#every-workflow-code)
- **FHIR Reference:** [Claim Request, D9](/docs/nhcx/v1/reference/fhir/claim-request#d9-submit-claim-pmjay)

There is no discharge submission: the claim asserts the discharge and carries its details. It carries:

- four dates
- the discharge type under category DIS, with the stage as its value
- a fresh biometric token
- on a LAMA or DAMA discharge before or during surgery, LM100 as the single procedure in place of the approved items

The amount may not exceed what was approved.

API call[`/v1/claim/submit`API reference](/docs/nhcx/v1/api/claim/endpoints/claim-v1-claim-submit)

Callback[`/v1/claim/on_submit`API reference](/docs/nhcx/v1/api/claim/endpoints/claim-webhook-v1-claim-on-submit)

D10Answer a claim query

Replies to a question the scheme raised on a claim, on the same case. The final decision follows, often with a note on why less than the claimed amount was allowed.

- **Workflow ID:** [`161`](/docs/nhcx/v1/concepts/workflow-codes?code=161#every-workflow-code)
- **FHIR Reference:** [Claim Query and Answer, D10](/docs/nhcx/v1/reference/fhir/claim-query-and-answer#d10-answer-a-claim-query-pmjay)

As D7, on the claim endpoint: the query is a ClaimResponse on 27, the answer a fresh submit on 161. The sandbox refuses 151, 19 and 16 with PAYR-1321. The final adjudication then arrives with outcome complete and, often, a deductible adjudication naming why the eligible amount is less than the claimed one.

API call[`/v1/claim/submit`API reference](/docs/nhcx/v1/api/claim/endpoints/claim-v1-claim-submit)

Callback[`/v1/claim/on_submit`API reference](/docs/nhcx/v1/api/claim/endpoints/claim-webhook-v1-claim-on-submit)

D11Reprocess a rejected claim

Appeals a rejected claim, with a supporting document and no amount. Raise it as soon as the rejection arrives. It can be done only once, and the review committee's decision is final.

- **Workflow ID:** [`36`](/docs/nhcx/v1/concepts/workflow-codes?code=36#every-workflow-code)
- **FHIR Reference:** [Cancel, Reprocess and Shortfall, D11](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall#d11-reprocess-a-rejected-claim-pmjay)

An appeal, not a resubmission: a Task with code reprocess and reason claimrejected, a supporting document attached, no amount. Raise it the moment the rejection arrives. Once only; the Claim Review Committee is final.

API call[`/v1/task/submit`API reference](/docs/nhcx/v1/api/task/endpoints/task-v1-task-submit)

Callback[`/v1/task/on_submit`API reference](/docs/nhcx/v1/api/task/endpoints/task-webhook-v1-task-on-submit)

D12Claim a shortfall

Asks for the rest of a claim that was paid in part. Allowed only after the final payment notice has arrived and been acknowledged. It can be done only once, and not after an appeal.

- **Workflow ID:** [`36`](/docs/nhcx/v1/concepts/workflow-codes?code=36#every-workflow-code)
- **FHIR Reference:** [Cancel, Reprocess and Shortfall, D12](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall#d12-claim-a-shortfall-pmjay)

The same Task with reason partialpayment and an amount capped at the difference, allowed only after payment notice 33 has arrived and been acknowledged with 17. Once only, and never after a reprocess.

API call[`/v1/task/submit`API reference](/docs/nhcx/v1/api/task/endpoints/task-v1-task-submit)

Callback[`/v1/task/on_submit`API reference](/docs/nhcx/v1/api/task/endpoints/task-webhook-v1-task-on-submit)

D13Acknowledge the payment notice

Up to three notices arrive: when payment starts, when the bank processes it, and when it settles. They show what was paid and what was deducted as tax. The last one carries the bank's transaction reference, so keep it for any dispute.

- **Workflow ID:** [`17`](/docs/nhcx/v1/concepts/workflow-codes?code=17#every-workflow-code)
- **FHIR Reference:** [Payment Notice and Acknowledgement, D13](/docs/nhcx/v1/reference/fhir/payment-notice-and-acknowledgement#d13-acknowledge-the-payment-notice-pmjay)

Three notices may arrive: 30 when the transfer is initiated, 31 when the bank processes it, 33 when it settles with the UTR. The reconciliation splits the amount into what was paid and what was deducted as tax. Keep the UTR; it is the reference for any dispute.

API call[`/v1/paymentnotice/on_request`API reference](/docs/nhcx/v1/api/payment-notice/endpoints/payment-notice-v1-paymentnotice-on-request)

Callback[`/v1/paymentnotice/request`API reference](/docs/nhcx/v1/api/payment-notice/endpoints/payment-notice-webhook-v1-paymentnotice-request)

### Payer

The following use cases are implemented by Payer participants (Insurance Companies and Third Party Administrators) to respond to provider inquiries, adjudicate claims, raise queries, and settle payments.

C1Link ABHA with policy

Links a patient's ABHA number, mobile number and member ID to their policy when the policy is created. This is what lets a hospital find the policy later.

Tie the ABHA number, mobile and member id to the policy's products at policy creation, naming the payer and the processor. This is what makes A2 answer.

**What information goes in and out**

- **It carries:** the patient's ABHA number, the policy number, and the insurer the policy belongs to.

API call[`/participant/link/abha/policy`API reference](/docs/nhcx/v1/api/registry/endpoints/registry-participant-link-abha-policy)

CallbackNone

C2De-link ABHA from policy

Removes that link. Only the insurer or claims processor named on the link can do this.

Undo C1. Only the party named as payer or processor on the link may do this.

**What information goes in and out**

- **It carries:** the patient's ABHA number and the policy number to unlink.

API call[`/participant/delink/abha/policy`API reference](/docs/nhcx/v1/api/registry/endpoints/registry-participant-delink-abha-policy)

CallbackNone

C3Respond to coverage eligibility

Answers a hospital's cover check with the patient's policy and cover details. An insurer can also ask the exchange to pass the request on to another insurer.

- **FHIR Reference:** [Coverage Eligibility Response, C3](/docs/nhcx/v1/reference/fhir/coverage-eligibility-response#c3-respond-to-coverage-eligibility-payer)

The eligibility and plan details for the beneficiary asked about. A payer may instead answer with a forward instruction, asking the exchange to pass the request to another payer.

API call[`/v1/coverageeligibility/on_check`API reference](/docs/nhcx/v1/api/eligibility/endpoints/eligibility-v1-coverageeligibility-on-check)

Callback[`/v1/coverageeligibility/check`API reference](/docs/nhcx/v1/api/eligibility/endpoints/eligibility-webhook-v1-coverageeligibility-check)

C4Respond to insurance plan request

Sends the plan's details to the hospital: covered treatments, rates and required documents. Under PM-JAY this file can be very large.

- **FHIR Reference:** [Insurance Plan Response Overview, C4](/docs/nhcx/v1/reference/fhir/insurance-plan-response-overview#c4-respond-to-insurance-plan-request-payer)

The plan as a benefit structure. Under PMJAY this is the scheme configuration for one hospital and can exceed twenty megabytes.

API call[`/v1/insuranceplan/on_request`API reference](/docs/nhcx/v1/api/insurance-plan/endpoints/insurance-plan-v1-insuranceplan-on-request)

Callback[`/v1/insuranceplan/request`API reference](/docs/nhcx/v1/api/insurance-plan/endpoints/insurance-plan-webhook-v1-insuranceplan-request)

C5Respond to pre-authorisation

Answers an approval request. The first reply confirms receipt and gives the case a reference number. The decision follows later: an approval, a rejection, or a question for the hospital.

- **Workflow ID:** [`20`](/docs/nhcx/v1/concepts/workflow-codes?code=20#every-workflow-code), [`21`](/docs/nhcx/v1/concepts/workflow-codes?code=21#every-workflow-code), [`23`](/docs/nhcx/v1/concepts/workflow-codes?code=23#every-workflow-code), [`24`](/docs/nhcx/v1/concepts/workflow-codes?code=24#every-workflow-code), [`22`](/docs/nhcx/v1/concepts/workflow-codes?code=22#every-workflow-code), [`231`](/docs/nhcx/v1/concepts/workflow-codes?code=231#every-workflow-code), [`241`](/docs/nhcx/v1/concepts/workflow-codes?code=241#every-workflow-code)
- **FHIR Reference:** [Preauthorisation Response, C5](/docs/nhcx/v1/reference/fhir/preauthorisation-response#c5-respond-to-pre-authorisation-payer)

The adjudicated pre-authorisation. The acknowledgement on 20 travels as response.partial and carries the payer's own case number; the decisions travel as response.complete. Read outcome and the adjudication amounts together: complete covers approval and denial alike. Under PMJAY a query is this ClaimResponse on 24 or 241, on the case's own thread.

API call[`/v1/preauth/on_submit`API reference](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-on-submit)

Callback[`/v1/preauth/submit`API reference](/docs/nhcx/v1/api/preauth/endpoints/preauth-webhook-v1-preauth-submit)

C6Raise a communication

Sends a message about a case, such as a request for documents, a warning that a time limit has passed, a grievance or a policy change. PM-JAY does not use this for questions; it asks them on the case itself.

- **Workflow ID:** [`24`](/docs/nhcx/v1/concepts/workflow-codes?code=24#every-workflow-code), [`241`](/docs/nhcx/v1/concepts/workflow-codes?code=241#every-workflow-code), [`27`](/docs/nhcx/v1/concepts/workflow-codes?code=27#every-workflow-code), [`N02`](/docs/nhcx/v1/concepts/workflow-codes?code=N02#every-workflow-code)
- **FHIR Reference:** [Communication, C6](/docs/nhcx/v1/reference/fhir/communication#c6-raise-a-communication-payer)

A message about a case, typed by its reason code: additionalinfo, tatquery for a turnaround breach, grievance, walletupdate, policychange, claimArbitration. A generic or IRDAI payer raises its document queries here, as a CommunicationRequest task bundle carrying 24, 241 or 27. It takes the answer as a Communication task bundle on on\_request, echoing the correlation id and workflow id. PMJAY does not use it for queries; its query is the ClaimResponse on the case's own thread.

API call[`/v1/communication/request`API reference](/docs/nhcx/v1/api/communication/endpoints/communication-v1-communication-request)

Callback[`/v1/communication/on_request`API reference](/docs/nhcx/v1/api/communication/endpoints/communication-webhook-v1-communication-on-request)

C7Respond to claim

Decides a claim item by item, showing any deduction and why. The first reply confirms receipt and gives the reference number.

- **Workflow ID:** [`25`](/docs/nhcx/v1/concepts/workflow-codes?code=25#every-workflow-code), [`26`](/docs/nhcx/v1/concepts/workflow-codes?code=26#every-workflow-code), [`27`](/docs/nhcx/v1/concepts/workflow-codes?code=27#every-workflow-code), [`28`](/docs/nhcx/v1/concepts/workflow-codes?code=28#every-workflow-code), [`29`](/docs/nhcx/v1/concepts/workflow-codes?code=29#every-workflow-code), [`291`](/docs/nhcx/v1/concepts/workflow-codes?code=291#every-workflow-code)
- **FHIR Reference:** [Claim Response, C7](/docs/nhcx/v1/reference/fhir/claim-response#c7-respond-to-claim-payer)

The adjudicated claim, item by item, with any deduction and its reason. The acknowledgement on 25 travels as response.partial with the payer's case number. Under PMJAY a query is this ClaimResponse on 27, answered by a fresh submit on 161.

API call[`/v1/claim/on_submit`API reference](/docs/nhcx/v1/api/claim/endpoints/claim-v1-claim-on-submit)

Callback[`/v1/claim/submit`API reference](/docs/nhcx/v1/api/claim/endpoints/claim-webhook-v1-claim-submit)

C8Respond to search

Returns the claims that match a search.

- **FHIR Reference:** [Status and Search, C8](/docs/nhcx/v1/reference/fhir/status-and-search#c8-respond-to-search-payer)

The ClaimResponse objects matching the criteria asked for.

API call[`/v1/search/on_submit`API reference](/docs/nhcx/v1/api/status/endpoints/status-v1-search-on-submit)

Callback[`/v1/search/submit`API reference](/docs/nhcx/v1/api/status/endpoints/status-webhook-v1-search-submit)

C9Send payment notice

Tells the hospital about a payment, itemised into what was approved, what was claimed, and any tax or recovery deducted. The final notice carries the bank's transaction reference.

- **Workflow ID:** [`30`](/docs/nhcx/v1/concepts/workflow-codes?code=30#every-workflow-code), [`31`](/docs/nhcx/v1/concepts/workflow-codes?code=31#every-workflow-code), [`33`](/docs/nhcx/v1/concepts/workflow-codes?code=33#every-workflow-code)
- **FHIR Reference:** [Payment Notice and Acknowledgement, C9](/docs/nhcx/v1/reference/fhir/payment-notice-and-acknowledgement#c9-send-payment-notice-payer)

The money, on a new thread of its own, with the reconciliation itemised by type: approved, claimed, tds, servicetax, advance, recovered, penality. The bank's UTR rides on the settled notice.

API call[`/v1/paymentnotice/request`API reference](/docs/nhcx/v1/api/payment-notice/endpoints/payment-notice-v1-paymentnotice-request)

Callback[`/v1/paymentnotice/on_request`API reference](/docs/nhcx/v1/api/payment-notice/endpoints/payment-notice-webhook-v1-paymentnotice-on-request)

C10Respond to a Task

Answers an appeal, a request for the rest of a part-paid claim, or a cancellation.

- **Workflow ID:** [`252`](/docs/nhcx/v1/concepts/workflow-codes?code=252#every-workflow-code), [`253`](/docs/nhcx/v1/concepts/workflow-codes?code=253#every-workflow-code), [`254`](/docs/nhcx/v1/concepts/workflow-codes?code=254#every-workflow-code), [`PC02`](/docs/nhcx/v1/concepts/workflow-codes?code=PC02#every-workflow-code), [`37`](/docs/nhcx/v1/concepts/workflow-codes?code=37#every-workflow-code)
- **FHIR Reference:** [Cancel, Reprocess and Shortfall, C10](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall#c10-respond-to-a-task-payer)

The answer to a reprocess, shortfall or cancel. A cancellation done is PC02 and carries the case's ClaimResponse in its output; a reprocess on 36 is acknowledged on 37 as arbitration. Both payers answer this way.

API call[`/v1/task/on_submit`API reference](/docs/nhcx/v1/api/task/endpoints/task-v1-task-on-submit)

Callback[`/v1/task/submit`API reference](/docs/nhcx/v1/api/task/endpoints/task-webhook-v1-task-submit)

### Patient app

Personal health record apps and beneficiary portals register on NHCX to receive real-time updates on a patient's claims and authorizations.

E1Subscribe to notifications

A patient's health app signs up when the patient logs in with their ABHA. The latest sign-up replaces any earlier one. The app can hear about claim progress, exchange maintenance, and changes to insurers and hospitals.

- **Workflow ID:** [`N01`](/docs/nhcx/v1/concepts/workflow-codes?code=N01#every-workflow-code), [`N02`](/docs/nhcx/v1/concepts/workflow-codes?code=N02#every-workflow-code), [`N03`](/docs/nhcx/v1/concepts/workflow-codes?code=N03#every-workflow-code), [`N04`](/docs/nhcx/v1/concepts/workflow-codes?code=N04#every-workflow-code)

A patient app subscribes when the beneficiary logs in with their ABHA, and the most recent subscription wins. Topics: workflow\_events for claim progress, network\_events for exchange maintenance, participant\_events for changes to payers and providers.

**What information goes in and out**

- **It carries:** the patient's ABHA number, the kinds of update the app wants, and the address the updates should be sent to.

API call[`/v1/notification/subscribe`API reference](/docs/nhcx/v1/api/other/endpoints/other-v1-notification-subscribe)

Callback[`/v1/notification/on_subscribe`API reference](/docs/nhcx/v1/api/other/endpoints/other-v1-notification-on-subscribe)


---

# PMJAY on NHCX

Ayushman Bharat Pradhan Mantri Jan Arogya Yojana, known as PMJAY, was launched on 23 September 2018. It is the largest health assurance scheme in the world, providing a health cover of Rs. 5 lakh per family per year for secondary and tertiary care hospitalisation to over 10.74 crore poor and vulnerable families, roughly 50 crore beneficiaries, forming the bottom 40 percent of the population. It is fully funded by government, with the cost of implementation shared between the Centre and the states.

Claim adjudication under PMJAY runs through three integrated systems: the Beneficiary Identification System (BIS), the Transaction Management System (TMS), and the Hospital Empanelment Module (HEM). The key decisions sit in TMS, taken at preauthorisation by the Preauthorisation Processing Doctor (PPD) and at settlement by the Claim Processing Doctor (CPD).

The previous chapters described how a claim moves between a Provider and a private insurer over NHCX. This chapter covers what changes when the Payer is PMJAY.

## The problem with a TMS-only workflow

PMJAY claims processing today depends on the TMS 2.0 Provider System, whether or not the hospital runs its own HMIS. That creates four difficulties.

- **Duplication of data entry.** The same case is keyed into the hospital HMIS and again into TMS, increasing administrative workload and the risk of errors.
- **Lack of interoperability.** Beneficiary, clinical and claims data cannot move cleanly between systems.
- **Single-system dependency.** Relying exclusively on one provider system limits scalability and operational flexibility.
- **Restricted innovation.** System constraints leave little room for hospitals and technology partners to build around the workflow.

## The change

A hospital running an ABDM-enabled HMIS integrated with NHCX can operate PMJAY workflows entirely within its own system, with no mandatory portal usage. Claims move directly from the hospital system to the payer system over the exchange.

- **No mandatory TMS dependency.** The PMJAY workflow lives inside the HMIS rather than beside it.
- **Single-source data capture.** PMJAY data is recorded once in the HMIS and reused for claims processing, removing the re-entry and reconciliation described above.
- **Choice of system.** Hospitals are no longer tied to one PMJAY processing system and can pick any ABDM-enabled HMIS.
- **Scale.** HMIS-based integration handles higher transaction volumes more reliably than a portal-based workflow.

## What this means for an empanelled hospital

**PMJAY becomes part of routine operations.** Cases are handled inside the hospital's normal workflow rather than as a separate portal-driven activity, and are no longer exposed to portal downtime, access constraints or concurrent user limits.

**Structured data enables automation.** Preauthorisation and claim processing can be automated, cutting cost and turnaround, reducing manual error and improving data quality, which is the basic requirement for any AI model and for fraud control.

**Audit and finance improve.** All PMJAY clinical and financial records sit within hospital systems, simplifying audits, internal reviews and compliance, and claims data flows natively into hospital billing and accounting.

**Training simplifies.** Staff learn one system instead of managing separate roles and workflows across HMIS and TMS.

## Where PMJAY differs from a private insurer integration

Once NHCX integration is complete, an integrator can send claims to any private insurer. PMJAY is a national assurance programme, so it carries scheme-specific requirements on top. The endpoints themselves do not change. Four things do.

**The InsurancePlan response carries the scheme configuration.** PMJAY uses the InsurancePlan FHIR bundle heavily. It is configured at hospital level and holds the available specialties, package costs, standard treatment guidelines, questionnaires and the mandatory documents required at preauthorisation and claim. This configuration drives most of what follows, so fetching and storing it correctly is a precondition rather than a convenience.

**Biometric authentication is mandatory.** The scheme requires biometric verification of the beneficiary at registration, during treatment and at discharge. This is an additional API, outside the NHCX set, that a PMJAY integrator must implement.

**Supporting information must be structured.** Sending scanned documents is not sufficient. Clinical information must travel in ABDM-defined structured Health Information Types.

**Document queries do not use the Communication API.** When the PMJAY payer wants more documents or clarification on a preauthorisation or claim, it queries the case itself. The provider answers on the same preauthorisation or claim endpoint with the same bundle, distinguished only by the workflow code. The Communication API is still used, but for other things. Telling a hospital a case has breached its turnaround time, passing on a grievance, or announcing a change to the beneficiary's wallet or to a package rate. Also asking for extra information outside a formal query, and acknowledging an arbitration request. A hospital system must still be able to receive it.

Set against the flows in the NHCX Use Cases chapter, the picture is:

- **Get Insurance Plan, Get Policy, Coverage Eligibility Check, Claim Submission, Payment Notice and Status Check** behave the same as on any NHCX integration.
- **Preauthorisation** behaves the same, except that mandatory biometric authentication of the beneficiary must be completed before it is submitted.
- **Communication Request** is not used for document queries, which travel on the preauthorisation and claim endpoints instead. It is used for turnaround-time alerts, grievances, wallet and policy updates, and arbitration acknowledgements. A private insurer does the opposite: its query is the Communication Request itself.

## PMJAY scheme rules

PMJAY runs on strict clinical and financial rules that a commercial insurer does not use. A hospital system has to follow them when it builds each request. In plain words:

- **Packages, not line items.** Every admission is paid as a fixed package covering the bed, nursing, consultations, procedures, medicines and standard follow-up.
- **Fully cashless.** A hospital may not charge the patient anything for a covered treatment.
- **Approval first.** Surgery in secondary and tertiary care needs a preauthorisation, and the claim must point to the approval.
- **Biometric checks.** The patient's fingerprint, iris or face is checked at registration, at preauthorisation, at every visit of a repeating treatment, and at discharge. These checks use ABDM's biometric service, not NHCX.
- **Every stay ends one of four ways.** The patient goes home, dies in hospital, leaves against medical advice, or is discharged against medical advice. The claim also records whether they left before, during or after surgery.
- **Leaving before surgery is finished.** If the patient leaves against advice before or during surgery, the surgical package is cancelled. The hospital is paid a daily rate for the days of the stay instead, set by the type of bed. If the patient leaves after surgery, the surgical package is paid.
- **Death in hospital.** The claim keeps the package for the care given, and must carry the time of death and a death summary.
- **Repeating treatments.** Dialysis and chemotherapy are approved as a block of sessions. Sessions must be at least 24 hours apart, each needs a biometric check, and only checked sessions are paid.
- **Procedures not on the list.** A surgery missing from the package list can be booked only for a planned admission, under the patient's specialty, on its own, and within the patient's remaining cover.

[Scheme rules the HMIS must implement](/docs/nhcx/v1/concepts/pmjay-use-cases#scheme-rules-the-hmis-must-implement), in PMJAY use cases, gives the codes, fields, tariffs and error codes behind each rule.

## The integrator journey

The route to a PMJAY integration runs in five stages.

1. **Get compliant for ABDM Milestone 1.** Request access to the sandbox APIs, integrate against them, complete functional testing and the security audit (WASA), give the HTC demo, and go live for ABDM M1.

2. **Register on the NHCX sandbox.** Register using the ABDM Client ID, generate a participant ID, create the public and private key pair, and work through the NHCX documentation until the API flows are properly understood.

3. **Build the integration.** Test the flows against the NHCX dummy payer, implement every use case API including biometric authentication and structured data exchange, and test all cases internally rather than only the happy path.

4. **Exit the sandbox.** Run the internal demo covering interoperability and FHIR bundle validation, give the PMJAY team demo, complete WASA and the HTC demo, and submit the NHCX sandbox exit form.

5. **Go live by mapping.** After the participant is created and configured in production, the hospital raises a ticket. It carries the existing PMJAY hospital ID, the HEM ID used in TMS, and the new NHCX participant ID. NHA's operations team maps the two by hand. That mapping is the switch: preauthorisations and claims raised before it finish their life in TMS, and everything raised after it goes through the HMIS. For a while a hospital is running both, so this step is planned rather than flipped.

Two practical notes. To begin the integration, the integrator shares the Participant ID, Client ID and Registry ID with the NHCX team for onboarding onto the PMJAY staging environment. The Registry ID is then used as the Provider ID on sandbox. On successful completion, the integrator receives production keys for NHCX, which also serve for processing private insurer claims.


---

# PMJAY use cases

```mermaid
flowchart TD
  D1[D1 Fetch the insurance plan and keep it fresh] --> R[Patient registers]
  R --> D2[D2 Biometric authentication]
  D2 --> D3[D3 Eligibility: validation]
  D3 --> D3b[D3 Eligibility: benefits and auth-requirements]
  D3b --> D4[D4 Submit preauthorisation]
  D4 --> Q{Payer answer}
  Q -- query --> D7[D7 Answer the query] --> Q
  Q -- approved --> TR[Treatment]
  TR --> E{Case needs more?}
  E -- yes --> D6[D6 Enhancement] --> Q
  E -- no --> D2b[D2 Biometric at discharge]
  D2b --> D9[D9 Submit claim with discharge details]
  D9 --> Q2{Payer answer}
  Q2 -- query --> D10[D10 Answer the query] --> Q2
  Q2 -- rejected --> D11[D11 Reprocess]
  Q2 -- approved --> D13[D13 Payment notice and acknowledgement]
  D13 -- paid short --> D12[D12 Claim the shortfall]
  D4 -. withdraw .-> D8[D8 Cancel]
  D4 -. revise .-> D5[D5 Resubmit]
```

The endpoints a PMJAY integration calls are the same ones listed in the NHCX Use Cases chapter. What changes is the behaviour around them: what must be fetched first, what must be proved before a request is accepted, how supporting information is packaged, and how a query is answered. The shared use cases apply unchanged, and so do Get Policy and Get Status.

The exchanges below are the D-series. Where a use case is distinguished by a workflow code rather than by a separate endpoint, that code is given with it. The scheme rules that change how a submission is built, for discharge, leaving against medical advice, death, cyclic and unspecified cases, are in [Scheme rules the HMIS must implement](#scheme-rules-the-hmis-must-implement) below. A PMJAY integration is as much about those rules as about the calls.

## Scheme setup and identity

### D1: fetch insurance plan

**API Called:** `/v1/insuranceplan/request` **Callback API:** `/v1/insuranceplan/on_request` **Payload:** encrypted TaskBundle on the request, InsurancePlanBundle on the response

The InsurancePlan is the structured representation of the policy under which a patient is covered. PMJAY is strictly package-based, with bundled costs for each service. Referencing the correct plan is what keeps the claim to admissible services, avoids rejections for non-compliance with scheme guidelines, and gives both sides an auditable record.

The request is keyed on Provider ID, Policy Code and Participant ID. The response is scoped to that provider. It returns the specialties relevant to it, the covered services and their limits, and the mandatory documents for both preauthorisation and claim, at policy level and per benefit. It also carries the Standard Treatment Guidelines and clinical protocols, and the policy conditions, exclusions and renewal information.

**How the plan is built.** Each specialty holds packages. Each package has a rate. Over and above the rate, the plan can attach add-ons that the payer allows for that package: an implant, a higher-cost bed category (called stratification), a high-end medicine or investigation. The plan also carries flags per package that change how a claim is built: whether it is an unspecified procedure, a cyclic one, or one that applies to a LAMA or DAMA discharge. The scheme rules section below explains each.

**Size and storage.** The plan object sometimes exceeds 20 MB. The system must accept a payload that large and store it in a structured, queryable form linked to the policy record.

**Freshness and versioning.** Refresh the plan regularly, and immediately whenever a policy is renewed or amended. The FRD says weekly; the scenario sheet says once in fifteen days. Version control on tariffs and packages is not optional: an outdated tariff version causes a rate mismatch and automatic claim rejection on suspicion of tampering. Keep audit logs of every fetch, refresh and version update, and of the version used in each preauth or claim.

**Driving the forms.** The stored plan populates the preauth and claim forms with benefits and limits, and supplies the STG checklist, which must be rendered dynamically against the treatment plan selected. The questionnaire URL received in the plan is what gets sent back in the questionnaire response.

### D2: biometric authentication of the beneficiary

```mermaid
sequenceDiagram
  box Provider side
    participant H as Hospital system
  end
  box ABDM
    participant A as ABHA biometric service
  end
  box Payer side
    participant Y as PMJAY payer
  end
  H->>A: auth init, fingerprint, iris or face
  A-->>H: transaction id
  H->>A: auth verify with the captured biometric
  A-->>H: user token valid 30 minutes, plus refresh token
  H->>Y: eligibility and preauthorisation, token in the header
  Note over H: refresh before 30 minutes, else authenticate again
  H->>A: fresh authentication at discharge
  H->>Y: claim, discharge token in the header
```

**API Called:** ABHA biometric auth init, then auth verify, with a refresh token endpoint **Callback API:** none **Note:** this is not an NHCX API. It was built specifically for the PMJAY payer.

The scheme mandates biometric verification of the beneficiary at registration, during treatment and at discharge, to establish physical presence.

**All three methods must be built.** Fingerprint, iris and face authentication are each mandatory to implement, because any of them may be the one that works for a given patient. A preauthorisation raised with a fingerprint can be followed by a claim raised with face authentication; the methods do not have to match. Fingerprint and iris follow an init-then-verify pair. Face authentication is a different flow. Initiate, show the patient a QR code to scan in the ABHA app, and poll until the capture is complete. Then verify with the Aadhaar number encrypted using the public key the portal supplies.

On success the system receives a User Token, which must be passed as a header on every subsequent PMJAY claim event that requires proof of presence, including the coverage eligibility check and the preauthorisation submission. The payer validates this token before treating the request as legitimate. Discharge requires a fresh authentication, and that token is passed on the claim submission.

**Token lifetime.** The User Token is valid for 30 minutes. Systems must refresh it automatically for the duration of a transaction cycle, and if it expires, start a fresh biometric authentication.

**Applicability.** This applies only to beneficiaries whose ABHA number is linked to their PMJAY card. Beneficiaries without that linkage follow the existing PMJAY-approved KYC protocols.

**Exemption.** Where biometric or Aadhaar authentication is not feasible, the provider obtains an Aadhaar exemption consent document signed by both the patient and a hospital representative. Store it digitally and link it to the beneficiary record. A preauthorisation or claim may then be raised on the consent form instead. The one exception is a cyclic procedure, where live biometrics are required at every step. Biometric authentication or a valid exemption is mandatory before a claim can be submitted.

## Eligibility

### D3: check coverage eligibility

**API Called:** `/v1/coverageeligibility/check` **Callback API:** `/v1/coverageeligibility/on_check` **Payload:** encrypted CoverageEligibilityRequestBundle

The check verifies a patient's eligibility and available benefits before registration or treatment. It is served with four purposes, and the purpose determines what comes back.

- **Validation.** Confirms the specified coverages are in force, and returns the wallet balance. The benefit component carries one entry per wallet applicable to the beneficiary, with the allowed balance and the amount consumed. Called after registration.
- **Discovery.** Asks the insurer to report any coverages it knows of beyond those specified, giving the list of all active coverages for the beneficiary.
- **Benefits.** Returns the plan benefits, and optionally the benefits already consumed, for the listed or discovered coverages. Called before raising a preauthorisation or enhancement.
- **Auth requirements.** Returns the prior authorisation requirements for the given categories of service or billing codes, procedure by procedure, and the documents needed at each stage. This is where the documents and questionnaires mandatory for preauthorisation come from. Called on the preauthorisation page before submission.

Validation, discovery and benefits require the Beneficiary ID, Coverage or Plan Code, Payer ID and Provider ID. Auth requirements and benefits additionally require the procedure or package codes.

Register the patient only after coverage is validated, and alert both provider and patient where coverage is insufficient, including the case where a family's shared limit is exhausted. Call this check again, as a validation, every time an additional treatment is added, so the limit is confirmed before a preauthorisation goes out.

## Preauthorisation

All five preauthorisation exchanges share the same endpoints and the same bundle structure. The workflow code is what distinguishes them. Each follow-up, whether a query answer, an enhancement or a resubmission, is a new request carrying the original reference and a fresh correlation ID.

**API Called:** `/v1/preauth/submit` **Callback API:** `/v1/preauth/on_submit` **Payload:** encrypted ClaimBundle, answered with a ClaimResponseBundle

The documents and questionnaires required come from the coverage eligibility response with purpose auth-requirements. Procedure components must match the values returned by the InsurancePlan. The preauthorisation amount may not exceed the balance remaining on the beneficiary's coverage. Two dates are mandatory, each sent as a timing (date or period) or as a string value, adhering to NRCeS standards.

| Field             | Category | Code   | Display                         |
| ----------------- | -------- | ------ | ------------------------------- |
| Registration date | `OTH`    | `EDT`  | EncounterDateTime               |
| Admission date    | `ONS`    | `ADDD` | Admission date - Discharge date |

See the note under D9 on where these codes come from and where the source documents disagree.

A preauthorisation cannot be raised more than one day in advance, and D2 must be completed before submission.

### D4: submit preauthorisation

**Workflow ID:** 12

The first preauthorisation for a case. It is auto-approved only if it is the first preauth for that case and every requested procedure is eligible for auto-approval. Separately, where the policy is eligible for turnaround-time approval and no action is taken within the defined window, the case is approved automatically. Everything else is adjudicated manually by the payer.

### D5: resubmit preauthorisation

**Workflow ID:** 121

Raised once a base preauth already exists, for example to revise an approved or rejected case for a higher amount or a different package. A resubmission nullifies all previous instances, and the payer treats it as the new base request.

### D6: raise enhancement

**Workflow ID:** 13, with 131 for a response to an enhancement query

Raised against an already approved preauth to extend a procedure or add new ones. Unlimited enhancements are allowed until discharge, within the limit, but each can only be sent after the previous request has closed. Check the plan's rules for the package before raising one. The bundle carries the enhancement workflow ID, the already approved treatments, and the treatments now sought.

### D7: respond to preauthorisation query

**Workflow ID:** 19

A query arrives in the item-wise adjudication field of the preauth response bundle. The provider reads it and answers with a preauth query response, not a resubmission. The bundle structure is unchanged.

### D8: cancel preauthorisation

**Workflow ID:** PC01 **Payload:** Task bundle

Cancels the whole preauthorisation. It can be raised at any point until the claim is raised, against an active preauth or one still pending decision at the payer end. The Task carries the code `cancel`, the case number as its input (the FRD calls this the intimation number, the scenario sheet the claim number), a reason, and any remarks in the disposition.

Reasons the payer recognises: `treatmentplanchanged`, `patientrequest`, `financialconstraints`, `alternativetreatment`, `duplicateclaim`, `administrativeerror`, and `other` with a free-text explanation.

## Claim

The claim exchanges share endpoints and bundle structure in the same way.

**API Called:** `/v1/claim/submit` **Callback API:** `/v1/claim/on_submit` **Payload:** encrypted ClaimBundle, answered with a ClaimResponseBundle

The documents and questionnaires for the claim come from the InsurancePlan response. Coverage eligibility with purpose auth-requirements supplies only those needed at preauthorisation; the remainder are mandatory at claim. The claim amount may not exceed the preauthorisation's approved amount. A claim cannot be cancelled.

### D9: submit claim

```mermaid
flowchart TD
  A[Patient leaves] --> B{How?}
  B -- went home --> DTH[DTH]
  B -- died --> DTM[DTM, plus the death date]
  B -- left without telling --> LAMA[LAMA]
  B -- left, signed an undertaking --> DAMA[DAMA]
  LAMA --> S{At what stage?}
  DAMA --> S
  S -- before surgery --> LM["LM100 only, quantity = days admitted, preauthorised items voided"]
  S -- after surgery --> ST[Surgery items stand, no LM100]
```

**Workflow ID:** 15

**PMJAY has no separate discharge workflow.** Raising a claim implicitly asserts that the patient has been discharged, so discharge details form part of the claim request itself. Once the preauthorisation is approved and treatment is complete, the patient is discharged and the claim submitted, carrying a fresh D2 token.

Four dates and the discharge status are mandatory. Each date is sent as a timing (date or period) or as a string value, adhering to NRCeS standards.

| Field             | Category                          | Code                              | Display                         |
| ----------------- | --------------------------------- | --------------------------------- | ------------------------------- |
| Registration date | `OTH`                             | `EDT`                             | EncounterDateTime               |
| Admission date    | `ONS`                             | `ADDD`                            | Admission date - Discharge date |
| Surgery date      | `ONS`, or `SURD` in every sample  | `PSP`, or `ADDD` in every sample  | PatientSurgeryPerformed         |
| Discharge date    | `ONS`, or `DSCHD` in every sample | `DSDE`, or `ADDD` in every sample | Discharge Date                  |

The discharge status itself goes under category `DIS`, with the code carrying the type of discharge. All four types from the hospital workflow are represented. There is no "referred to another hospital" type; a patient is discharged as one of these four before being admitted elsewhere.

| Code   | Display             | Discharge type                                                  |
| ------ | ------------------- | --------------------------------------------------------------- |
| `DTH`  | DischargeToHome     | Normal discharge                                                |
| `DTM`  | DischargetoMortuary | Death                                                           |
| `LAMA` | Discharge with LAMA | Left against medical advice, without telling the hospital       |
| `DAMA` | Discharge with DAMA | Discharged against medical advice, having signed an undertaking |

The value against the `DIS` entry is not a date. It is a string carrying the discharge stage: **Before Surgery**, **During Surgery** or **After Surgery**. It is sent for medical cases as well as surgical ones. Each discharge type has a matching questionnaire in the plan (Death, Life, LAMA, DAMA), found by title.

A death is the one case that needs a fifth date. Where the discharge type is `DTM`, send the death date as an additional entry under category `ONS` with the same `DTM` code, alongside the four dates above.

**LAMA and DAMA claims carry a special procedure code.** Under LAMA or DAMA, procedure code `LM100` may be the only code the payer accepts on the claim. Every item approved on the earlier preauthorisation is disqualified and only the stay is paid. The `LM100` line carries the number of days admitted as its quantity, and a LAMA discharge also sends the bed category with its duration. `LM100` is never valid on a preauthorisation.

Which discharge stages trigger it is stated four ways across the sources: before surgery only, before or during, before or after, and after or during in the payer's own error message. Establish the rule with the payer before building; it decides whether an approved package is paid or voided.

**A note on the codes above.** These combinations are taken from the NHCX gateway validation messages, which reject a claim naming the exact category and code expected. The Functional Requirement Document gives a different set for three of these fields, listing the admission, surgery and discharge dates under categories `ADMD`, `SURD` and `DSCHD` with code `ADDD` throughout. Those three categories do not appear in the supporting info category value set. Confirm against the current NRCeS value sets before building.

Claims are adjudicated manually, approved or rejected case by case.

### D10: respond to claim query

**Workflow ID:** 161. The payer refuses 151, 19 and 16 with `PAYR-1321`.

As with D7, the provider answers a payer query with a claim query response using the same Claim Bundle structure.

### D11: reprocess a rejected claim

**API Called:** `/v1/task/submit` **Callback API:** `/v1/task/on_submit` **Workflow ID:** 36 **Payload:** Task bundle, with a supporting document attached

When a claim is rejected outright and the hospital disputes it, it asks for a re-evaluation. This is an appeal, not a resubmission: the claim itself is not sent again.

The Task carries the code `reprocess` and the reason `claimrejected`. It names the case by its claim number, which under PMJAY is the preauthorisation number the hospital generated. No amount is sent, because the whole claim is in dispute. A supporting document is mandatory; without one there is no ground for the appeal. It can be raised as soon as the rejection arrives, with no dependency on any payment notice.

The request goes to the Claim Review Committee, whose decision is final. A claim can be reprocessed once. The original claim number carries forward; no new case is created.

### D12: claim a shortfall (erroneous claim)

```mermaid
flowchart TD
  A[Claim adjudicated] --> B{Outcome}
  B -- rejected --> C["D11 Reprocess: Task, reason claimrejected, document attached, no amount"]
  B -- paid in full --> D[Done]
  B -- paid short --> E[Wait for payment notice 33]
  E --> F[Verify the money, send acknowledgement 17]
  F --> G["D12 Shortfall: Task, reason partialpayment, amount up to the difference"]
  C --> H[Claim Review Committee decides, and that is final]
  G --> H
```

**API Called:** `/v1/task/submit` **Callback API:** `/v1/task/on_submit` **Workflow ID:** 36 **Payload:** Task bundle, with a supporting document attached

When a claim is approved and paid, but for less than was claimed, the hospital can ask for the difference. This uses the same Task as a reprocess with one change: the reason is `partialpayment`, and an amount is sent.

The amount is capped at the shortfall. A claim raised for 10,000 and paid at 6,000 can ask for up to 4,000, with justification, and never more. The request can only be raised once the payment cycle is complete: after the payment notice with workflow 33 has arrived and the hospital has verified the money and sent its acknowledgement, code 17. As with a reprocess, it can be raised once, and a supporting document is mandatory.

The two mechanisms do not chain. If a reprocess results in a partial approval, no shortfall claim can follow, because the Committee's decision is final.

## Payment

### D13: acknowledge payment notice

**API Called:** `/v1/paymentnotice/on_request` **Callback API:** `/v1/paymentnotice/request` **Workflow ID:** 17

Once a claim is approved and payment made, the payer sends a payment notice, which the provider system must be able to accept and acknowledge. Three notices may arrive in sequence: 30 when the payer initiates the transfer, 31 when the bank processes it, and 33 when it settles and the UTR number is available. The notice gives a consolidated status. **Cleared** where the amount has been initiated, **Paid** where it has been received, **Rejected** where it was initiated but failed on a server issue, **Adjusted** where a balance is being adjusted. Payment reconciliation gives the breakup for the case, including TDS and other deductions. Keep the UTR; it is the reference for any later dispute.

## Scheme rules the HMIS must implement

The Pradhan Mantri Jan Arogya Yojana (PMJAY) operates under strict operational, clinical, and financial guidelines that diverge significantly from commercial, fee-for-service insurance exchanges. This chapter details the scheme-specific business rules, calculation models, and clinical workflows that a Hospital Management Information System (HMIS) must implement.

---

### Core Principles of PMJAY Adjudication

1. **Strictly Package-Based**: PMJAY does not reimburse fee-for-service line items. All admissions are governed by Health Benefit Packages (HBP) with bundled tariffs covering registration, bed charges, nursing, consultations, procedures, medicines, consumables, and standard post-discharge follow-up.
2. **100% Cashless Mandate**: Empanelled healthcare providers cannot collect out-of-pocket co-payments from beneficiaries for covered procedures (`adjudication.copay` = ₹0).
3. **Pre-Authorization Gating**: Pre-authorization is mandatory for all secondary and tertiary surgical interventions. Final claims must reference the approved pre-authorisation number (`preAuthRef`).
4. **Mandatory Biometric Verification**: Live biometric capture (Fingerprint, Iris, or Face) is required at registration/admission, pre-authorisation, every cyclic treatment visit, and discharge.

---

### Discharge Types and Stages

Under PMJAY, a hospital cannot record an open-ended "referral" or "transfer" discharge. Every patient episode must terminate in one of four standardized discharge types, qualified by the surgical timing stage:

| Discharge Type Code | Display                           | Criteria & Adjudication Rule                                                                   |
| ------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------- |
| `DTH`               | Discharge to Home                 | Patient successfully completes inpatient care. Standard package adjudication applies.          |
| `DTM`               | Discharge to Mortuary             | In-hospital mortality. Claim carries death date (`ONS`/`DTM`) and death summary questionnaire. |
| `LAMA`              | Left Against Medical Advice       | Patient absconds or departs against clinical counsel without formal documentation.             |
| `DAMA`              | Discharged Against Medical Advice | Patient or attendant executes an informed refusal undertaking.                                 |

#### The Discharge Stage Qualification

Every claim records the clinical timing stage under `supportingInfo` category `DIS` ("Discharge status"):

- `Before Surgery`
- `During Surgery`
- `After Surgery`

---

### Package LM100 and LAMA/DAMA Billing Rules

```mermaid
flowchart TD
    Discharge[LAMA or DAMA Discharge] --> StageCheck{Discharge Stage?}
    StageCheck -->|Before Surgery| BillLM100[Nullify Surgical Package<br/>Bill LM100 at Daily Per Diem Rate]
    StageCheck -->|During Surgery| BillLM100
    StageCheck -->|After Surgery| BillPackage[Bill Full Approved Surgical Package<br/>LM100 Prohibited]
```

When a patient departs under `LAMA` or `DAMA`, the scheme strictly prohibits billing the full surgical package if the surgical intervention was not completed:

#### Before or During Surgery

- **Nullification**: Submitting a LAMA/DAMA claim before or during surgery immediately **nullifies all prior approved surgical pre-authorisation packages**.
- **Item Code `LM100`**: The claim replaces all surgical line items with a single item: procedure code `LM100` (Conservative / Per Diem Inpatient Care).
- **Daily Quantity Multiplier & `LengthOfStay` Bound**: The quantity on `LM100` is set to the exact number of days the patient was admitted (`Discharge Date - Admission Date`). This quantity is strictly bounded by the `LengthOfStay` (Maximum Length of Stay) attribute declared in the scheme package master (`InsurancePlan`). Admitted days billed cannot exceed `LengthOfStay` without prior clinical justification; stays extending beyond standard procedure limits in ordinary admissions require an approved pre-authorisation enhancement request (workflow 13).
- **Stratification Tariffs**: Procedure `LM100` is stratified by bed tier in the PMJAY master: Routine Ward (₹1,800/day, `STRAT006a`), High Dependency Unit HDU (₹2,700/day, `STRAT006b`), ICU Without Ventilator (₹3,600/day, `STRAT006c`), and ICU With Ventilator (₹4,500/day, `STRAT006d`).
- **Error Safeguard**: Submitting a surgical package code alongside LAMA/DAMA before or during surgery triggers automated rejection with error `PAYR-1362`.
- **Pre-Auth Prohibition**: `LM100` is strictly a claim-time adjudication code. Submitting `LM100` in a pre-authorisation request triggers error `PAYR-1270`.

#### After Surgery

- If surgery was successfully performed and the patient subsequently leaves against medical advice during post-operative recovery:

  - The approved surgical package remains valid.
  - `LM100` is **not** used.
  - The discharge stage is recorded as `After Surgery`, and the hospital is reimbursed for the surgical package.

---

### In-Hospital Death Claims (`DTM`)

If a patient expires during hospitalisation:

1. The discharge code is set to `DTM` (Discharge to Mortuary).
2. The claim retains the package appropriate to the clinical management provided up to the point of death.
3. The claim **must** include the date and time of death under `supportingInfo` category `ONS` with code `DTM`. Omitting the death timestamp causes rejection with error `PAYR-1096`.
4. The hospital must complete and attach the PMJAY Death Summary Questionnaire defined in the InsurancePlan.

---

### Cyclic Procedures (Dialysis, Chemotherapy)

Cyclic treatments represent recurring therapy requiring multiple sessions under a single overarching pre-authorisation:

- **Plan Identification**: Packages flag cyclic eligibility with `CyclicProcedure = Y` and `MaximumCyclesAllowed` in the `InsurancePlan`.
- **Pre-Auth Booking**: Pre-authorisation is requested and approved for the entire block of sessions (e.g., 10 cycles).
- **The Rolling 24-Hour Rule**: Two cycles of the same procedure cannot occur within a **rolling 24-hour window** (measured strictly from biometric timestamp to biometric timestamp, not calendar days). Submitting cycles within 24 hours triggers rejection with error `PAYR-1369`.
- **Biometric Enforcement**: Live biometric capture is mandatory at pre-auth, at **every individual treatment visit**, and at final discharge.
- **Payment Settlement**: The claim is submitted once after all sessions conclude. Payment is released exclusively for sessions backed by a verified biometric capture. (E.g., 10 sessions approved, 8 biometric captures recorded = 8 sessions paid).
- **Clinical Mapping**: Each cycle is recorded under `supportingInfo` category `CD` (Clinical document) with code `TD` (Treatment detail), carrying exact start and end timestamps matching the biometric verification log.

---

### Unspecified Surgical and Medical Procedures

When a patient requires a clinically necessary surgical intervention not present in the PMJAY Health Benefit Package master:

1. **Strictly Planned**: Unspecified procedures are permitted **only for elective/planned admissions**; emergency cases cannot utilize unspecified package codes.

2. **Specialty Alignment**: Must be booked under the patient’s treating specialty.

3. **Coding Convention**:

   - In live PMJAY plans, the procedure code is constructed as the **Specialty Prefix + `U100`** (e.g., `SGU100` for General Surgery, `SMU100` for Oral & Maxillofacial Surgery).
   - Some earlier NHA documentation referenced `Specialty + 215` (e.g., `SG215`). Systems must echo the exact code returned in the hospital’s dynamic `InsurancePlan`.

4. **Free-Text Specification**: The procedure name, clinical description, and requested tariff are entered by the hospital staff rather than selected from fixed master lists.

5. **Wallet Validation**: The entered amount cannot exceed the beneficiary’s available wallet balance. HMIS systems must validate this balance server-side before submission.

6. **Standalone Requirement**: An unspecified procedure must be a solitary line item; it cannot be clubbed with standard packages, implants, or stratified ICU addons.

---

### Biometric Authentication and Aadhaar Exemption

The captures these rules call for, at registration, preauthorisation, every cyclic visit and discharge, are made through ABDM's biometric APIs, not over NHCX. Biometric Authentication, in Building a Provider, gives the calls: fingerprint and iris on one host, face on another, the user token they return and its refresh, the `K-547` device error, and the Aadhaar exemption consent and questionnaire that stand in where a capture is not possible.

## Structured data exchange

This requirement applies to every preauthorisation and claim bundle, D4 through D10, and is what separates a PMJAY submission from an ordinary one. The Task bundles in D8, D11 and D12 carry their document as a plain attachment instead.

Supporting clinical information travels through the `SupportingInfo` to `DocumentReference` resource. Inside `DocumentReference.content.attachment`, the `attachment.data` field carries a Base64-encoded FHIR Bundle holding the relevant structured resources, for example DiagnosticReport, DischargeSummary or WellnessRecord. This is the difference from an unstructured submission, where the same field would carry a Base64-encoded PDF or JPG. For structured submissions the content type is set to `application/json` or `application/fhir+json`.

The category code decides which of the two applies. Structured data uses a supporting info category among DIA, HDS, CD and INF, with the value sent as a reference. Unstructured data uses a category among POI, POA, DOB, DEF, FIR and ATT, with the value sent as an attachment. Questionnaire responses are configured under supporting info with category INF, code AT, and a reference value.

Each document is limited to 2 MB, against a whole-bundle maximum of 20 MB, and only one document can be linked per item, so multiple documents for a single item must be merged.

## Workflow codes

The full code list, provider-initiated and payer response, is in the Workflow Codes chapter. The codes are the same under PMJAY, and each D-series entry above carries the one that applies to it.

Three points are specific to PMJAY. Because the scheme does not use the Communication API for document queries, the query codes 19 and 161 travel on the preauthorisation and claim endpoints. That is what allows D7 and D10 to reuse the original bundle structure unchanged. The Communication API is still used, with its own reason codes, for turnaround-time alerts, grievances, wallet and policy changes, and arbitration acknowledgements, so a hospital system must still host it. And codes 14 and 141 for discharge have no counterpart here, because PMJAY folds discharge into the claim rather than treating it as a submission of its own.

## Error handling and validation

Envelope errors, receipts, retries and the error endpoint are the same as on any NHCX integration and are covered in [The JWE message format](/docs/nhcx/v1/getting-started/jwe-message-format). Two things are specific here. Every callback must accept the answer in two forms, decided by the `type` field. A sealed bundle when the payer processed the request, or a protocol response when it could not be opened or failed validation. And the PMJAY payer's own error codes, the `PAYR-12xx` set for preauthorisation and `PAYR-13xx` for claims, name the exact field or rule that failed; surface them to the user as they are.

## Before you build

Three things on the portal shorten the first week.

- **Sample bundles.** Twenty-two worked FHIR bundles, in eleven request-and-response pairs. They cover every eligibility purpose, preauthorisation with its query, enhancement and cancellation, claim with its query, and payment notice with its acknowledgement. One is an insurance plan response of 21 MB, which shows what the storage requirement means in practice.
- **Test cases.** A matrix from TC-ABHA-01 onward, each with preconditions, inputs and expected output. The scenario list beside it includes registration, wallet update, preauthorisation with implant, discharge in multiple modes, and the Claim Review Committee path.
- **The dummy payer.** Described in the NHCX Use Cases chapter, it answers the exchanges listed in the NHCX Use Cases chapter, which does not include the Task exchanges or biometrics.


---

# Workflow Codes

The address a message is sent to does not say which step of a claim it is. A new preauthorisation, a resubmission, an enhancement and an answer to a query all go to the same place, in the same kind of bundle. The workflow code in the message header is what tells them apart. Each code also comes with a status that says whether the message starts a request, answers one, or refuses it. The official Workflow Status Sheet is the authority, and new codes appear there first.

## Every workflow code

Search by code, name or status, and switch between the codes a provider sends, the codes a payer sends, every row of the Workflow Status Sheet, and the lettered families.

Search by code, name or status

Spellings are as published, such as `Initimation`, `Reimburstment` and `protocal`, so that searching for what you saw in a payload finds the row.

- `12`Preauth Request Initiatedrequest.initiated
- `121`Preauth Reprocess(Resubmission) Initimationrequest.initiated
- `13`Enhancement Request Initiatedrequest.initiated
- `131`Enhancement Query Ack Successresponse.partial
- `131`Enhancement Query Ack Failedresponse.error
- `131`Enhancement Query Response Submittedresponse.complete
- `18`Preauth Query Ack Successresponse.partial
- `18`Preauth Query Ack Failedresponse.error
- `19`Preauth Query Response Submittedresponse.complete
- `20`Preauth Ack Successresponse.partial
- `20`Preauth Ack Failedresponse.error
- `21`Preauth Request Approvedresponse.complete
- `22`Enhancement Request Approvedresponse.complete
- `23`Preauth Request Rejectedresponse.complete
- `231`Enhancement Denyresponse.complete
- `24`Preauth Request Queriedrequest.initiated
- `241`Enhancement Query Raiserequest.initiated
- `251`Preauth Reprocess Ackresponse.complete
- `41`Preauth Arbitration Intimationrequest.initiated
- `42`Preauth Arbitration Acknowledgementresponse.complete
- `PC01`Preauthorization Cancellationrequest.initiated
- `PC02`Preauthorization Cancellation Accomplishedresponse.complete
- `10`Patient Registeredrequest.initiated
- `11`Patient Admittedrequest.initiated
- `14`Discharge Submittedrequest.initiated
- `28`Claim Request In Processresponse.partial
- `29`Claim Forwardedresponse.partial
- `31`Payment Processedrequest.initiated
- `33`Payment Settledrequest.initiated
- `141`Discharge Query Response Submittedresponse.complete
- `151`Claim Query Response Submittedresponse.complete
- `252`Reprocess Request Approvedresponse.complete
- `253`Reprocess Request Rejectedresponse.complete
- `254`Reprocess Request Queriedrequest.initiated
- `261`Discharge Request Approvedresponse.partial
- `262`Discharge Request Rejectedresponse.complete
- `263`Discharge Request Queriedrequest.initiated
- `45`Final Bill Initimationrequest.initiated
- `45`Final Bill Ack Successresponse.partial
- `45`Final Bill Ack Failedresponse.error
- `15`Claim Request Initiatedrequest.initiated
- `181`Final Bill Query Responseresponse.complete
- `161`Claim Doc Query Responseresponse.complete
- `17`Payment Notice Recivedresponse.complete
- `25`Claim Doc Ack Successresponse.partial
- `25`Claim Doc Ack Failedresponse.error
- `46`Final Bill Approveresponse.complete
- `26`Claim Request Approvedresponse.complete
- `47`Final Bill Query Raiserequest.initiated
- `47`Final Bill Query Ack Successresponse.partial
- `47`Final Bill Query Ack Failedresponse.error
- `27`Claim Request Queriedrequest.initiated
- `27`Claim Request Queriedresponse.partial/complete
- `491`Final Bill Denyresponse.complete
- `291`Claim Doc Denyresponse.complete
- `30`Payment Notice Initmationrequest.initiated
- `30`Payment Notice Ack Successresponse.partial
- `30`Payment Notice Ack Failedresponse.error
- `R122`Reimburstment Claim Reprocess Requestedrequest.initiated
- `R15`Reimburstment Claim Submittedrequest.initiated
- `R151`Reimburstment Claim Query Response Submittedresponse.complete
- `R252`Reimburstment Claim Reprocess Request Approvedresponse.complete
- `R253`Reimburstment Claim Reprocess Request Rejectedresponse.complete
- `R254`Reimburstment Claim Reprocess Request Queriedrequest.initiated
- `R26`Reimburstment Claim Approvedresponse.complete
- `R27`Reimburstment Claim Queriedrequest.initiated
- `R28`Reimburstment Claim Evaluation In Processresponse.partial
- `R291`Reimburstment Claim Rejectedresponse.complete
- `34`Wallet Upgrade Intimationrequest.initiated
- `36`Claim Arbitration Intimationrequest.initiated
- `38`Fraud Alertrequest.initiated
- `35`Wallet Upgrade Acknowledgementresponse.complete
- `37`Claim Arbitration Acknowledgementresponse.complete
- `39`Fraud Alert Acknowledgementresponse.complete
- `G11`Grievance Intimationrequest.initiated
- `G12`Grievance Acknowledmentresponse.complete
- `G13`Grievance Intimation Failureresponse.error
- `RP1`Return Payment Intimationrequest.initiated
- `RP2`Return Payment Acknowledgementresponse.complete
- `RP3`Return Payment Failureresponse.error
- `N01`Notifications Intended To Payerrequest.initiated
- `N02`Notifications Intended To Providerrequest.initiated
- `N03`Notifications Intended To Beneficiaryrequest.initiated
- `N04`Acknowledgement Of The Notificaionresponse.complete
- `DC01`Discharge Correction Intimationrequest.initiated
- `DC02`Acknowledgement For Discharge Correctionresponse.complete

## Mainline Cashless State Machines

In the diagrams below, each arrow carries the workflow code of the message that moves the case.

### Preauthorisation Lifecycle

```mermaid
stateDiagram-v2
  [*] --> Requested: 12
  Requested --> Received: 20
  Received --> Approved: 21
  Received --> Rejected: 23
  Received --> Queried: 24
  Queried --> QueryAnswered: 19
  QueryAnswered --> Received
  Rejected --> Resubmitted: 121
  Resubmitted --> Received: 251
  Approved --> EnhancementAsked: 13
  EnhancementAsked --> Approved: 22
  EnhancementAsked --> EnhancementDenied: 231
  EnhancementAsked --> EnhancementQueried: 241
  EnhancementQueried --> EnhancementAnswered: 131
  EnhancementAnswered --> Approved: 22
  EnhancementAnswered --> EnhancementDenied: 231
  Received --> CancelAsked: PC01
  Approved --> CancelAsked: PC01
  CancelAsked --> Cancelled: PC02
  Approved --> [*]
```

### Claim Lifecycle

```mermaid
stateDiagram-v2
  [*] --> Submitted: 15
  Submitted --> Received: 25
  Received --> InProcess: 28
  InProcess --> Forwarded: 29
  Forwarded --> InProcess
  InProcess --> Queried: 27
  Queried --> QueryAnswered: 151
  QueryAnswered --> InProcess
  InProcess --> Approved: 26
  InProcess --> Denied: 291
  Denied --> ArbitrationAsked: 36
  ArbitrationAsked --> ArbitrationAcknowledged: 37
  ArbitrationAcknowledged --> ReprocessApproved: 252
  ArbitrationAcknowledged --> ReprocessRejected: 253
  ArbitrationAcknowledged --> ReprocessQueried: 254
  ReprocessQueried --> ArbitrationAcknowledged: 19
  Approved --> [*]
```

### Payment & Settlement Lifecycle

```mermaid
stateDiagram-v2
  [*] --> Initiated: 30
  Initiated --> Processed: 31
  Processed --> Settled: 33, UTR available
  Settled --> Acknowledged: 17, sent by the provider
  Acknowledged --> [*]
```


---

# Base URLs

Every NHCX call is a base URL followed by a path. Each base URL is fixed: one value in the sandbox and one in production. It does not change from call to call or from participant to participant. The paths are the same in both environments. Each service has its own base, so keep the bases in configuration and set them once per environment.

## In short

- Each service has its own base. The exchange, the participant service and the ABDM gateway are three different bases, not one.
- A path in this documentation, such as `/v1/preauth/submit`, goes after the base of the service that serves it.
- Each base is a fixed value for its environment. Going Live has the order of the switch from the sandbox values to the production values.

## Every base, in both environments

| Service                  | Sandbox                                                         | Production                                                    |
| ------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------- |
| ABDM session token       | `https://dev.abdm.gov.in`                                       | `https://apis.abdm.gov.in`                                    |
| NHCX exchange            | `https://apisbx.abdm.gov.in/hcx`                                | `https://apisprod.nha.gov.in/hcx`                             |
| Participant service      | `https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice` | `https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice` |
| ABDM proxy               | `https://apisbx.abdm.gov.in/pmjay/sbxhcx/abdmproxy`             | `https://apisprod.nha.gov.in/pmjay/hcx/abdmproxy`             |
| NHCX portal              | `https://hcxsbx.abdm.gov.in`                                    | `https://nhcx.abdm.gov.in`                                    |
| Face authentication page | `https://phrsbx.abdm.gov.in/face-auth`                          | `https://phr.abdm.gov.in/face-auth`                           |

What each one serves:

- **ABDM session token**: The session token every other call carries, at /api/hiecm/gateway/v3/sessions.
- **NHCX exchange**: Every use-case call under /v1, fingerprint and iris authentication under /abha.
- **Participant service**: Creating and updating a participant, the registry search, certificates and policies.
- **ABDM proxy**: Face authentication for PMJAY biometrics.
- **NHCX portal**: The portal, the sandbox Swagger specifications it publishes, and notification subscribe.
- **Face authentication page**: The QR page a patient opens to complete face authentication, with ?txnId=\<txnId>.

The ABDM gateway also reads `X-CM-ID` on the session call: `sbx` in the sandbox, `abdm` in production.

On the sandbox, a preauthorisation is therefore posted to `https://apisbx.abdm.gov.in/hcx/v1/preauth/submit`, and a participant is created at `https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/v2/participant/create`.

## Two things that are easy to get wrong

**The use-case path is `/hcx/v1`, the participant path is `/pmjay/sbxhcx/participanthcxservice`.** They are different services on the same host and neither prefix works for the other.

**Biometrics span two bases.** Fingerprint and iris sit under the exchange's `/abha/`; face authentication sits under the ABDM proxy's `/abha/`. A client that assumes one base path for all three will fail on face authentication alone.

## Production

The production bases are fixed values, listed in the table above. The exchange's production base is `https://apisprod.nha.gov.in/hcx`. The participant service's is `https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice`, and the ABDM gateway's is `https://apis.abdm.gov.in`. When you go live, set each base to its production value once.

## Next steps

- Session Token: the first call, made against the ABDM gateway's base
- Environments and Addresses, in the Reference: every full address, the headers each service reads, and the firewall
- Going Live: when and how each base changes to production


---

# Build it well

Every call on this site can be made correctly and still leave a hospital with a claim it cannot find. NHCX answers later, on another connection, and sometimes not at all. These are the rules that decide whether your integration survives that, and each one was learnt from a build that got it wrong once.

## In short

- The family of an error code says who refused: the exchange, the payer, or your own receiving end.
- Match every answer on its correlation id, never on the path or the order it arrived in.
- A send that reports failure may still have landed. Look before you send again.
- Deduplicate deliveries, because the exchange redelivers up to five times.
- Silence has four causes, and one of them is a route you did not host.

## Read who refused before you read the code

Three places refuse a message. Which one it was decides what you fix.

| What you received                    | Who refused                                       | Where it arrives                                                           |
| ------------------------------------ | ------------------------------------------------- | -------------------------------------------------------------------------- |
| HTTP `400` or `401` on your own send | the exchange, before the message went further     | the answer to your call. A `401` is an expired token or a missing `Bearer` |
| A delivery your key cannot open      | your own receiving end                            | the certificate on your participant record is not the key you hold         |
| `NHCX-*`                             | the exchange. The message never reached the payer | the answer to your call, or a `ProtocolResponse` on your callback later    |
| `PAYR-*`, `ERR-PYR-*`                | the payer. The message reached it                 | a `ProtocolResponse` on your callback, on the request's correlation id     |

A `ProtocolResponse` is plain JSON, not a bundle. It carries `x-hcx-status` as `response.error`, and the code and text in `x-hcx-error_details`.

Do not match a `PAYR` code on its number alone. The same number means different things from different payers. Read the code with the message text beside it, and log both. [Reading error codes](/docs/nhcx/v1/reference/error-code-guide) lists the collisions, and [error codes](/docs/nhcx/v1/reference/error-codes) lists every code.

## Match every answer on its correlation id

The acknowledgement and the decision share one correlation id. So does every redelivery. Route an inbound message by that id first, and by the claim number inside the bundle second.

| Mistake                                             | What happens                                                   |
| --------------------------------------------------- | -------------------------------------------------------------- |
| Closing a thread on its first reply                 | the decision arrives on the same id and is thrown away         |
| Matching by path or by arrival order                | an answer lands on the wrong case                              |
| Reusing a correlation id after an error             | the exchange has retired it, and refuses the next attempt      |
| Answering a scheme payer's query on the same thread | the answer is swallowed without a refusal. It goes on a new id |
| Sending an id that is not a UUID                    | a transport may replace it, and the thread is lost             |

Store the ids the transport returned, not the ones you meant to send. See [responses arrive against the wrong request](/docs/nhcx/v1/troubleshooting/responses-arrive-against-the-wrong-request).

## What is safe to send again

A send that reports failure can still have landed. A connection that drops after the request was written answers `502`, while the exchange has the message and the payer acknowledges it seconds later. A hospital that reads that `502` as "not sent" sends again. The payer refuses the duplicate, and a live case now stands at the payer that the hospital has no record of.

1. Store `txn_id`, `correlation_id` and `api_call_id` before the POST, so a failed POST still has a handle.
2. Record the failed leg under that correlation id, not as nothing.
3. When an answer arrives on a failed leg's correlation id, revive the leg rather than offering a second send.
4. After a real refusal, send again on a fresh correlation id.

## Receive as if every delivery comes twice

The exchange redelivers an unacknowledged message up to five times, then drops the correlation id. A payer may also redeliver a large answer on its own.

- Deduplicate on `x-hcx-api_call_id`.
- Deduplicate payment notices and communication requests on their correlation id, with a unique index.
- Answer `2xx` before doing slow work. The exchange allows 30 seconds for the receipt.
- If applying a delivery failed for a passing reason, such as a database being away, un-record it. Otherwise its redelivery is waved off as a duplicate.

[Receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has the route and the receipt.

## When no answer comes

Silence is a finding. Check these in order.

1. The send landed although it reported failure. Look for a delivery on its correlation id.
2. The answer arrived and a settled-status guard discarded it.
3. The answer went out on the wrong thread and was swallowed.
4. The exchange could not deliver, and reported that to `/v1/error`. If you do not host that route, nothing told you.

Then ask for the status rather than sending again: [status and search](/docs/nhcx/v1/getting-started/status-and-search).

## How you know it holds

Replace your `send` with a stub and replay one case: an acknowledgement, the same acknowledgement again, then the decision. The case must end decided, with one row per message and no second send offered. Then fail a send after the write, deliver its answer, and check the leg revives.

## Where to go next

- [Build with AI](/docs/nhcx/v1/getting-started/build-with-ai) sets an agent up with all seven skills and the documentation server.
- [Building and sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe) is the seal every rule above assumes.
- [The provider checklist](/docs/nhcx/v1/roles/provider/provider-checklist) is what has to be in place before go live.


---

# Build with AI

Use NHCX documentation with AI-assisted development tools. Developers may use supported AI-assisted tools to search NHCX integration guides, API references and use case documentation while building their solution.

note

Review all AI-generated code against the official NHCX documentation and test it in the Sandbox.

Every fact on this site is a public URL. There are three ways to put it in front of your agent, and they combine. From lightest to fullest:

- Copy one skill into your project.
- Install all seven skills as a plugin.
- Connect the docs server, so the agent can look things up as it works.

[Recommended](#connect-the-docs-mcp-server)

[Docs MCP server](#connect-the-docs-mcp-server)

[This documentation live, queried a paragraph at a time as your agent works. It cannot go stale, because it is this site answering.](#connect-the-docs-mcp-server)

[AI plugin](#install-the-plugin)

[All seven NHCX skills in one install, updated in place. Add the marketplace once, then install the plugin.](#install-the-plugin)

[Agent skills](#install-a-skill)

[One folder per NHCX use case, in episode order. Works offline, and ages until you update it.](#install-a-skill)

## Learn how to use AI

Never built with a coding assistant before? Start here. Three things have to be in place before anything else on this page works.

| What you need               | Why                                                                                                                                       |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| A coding assistant          | Claude, Cursor, VS Code with GitHub Copilot, Codex and ChatGPT are the ones set up below. Any of them is enough. Pick one and stay on it. |
| A paid plan on it           | Free tiers stop partway through a long task. The cheapest paid plan on any of these carries a use case.                                   |
| Your own project open in it | The assistant reads and writes the folder it is opened in. Open the repository you are integrating NHCX into first.                       |

Then work down the page in order.

1. Connect the Docs MCP server, so the assistant looks NHCX up here instead of recalling an older version of it.
2. Install the plugin, which is one command or one pasted line.
3. Install the skill for the use case you are on, `nhcx-coverage` first if you are starting.
4. Ask for what you want in plain language, one use case at a time. "Add coverage eligibility to this project, using the nhcx-coverage skill" is a good first prompt.

You do not need to know what MCP, a plugin or a skill is to use them. They are three ways of handing the same documentation to the assistant: live lookup, one install for everything, and one folder for one use case.

Read what it writes before you run it. An assistant is fast and confident, and it is wrong in ways only the Sandbox will show you.

## Connect the Docs MCP server

A skill is a snapshot. The Docs MCP server is the same documentation live, queried a paragraph at a time instead of loaded whole. The agent searches it, decodes error codes and checks request bodies as it works, alongside a skill or on its own. Add it as `nhcx-docs` at `https://docs.abdm.gov.in/mcp`.

Docs MCP server

Your agent queries this catalogue as it works, instead of loading it.

- SearchHybrid keyword and semantic search over every page here, so an agent retrieves the paragraph it needs instead of loading the site.`search_docs, get_atom, related_atoms, list_atoms`
- DecodeTurn an error code you just received into what it means and what to do, without you finding the right table.`decode_error`
- ValidateCheck a request body against the specification before you send it, and list or read any operation.`validate_request, list_operations, get_operation`

**Claude**

[Add to Claude](claude://code/new?q=Add%20the%20NHCX%20documentation%20MCP%20server%2C%20then%20use%20it%20to%20answer%20my%20NHCX%20questions.%0A%0ARun%20this%3A%0Aclaude%20mcp%20add%20--transport%20http%20nhcx-docs%20https%3A%2F%2Fdocs.abdm.gov.in%2Fmcp%20-s%20user%0A%0AUser%20scope%2C%20so%20it%20is%20available%20in%20every%20project%20rather%20than%20only%20this%20directory.%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

`claude mcp add --transport http nhcx-docs https://docs.abdm.gov.in/mcp -s user`

User scope, so it is there in every project rather than only this directory. Claude Desktop takes the generic block under "Any agent" instead.

**Cursor**

[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=nhcx-docs\&config=eyJ1cmwiOiJodHRwczovL2RvY3MuYWJkbS5nb3YuaW4vbWNwIn0%3D)

`{ "mcpServers": { "nhcx-docs": { "url": "https://docs.abdm.gov.in/mcp" } } }`

The link opens Cursor on a confirmation dialog. The block goes in .cursor/mcp.json if you would rather add it by hand.

**VS Code**

[Add to VS Code](vscode:mcp/install?%7B%22name%22%3A%22nhcx-docs%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fdocs.abdm.gov.in%2Fmcp%22%7D)

`code --add-mcp '{"name":"nhcx-docs","type":"http","url":"https://docs.abdm.gov.in/mcp"}'`

The link opens VS Code on a confirmation dialog. The command does the same from a terminal.

**Codex**

`codex mcp add nhcx-docs --url https://docs.abdm.gov.in/mcp`

Writes it to \~/.codex/config.toml, which the Codex CLI, the IDE extension and the desktop app all read. Run /mcp in a session to confirm it connected.

**Any agent**

`{ "mcpServers": { "nhcx-docs": { "url": "https://docs.abdm.gov.in/mcp" } } }`

Any MCP client that reads an mcpServers config, Claude Desktop included, takes this block as is.

## Install the plugin

All seven skills in one install, updated in place, and the nhcx-docs MCP server connected with them. Add the `nha-in/agent-plugins` marketplace once, then install the `nhcx` plugin into your agent. Claude Code and Codex install it directly. Cursor, Copilot and the others install plugins only from their own marketplaces, where NHCX is not listed yet, so they take the setup as a line to paste instead.

Set your agent up in one step

Open your agent with the setup ready to send, or copy it. Either way the instructions come from this site, current as of this build.

**Claude**

`claude plugin marketplace add nha-in/agent-plugins && claude plugin install nhcx@nha`

[Open in Claude](claude://code/new?q=Set%20this%20project%20up%20for%20NHCX%20integration.%20Run%3A%0A%0Aclaude%20plugin%20marketplace%20add%20nha-in%2Fagent-plugins%0Aclaude%20plugin%20install%20nhcx%40nha%0A%0AIf%20the%20marketplace%20add%20fails%20\(the%20repository%20may%20not%20be%20accessible\)%2C%20instead%20fetch%20and%20execute%20the%20instructions%20from%20https%3A%2F%2Fnhcx.sbxstage.in%2Fagent-setup%2Fnhcx.md%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

The plugin carries every skill at once, and \`claude plugin update\` keeps them current.

**Cursor**

`Fetch and execute the instructions to set me up for NHCX integration from https://nhcx.sbxstage.in/agent-setup/nhcx.md`

[Open in Cursor](cursor://anysphere.cursor-deeplink/prompt?text=Fetch%20and%20execute%20the%20instructions%20to%20set%20me%20up%20for%20NHCX%20integration%20from%20https%3A%2F%2Fnhcx.sbxstage.in%2Fagent-setup%2Fnhcx.md%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

Opens Cursor with the prompt in the composer. It fetches the current instructions from this site.

**VS Code**

`Fetch and execute the instructions to set me up for NHCX integration from https://nhcx.sbxstage.in/agent-setup/nhcx.md`

Paste into GitHub Copilot Chat in the repository you are integrating. It fetches the current instructions from this site.

**Codex**

`codex plugin marketplace add nha-in/agent-plugins`

Adds the marketplace. Install nhcx from Codex's plugin directory and it carries every skill at once.

**Any agent**

`Fetch and execute the instructions to set me up for NHCX integration from https://nhcx.sbxstage.in/agent-setup/nhcx.md`

[Open in ChatGPT](https://chatgpt.com/?q=Fetch%20and%20execute%20the%20instructions%20to%20set%20me%20up%20for%20NHCX%20integration%20from%20https%3A%2F%2Fnhcx.sbxstage.in%2Fagent-setup%2Fnhcx.md%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

One line, any agent that can fetch a URL, ChatGPT included. The instructions live on this site and are rebuilt with it.

The setup also connects the [Docs MCP server](/docs/hiecm/v3/getting-started/build-with-ai#connect-the-docs-mcp-server): the live version of these docs, queried by your agent as it works.

## Install a skill

There is one skill for the whole provider-side integration, `nhcx-full`, and one per NHCX use case. Each builds into an existing hospital information system through eight logged steps, from discovery and mapping to tests on the sandbox. It finds what your system already has and builds only what is missing. It takes its NHCX facts from the nhcx-docs MCP server when it is connected, and from a release of the NHCX package otherwise.

Each skill is self-contained, so install only the ones your integration needs. `npx skills` finds every coding agent in the project and sets the skill up for each. With git alone, the command fetches just the skill's folder into the directory your agent reads skills from.

| Skill                | What it builds                                                                                                                                 | [Use cases](/docs/nhcx/v1/concepts/nhcx-use-cases) |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `nhcx-full`          | The whole provider-side integration, every exchange end to end, with the NHCX gateway embedded in the application                              | All provider use cases                             |
| `nhcx-coverage`      | Beneficiary policy search and coverage eligibility: validation, benefits and discovery                                                         | A2, B1, D3                                         |
| `nhcx-preauth`       | The payer's insurance plan, line items, authorisation requirements, the pre-authorisation, enhancement, query answers, cancellation and status | B2, B3, B8 cancel, D1, D2, D4 to D8                |
| `nhcx-claim`         | Discharge details, claim documents and forms, the claim and its query answers, the payer's verdict and status enquiries                        | A5, B5, D9, D10                                    |
| `nhcx-communication` | Payer queries, notifications and notes on a case, replies with text and documents, and acknowledgements                                        | B4                                                 |
| `nhcx-payment`       | The payer's payment notice and its breakdown, matched to the claim and acknowledged                                                            | B7, D13                                            |
| `nhcx-reprocess`     | Asking the payer to look again at a decided claim, and asking for the unpaid balance of a partly paid claim                                    | B8 reprocess, D11, D12                             |

NHCX agent skill

The whole provider-side integration, every exchange end to end, with the NHCX gateway embedded in the application.

[SKILL.md](/skills/nhcx-full/SKILL.md "The router. Use the command below to take the references with it.")

- ScaffoldThe eight steps that build the use case into your system, from discovery and mapping through code to tests on the sandbox, each logged as it goes.
- Integrate26 operations, with their hosts and headers.
- Test10 test matrix rows, from offline pins up to a live payer on the sandbox.

`mkdir -p .claude/skills && curl -fsSL https://nhcx.sbxstage.in/skills/nhcx-full.tar.gz | tar -xzf - -C .claude/skills`

[Open in Claude](claude://code/new?q=Install%20the%20ABDM%20NHCX%20agent%20skill%20into%20this%20project%2C%20then%20help%20me%20use%20it.%0A%0ARun%20this%3A%0Amkdir%20-p%20.claude%2Fskills%20%26%26%20curl%20-fsSL%20https%3A%2F%2Fnhcx.sbxstage.in%2Fskills%2Fnhcx-full.tar.gz%20%7C%20tar%20-xzf%20-%20-C%20.claude%2Fskills%0A%0AIf%20this%20session%20did%20not%20open%20in%20the%20repository%20I%20am%20integrating%20ABDM%20into%2C%20ask%20me%20for%20the%20path%20before%20you%20write%20anything.)

Drops the skill into this project. Claude loads it when a task matches.

How to use it

1. Run the command above in the repository you are integrating.
2. Ask your agent for the job in your own words. "Build the whole provider-side NHCX integration into this hospital system". The skill loads when the task matches it.
3. Check what it writes against these pages. The skill names the cases it could not reach on the NHCX sandbox, and nothing in it is re-verified here.
4. Open in Claude needs that app installed. It fills the composer and waits: nothing runs until you read it and press Enter.

Download all skills

- [Everything](https://nhcx.sbxstage.in/skills/nhcx-full.tar.gz)
- [Coverage](https://nhcx.sbxstage.in/skills/nhcx-coverage.tar.gz)
- [Preauth](https://nhcx.sbxstage.in/skills/nhcx-preauth.tar.gz)
- [Claim](https://nhcx.sbxstage.in/skills/nhcx-claim.tar.gz)
- [Communication](https://nhcx.sbxstage.in/skills/nhcx-communication.tar.gz)
- [Payment](https://nhcx.sbxstage.in/skills/nhcx-payment.tar.gz)
- [Reprocess](https://nhcx.sbxstage.in/skills/nhcx-reprocess.tar.gz)

## Prompting an agent to build against NHCX

An agent with this site loaded still writes a plausible integration rather than a correct one, because the parts of NHCX that catch people are the parts a model cannot infer. Tell it these, and check its output against them.

| Tell it                                                                        | Because                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Look the operation up here before writing the call                             | An agent fills gaps in the envelope and the bundle from memory. The MCP server above is this site answering live, so it cannot be recalling another shape                                                                                                                   |
| Every answer arrives at your server, not in the response to your call          | Left alone, an agent writes a response handler for a call whose 202 means accepted and nothing else. See [receiving a callback](/docs/nhcx/v1/getting-started/receiving-a-callback)                                                                                         |
| Open each cycle with a new correlation ID, and match answers on it             | An agent matches on arrival order, or reuses a failed cycle's ID, which the exchange refuses with `NHCX-1006`. See [responses arrive against the wrong request](/docs/nhcx/v1/troubleshooting/responses-arrive-against-the-wrong-request)                                   |
| Every bundle is sealed for its recipient, with the recipient's certificate     | An agent seals with your own certificate, or with the first one it finds. See [fetching a recipient certificate](/docs/nhcx/v1/getting-started/fetching-a-recipient-certificate) and [building and sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe) |
| Host `/v1/error` beside the other callbacks                                    | It is where the exchange reports a message it could not deliver. Without it you never find out                                                                                                                                                                              |
| Run the NRCeS validator on the exact bundle you seal                           | A bundle that looks right is refused by the payer with a `PAYR-` code. See [the payer rejects your bundle](/docs/nhcx/v1/troubleshooting/the-payer-rejects-your-bundle)                                                                                                     |
| Do not invent an error code or a workflow code                                 | Both exist here in full. See [workflow codes](/docs/nhcx/v1/concepts/workflow-codes) and [error codes](/docs/nhcx/v1/reference/error-code-guide)                                                                                                                            |
| Patient identifiers and bundle contents never reach a log, a fixture or a test | An agent writing test data will otherwise put a real looking beneficiary in your repository                                                                                                                                                                                 |

Point it at [Build it well](/docs/nhcx/v1/getting-started/build-it-well) for the handling rules themselves: who refused a message, what is safe to send again, and what to do when no answer comes. Then point it at the [provider checklist](/docs/nhcx/v1/roles/provider/provider-checklist) or the [payer checklist](/docs/nhcx/v1/roles/payer/payer-checklist) for what your side has to have in place before go live.

## Read this site as an agent

`llms.txt` is a map of every page here; `llms-full.txt` is every page's text in one file. Each NHCX API module also has its own index at `/docs/nhcx/v1/api/<module>/llms.txt`, and [API references](/docs/nhcx/v1/api) names the modules. Add `/index.md` to any URL on this site to get that page as plain Markdown, no scraping required.

[View llms.txt](/llms.txt)[View llms-full.txt](/llms-full.txt)[This page as Markdown](/docs/nhcx/v1/getting-started/build-with-ai/index.md)

## Ask AI

Ask this catalogue a question directly, without setting anything up.

The same assistant sits in the search box at the top of every page, labelled "Search or ask AI".

### Attaching a file

Ask AI takes a file with your question: a failing request body, a FHIR bundle, a log, a CSV, a PDF, or a screenshot. The paperclip is on the left of the box. At most 20,000 characters of text, 256KB for a text file and 8MB for a PDF or an image.

What happens to it is worth knowing before you attach one.

- The file is read in your own browser and only the text it gives up travels with your question. A PDF gives up the text it already carries. A screenshot is read by a text recognition engine your browser downloads once, from this site, and runs on your own machine. The picture itself is never sent, so nothing is uploaded and nothing is stored: the conversation lives in the panel and is gone when you close it.
- A PDF that is only pictures of text, a scan, gives up nothing. Screenshot the part you mean instead and that will be read.
- Text read from a picture carries reading mistakes. The assistant is told where the text came from, so it can say when an answer turns on a character it cannot trust.
- Personal data is removed before the file reaches the model. A file that parses as JSON is masked by its field names, so `name`, `telecom`, `address`, `birthDate` and identifier values in a FHIR bundle are replaced with placeholders such as `<MASKED_NAME>`. Aadhaar, ABHA, PAN, passport, voter, mobile, email and bearer tokens are matched by pattern anywhere in the file, JSON or not.
- A file with no field names, a log or the text read from a screenshot, gets the same pattern masking, and a name on a labelled line goes too: `patient: Rakesh Sharma` leaves as `patient: <MASKED_NAME>`.
- What none of that catches is a name written in running prose, with nothing marking it as a name. Redact those yourself, the same way you would in a support request. The panel says so next to any file it read for you.
- Your question is logged, masked, to improve the answers. The file is not logged.

## Next steps

- [Get your sandbox credentials](/docs/nhcx/v1/getting-started/get-your-sandbox-credentials)
- [Quickstart](/docs/nhcx/v1/getting-started/quickstart)
- [The base framework](/docs/nhcx/v1/getting-started/the-base-framework)


---

# Building and sending a JWE

A message on the exchange is a JSON Web Encryption token: a readable protected header and an encrypted body, serialised as five base64url parts joined by dots. The body is a FHIR bundle. This chapter builds one with an empty bundle, so that what you are testing is the envelope and the plumbing, not the FHIR.

## The protected header

Every field the exchange needs to route and log the message. All the `x-hcx-` names are fixed.

Every field, its obligation and its allowed values are in [The JWE message format](/docs/nhcx/v1/getting-started/jwe-message-format).

```json
{  "alg": "RSA-OAEP-256",  "enc": "A256GCM",  "x-hcx-sender_code": "1000004446@hcx",  "x-hcx-recipient_code": "1000003538@hcx",  "x-hcx-api_call_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",  "x-hcx-request_id": "f0e1d2c3-b4a5-4978-8fed-cba987654321",  "x-hcx-correlation_id": "11223344-5566-4788-99aa-bbccddeeff00",  "x-hcx-workflow_id": "12",  "x-hcx-timestamp": "2026-09-04T11:46:34+05:30",  "x-hcx-status": "request.initiated",  "x-hcx-ben-abha-id": "91123456781234"}
```

- `alg` and `enc` are the encryption. The protocol page says `RSA-OAEP`; the handbook, the code samples and every Postman body on the portal say `RSA-OAEP-256`. Use `-256`.

- The three IDs are fresh UUIDs. `api_call_id` is new per call, `request_id` per request, `correlation_id` per conversation and reused on the answer.

- `workflow_id` says which step this is. `12` is a new preauthorisation.

- `timestamp` is ISO 8601. Which zone is contested: the handbook says Indian time and that UTC will fail validation, the FAQ says UTC with a trailing `Z`. The sample bundles use `+05:30`. Confirm before building; it is a validated field.

- `status` is always `request.initiated` on something you initiate.

- `ben-abha-id` is the beneficiary's ABHA number. Its form depends on where it travels:

  - Inside the bundle, the ABHA identifier is 14 digits without hyphens.
  - On this header, the published sample also sends 14 digits without hyphens. The gateway's own refusal, `NHCX-1018`, asks for `XX-XXXX-XXXX-XXXX`.
  - Store the 14 digits once and format them where you build the header. If the gateway answers `NHCX-1018`, send the hyphenated form on the header and leave the bundle alone.

## The smallest possible bundle

```json
{  "resourceType": "Bundle",  "id": "smoke-test-001",  "type": "collection",  "timestamp": "2026-09-04T11:46:34+05:30",  "entry": []}
```

This is a valid FHIR Bundle with nothing in it. The exchange will accept it, because it only reads the header. The dummy payer will reject it, because there is no Claim inside. That rejection is what the next chapter catches.

## Sealing it

The recipe, from the message-security page. Base64url the header, generate a random content key, and encrypt that key with the recipient's public key using RSA-OAEP. Generate an IV, encrypt the bundle with AES-256-GCM using the header as additional authenticated data, and join the five parts. A JOSE library does all of it.

```js
bundle = json.encode(fhirBundle)header = {    "alg": "RSA-OAEP-256",    "enc": "A256GCM",    "x-hcx-sender_code":    sender,    "x-hcx-recipient_code": recipient,    "x-hcx-api_call_id":    randomUUID(),    "x-hcx-request_id":     randomUUID(),    "x-hcx-correlation_id": correlationId,    "x-hcx-workflow_id":    workflowId,    "x-hcx-timestamp":      currentISTTimestamp(),    "x-hcx-status":         "request.initiated",    "x-hcx-ben-abha-id":    abhaId}jwe = jose.encrypt(    plaintext       = bundle,    recipientKey    = recipientPublicKey,       // from the certificate fetched in the previous chapter    protectedHeader = header,    algorithm       = "RSA-OAEP-256",    encryption      = "A256GCM")body = { "payload": jwe }
```

warning

This is pseudo-code, not something to paste. Use your language's JOSE library: `jose` on Node, `jwcrypto` on Python, Nimbus on Java, `System.IdentityModel.Tokens.Jwt` or `jose-jwt` on .NET.

The result is one long string with four dots in it. That is the whole message. Java users can take the portal's `JWEPayloadUtil` sample as-is; it does the same thing with Nimbus, `JWEAlgorithm.RSA_OAEP_256` and `EncryptionMethod.A256GCM`, passing the `x-hcx-` fields as custom header parameters.

## Sending it

The request body is a JSON object with one field. The `x-hcx-` fields are not HTTP headers: they travel inside the JWE's protected header, sealed above. The only headers on the wire are the token and the content types.

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/hcx/v1/preauth/submit' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwieC1oY3gtc2VuZGVyX2NvZGUiOi4uLn0.encrypted_key.iv.ciphertext.tag"  }'
```

[Pre-authorisation submit in the API reference](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-submit)

## What comes straight back

`202 Accepted`. The receipt below is the shape the sources define for a *recipient* acknowledging a delivery, which is what your own callback must return in the next chapter. Treat it as the pattern rather than a guaranteed gateway body, and inspect a real response:

```json
{  "timestamp": "04/09/2026 11:46:35:120",  "api_call_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",  "correlation_id": "11223344-5566-4788-99aa-bbccddeeff00",  "result": {    "sender_code": "1000004446@hcx",    "recipient_code": "1000003538@hcx",    "entity_type": "preauth",    "protocol_status": "request.queued"  },  "error": { "code": "", "message": "" }}
```

This is not the decision. It says the envelope was valid and the message has been queued for the recipient. The decision, or in this case the rejection, comes later, on your callback.

If instead you get `400`, the envelope failed validation. If you get `401`, go back to the token chapter. Anything else about the bundle itself will not show up here at all; the exchange never opens it.


---

# Creating and updating a participant

A participant record is your identity on the exchange. It holds your participant code, your role, your certificate and your callback address. You create it once, then update it whenever the certificate or the address changes.

The sandbox and production differ here. The sandbox is a single call each way. Production adds a one-time passcode to the registered mobile number at every step, so nobody can register a hospital they do not control. Both are shown.

## Sandbox: create

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/create' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --header 'source: internal' \  --data-raw '{    "linked_registry_codes": [      "10001"    ],    "registryid": "<client id>",    "participant_name": "Test Hospital",    "scheme_code": "PMJAY",    "state": "Haryana",    "district": "Panchkula",    "roles": [      "10001"    ],    "primaryEmail": "integration@hospital.example",    "phone": [      "01123456789"    ],    "primaryMobile": "9876543210",    "signing_cert_path": "",    "encryption_cert": "<encryption cert>",    "endpoint_url": "https://nhcx.hospital.example"  }'
```

[Participant create (v1) in the API reference](/docs/nhcx/v1/api/onboarding/endpoints/onboarding-participant-create)

Field by field:

| Field                   | What to put                                                                                                |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
| `linked_registry_codes` | Which registry vouches for you. `10001` HFR, `10002` NIN, `10003` ROHINI, `10004` payer registry.          |
| `registryid`            | On the sandbox, your ABDM client ID. In production, the HFR ID for a hospital or the IRDAI ID for a payer. |
| `roles`                 | `10001` provider, `10002` payer, `10003` TPA. The full list is in the Overview.                            |
| `encryption_cert`       | The base64 certificate from the previous chapter.                                                          |
| `signing_cert_path`     | Optional. Leave empty.                                                                                     |

The response carries your new address:

```json
{ "participant_code": "1000004446@hcx" }
```

Keep it. It is `x-hcx-sender_code` on everything you send from now on. A hospital group creates one participant per facility, each with its own HFR ID, using the same credentials.

## Sandbox: update

The same shape, keyed on the participant code, used to change the certificate or the callback address:

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/update' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "participant_code": "<participant code>",    "participant_name": "Test Hospital",    "scheme_code": "PMJAY",    "roles": [      "10001"    ],    "primaryEmail": "integration@hospital.example",    "phone": [      "01123456789"    ],    "primaryMobile": "9876543210",    "endpoint_url": "https://nhcx.hospital.example",    "signing_cert_path": "",    "encryption_cert": "<encryption cert>"  }'
```

[Participant update (v1) in the API reference](/docs/nhcx/v1/api/registry/endpoints/registry-participant-update)

`endpoint_url` is the base of your callback server, sometimes called the bridge URL. It can be set at creation as well as on update. The exchange appends the callback path to it: a preauthorisation decision arrives at `<endpoint_url>/v1/preauth/on_submit`. The rules for this address are in Receiving a Callback.

## Production: four steps

Base: `https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice`.

**1. Create.** `POST v2/participant/create`

```bash
curl --location --request POST 'https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice/v2/participant/create' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "registrytype": "10001",    "registryid": "XXXXX74586",    "role": [      "10001"    ],    "endpointurl": "https://nhcx.demohospital.example.in",    "mobilenumber": "XXXX748348",    "email": "sample@gmail.com"  }'
```

[Participant create (v2) in the API reference](/docs/nhcx/v1/api/onboarding/endpoints/onboarding-v2-participant-create)

The mobile number must match the one on your HFR record exactly, or for a payer the one NHA holds. The response gives `participantid` and a `transactionid`, and a passcode is sent to that mobile. The participant exists, in a pending state.

**2. Confirm.** `GET validate?transactionId=<id>&passcode=<code>`. Note the method: the two confirmation calls are GETs, not POSTs. The participant becomes active.

```bash
curl --location --request GET 'https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice/validate?transactionId=<transaction id>&passcode=<passcode>' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>'
```

[Validate participant creation in the API reference](/docs/nhcx/v1/api/onboarding/endpoints/onboarding-validate)

**3. Configure.** `POST v2/participant/update`

```bash
curl --location --request POST 'https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice/v2/participant/update' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "participantcode": "XXXXX7583@hcx",    "encryptioncert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...",    "endpointurl": "https://nhcx.demotpa.example.in"  }'
```

[Participant certificate and bridge update (v2) in the API reference](/docs/nhcx/v1/api/registry/endpoints/registry-v2-participant-update)

A second transaction ID and passcode arrive.

**4. Confirm again.** `GET update/validate?transactionId=<id>&passcode=<code>`. The certificate and address go live.

```bash
curl --location --request GET 'https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice/update/validate?transactionId=<transaction id>&passcode=<passcode>' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>'
```

[Validate participant update in the API reference](/docs/nhcx/v1/api/onboarding/endpoints/onboarding-update-validate)

Passcodes and transaction IDs are valid for 24 hours. If one is lost, repeat that step; a new pair is issued.

## Replacing only the certificate

In production there is a shorter path that skips the passcode:

```bash
curl --location --request POST 'https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice/v2/update/cert' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "participantId": "XXXX@hcx",    "certificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."  }'
```

[Update certificate (v2, no passcode) in the API reference](/docs/nhcx/v1/api/registry/endpoints/registry-v2-update-cert)

Use it for the yearly rotation.

## Checking it worked

Fetch your own certificate back, using the Fetching a Recipient Certificate chapter's call with your own participant code. If what comes back matches what you registered, the record is live and other participants can seal messages for you.


---

# Fetching a recipient certificate

Before you can seal a message for anyone, you need their public key. The participant service hands it out against a participant code.

## The call

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/fetch/certs' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "participantid": "1518@hcx"  }'
```

[Fetch certificate in the API reference](/docs/nhcx/v1/api/registry/endpoints/registry-fetch-certs)

That participant code is the sandbox dummy payer. For the smoke test at the end of this section it is the recipient.

## What comes back

Key material in PEM text. None of the source documents gives the JSON envelope it arrives in, only the material itself, so inspect one response before writing the parser. Usually a full X.509 certificate:

```text
-----BEGIN CERTIFICATE-----MIID0zCCArugAwIBAgIUax...-----END CERTIFICATE-----
```

Sometimes, for a participant who registered a bare key, an SPKI public key:

```text
-----BEGIN PUBLIC KEY-----MIIBIjANBgkqhkiG9w0BAQEF...-----END PUBLIC KEY-----
```

Handle both. Try to load it as a certificate and take the public key out of it; if that fails, load it as a public key directly. The handbook's rule of thumb is that anything under about 400 bytes is a bare key.

## Cache it

Keys change rarely. Fetching one before every message is a round trip that buys nothing, and the portal's own code sample says to store certificates locally rather than call this endpoint repeatedly. Cache by participant code for 24 hours, and refresh early if a decryption on the other side starts failing, which is the sign that they rotated.

## Whose certificate

The participant code to fetch is the `processingid` from the policy lookup in the previous chapter, not the insurer's `payerid`. For the smoke test it is the dummy payer's code, `1000003538@hcx`.


---

# Finding participants and policies

```mermaid
flowchart LR
  A[List participants by role] --> B[Choose the insurer]
  B --> C[Look up the patient's policies]
  C --> D{processingid}
  D --> E[Fetch that participant's certificate]
  E --> F[Seal and send]
```

Before a message can be sealed, two questions have to be answered: who is it going to, and which policy is it about. The participant service answers both. A provider asks them at every admission. A payer answers the second one in advance, by linking each policy to its holder when the policy is written.

## Listing participants

The registry can be asked for everyone holding a role. This is how a hospital system builds its list of payers, and how a payer finds hospitals.

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/fetch/participants/list' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "role": "PAYER",    "fromdate": "01/04/2021",    "todate": "20/03/2026",    "entitytype": "Gov"  }'
```

[Fetch participants list in the API reference](/docs/nhcx/v1/api/registry/endpoints/registry-fetch-participants-list)

- `role` is `PAYER`, `PROVIDER` or `TPA`.
- `fromdate` and `todate` bound the registration date, in `dd/MM/yyyy` only.
- `entitytype` is optional. `Gov` narrows to government schemes; leave it out for everyone.

The response is a list of participant records, each with the participant code, name, roles and entity type. The list is not searchable by name on the server side. Fetch it, filter by name in your own code when a user is looking for a specific insurer, and classify government against private from the entity type. Cache it for the day; it changes rarely.

There is no separate call to fetch one participant's details by code. The list is the lookup. Fetching a participant's certificate, covered in the next chapter, is the one per-participant call.

## Looking up a patient's policies

Given something that identifies the patient, the registry returns every policy linked to them.

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/get/policies' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "identifiertype": "AbhaNumber",    "identifiervalue": "12345678910111"  }'
```

[Get beneficiary policies in the API reference](/docs/nhcx/v1/api/registry/endpoints/registry-participant-get-policies)

`identifiertype` is one of three, and they are not equal. Try them in this order and stop at the first that returns a policy:

1. `AbhaNumber`, the ABHA number without hyphens. The strongest identifier.
2. `MemberId`, the member or policy number captured at admission.
3. `MobileNo`, the patient's registered mobile. The weakest, since a number can be shared or stale.

Each policy in the answer carries the fields that every later message depends on. The shape, not a verbatim sample:

```json
{  "policies": [    {      "payerid": "1518@hcx",      "processingid": "1000000109@hcx",      "memberid": "MD5SLS4X5",      "productid": "PMJAY/HP/S/G",      "productname": "PMJAY Himachal Pradesh"    }  ]}
```

| Field          | What it is for                                                                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| `payerid`      | The insurer's participant code. Goes inside the bundle as the insurer.                                        |
| `processingid` | Who processes claims for this policy. **This is the recipient on the envelope and the certificate to fetch.** |
| `memberid`     | Identifies the beneficiary in eligibility and claim bundles.                                                  |
| `productid`    | The product or plan code, used to fetch the insurance plan and coverage detail.                               |
| `productname`  | Human-readable; some systems use it as the effective policy code when a formal number is missing.             |

**Send to the processor.** When an insurer handles its own claims, `payerid` and `processingid` are the same code. When a TPA processes for it, `processingid` is the TPA and every request goes there. Pointing at `payerid` is the portal's seventh most common mistake; the request goes nowhere useful. If no `processingid` comes back, stop; nothing can be addressed.

**When no identifier returns a policy**, the order of calls matters, and it is fixed:

1. The policy lookup, with all three identifiers tried.
2. [Coverage eligibility](/docs/nhcx/v1/roles/provider/registration-and-eligibility) with purpose `discovery`, to learn the active policy code from the payer.
3. Coverage eligibility with purpose `validation`, carrying that policy code.

Cache the result against the patient. Their policies do not change between one screen and the next, and re-fetching on every step is wasted traffic. Provide a way to force a refresh when something has genuinely changed.

## Linking a policy to a beneficiary

This is the payer's half, and it is why the lookup above works at all. When a policy is written, the insurer links it to the holder's ABHA number, mobile and member ID, and names who will process claims for it.

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/link/abha/policy' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "requestid": "7f3f2a4e-0c6b-4b7a-9e2d-2c1f8a5b6d90",    "abhanumber": "12345678910111",    "mobilenumber": "9876543210",    "memberid": "MEM-2026-000123",    "payerid": "100234@sbx",    "policies": [      {        "productid": "PRD-FLOATER-01",        "productname": "Family Floater Gold"      }    ],    "processingid": "100235@sbx"  }'
```

[Link ABHA number to policies in the API reference](/docs/nhcx/v1/api/registry/endpoints/registry-participant-link-abha-policy)

- `requestid` is a fresh UUID.
- `payerid` is the insurer's own participant code. Every insurer has one, even when it works through a TPA.
- `processingid` is the TPA's participant code, or the insurer's own if it processes its own claims.
- `policies` lists each product the holder has, by product ID and name.

Only the two participants named on the link, the `payerid` and the `processingid`, may change it later. The exchange takes the client ID from the caller's token and checks it against them. That also means the token used to link must come from the same credentials that created that participant; a mismatch is refused and has to be sorted out with NHA by email.

## Removing a link

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/delink/abha/policy' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "requestid": "9a7c5e3d-1b2f-4c8a-b6d4-0e9f8a7b6c55",    "payerid": "100234@sbx",    "memberid": "MEM-2026-000123",    "policies": [      {        "productid": "PRD-FLOATER-01",        "productname": "Family Floater Gold"      }    ],    "processingid": "100235@sbx"  }'
```

[De-link ABHA policies in the API reference](/docs/nhcx/v1/api/registry/endpoints/registry-participant-delink-abha-policy)

Only products already on the link can be removed; naming one that is not there returns "There is no policies with requested details".

The commonest reason to de-link is a change of TPA. There is no edit call: every affected policy is de-linked with the old `processingid` and linked again with the new one. Plan that as a batch job, not a manual task.

## What a provider needs before sending anything

From the two lookups above, four values, in this order:

1. The insurer, chosen from the participant list.
2. The patient's policy with that insurer, from the policy lookup.
3. From it, the `processingid`, `memberid` and `productid`.
4. That participant's certificate, fetched in the next chapter against the `processingid`.

Only then can a message be sealed and addressed. A patient can look correctly admitted as insured on screen while every NHCX call fails, because step 3 was never reached.


---

# Get your sandbox credentials

Every National Health Claims Exchange (NHCX) call carries a session token, and every token starts with an [ABDM](/docs/nhcx/v1/getting-started/glossary#organisations-and-programmes) client ID and client secret. This chapter gets you those credentials, your NHCX sandbox roles, and a payer to test against.

## In short

- Register your organisation first: a hospital in the [Health Facility Registry (HFR)](/docs/nhcx/v1/getting-started/glossary#identity-and-registration), an insurer or [TPA](/docs/nhcx/v1/getting-started/glossary#organisations-and-programmes) with its [IRDAI](/docs/nhcx/v1/getting-started/glossary#organisations-and-programmes) registry id.
- Apply for ABDM sandbox credentials, then register the same client on the NHCX sandbox.
- Your software must support ABDM [Milestone 1](/docs/nhcx/v1/getting-started/glossary#identity-and-registration), [ABHA](/docs/nhcx/v1/getting-started/glossary#identity-and-registration) creation and verification.
- Test against the [dummy payer](/docs/nhcx/v1/getting-started/glossary#messages), participant code `1000003538@hcx`.
- The reviews have no fixed turnaround time, so start them first.

## Prerequisites

- Your organisation, and a mobile number for its registry record that you can receive messages on.

## Register the organisation

| You are              | Register in                                                            | Your registry id             |
| -------------------- | ---------------------------------------------------------------------- | ---------------------------- |
| A hospital or clinic | The Health Facility Registry (HFR), at <https://facility.abdm.gov.in/> | The HFR ID                   |
| A payer or TPA       | IRDAI, or the relevant authority                                       | The id that authority issues |

Keep the mobile number on the registry record current. Participant creation checks it and sends a passcode to it.

## Apply for ABDM sandbox credentials

1. Apply at <https://sandbox.abdm.gov.in/sandbox/v3/>.
2. Select "Providers and Payer" and Milestone 1 as your intent.
3. Wait for review. On approval you receive a client ID and a client secret.

The review is semi-manual. It filters out repeat requests from one organisation, organisations missing from every registry, technology providers without a valid website, and spam. Send one application only.

Store the secret the way you store any production credential. Never commit it, and never write it to a log.

## Build Milestone 1

Your software must support ABDM Milestone 1 before it joins NHCX. It creates an ABHA number through Aadhaar or a driving licence. It verifies an ABHA number or ABHA address at patient registration.

## Register on the NHCX sandbox

Register at <https://sandbox.abdm.gov.in/sandbox/v3/sandbox-registration> with your ABDM sandbox client ID and secret. When the form is submitted, NHCX sandbox roles are assigned to your client.

Decide your role before you create your participant. A wrong role and registry pair leads to access errors, rejected requests or misrouted messages.

| Role     | Role code | Registry | Registry code |
| -------- | --------- | -------- | ------------- |
| Provider | `10001`   | HFR      | `10001`       |
| Payer    | `10002`   | Payer    | `10004`       |
| TPA      | `10003`   | Payer    | `10004`       |

## Meet the dummy payer

A provider needs a payer to send requests to. The sandbox has one: the dummy payer, participant code `1000003538@hcx`.

| Use case                  | What you do                                                                                                                                                                      |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Coverage eligibility      | Send the check. It answers on its own.                                                                                                                                           |
| Insurance plan            | Send the request with provider id `32722` and policy number `100217` in the bundle. It answers on its own.                                                                       |
| Preauthorisation or claim | Send the submit, then choose its answer with the [dummy payer action call](/docs/nhcx/v1/api/adjudicator/endpoints/adjudicator-process-request): `Approve`, `Reject` or `Query`. |
| Payment notice            | Start it with the [payment notice trigger](/docs/nhcx/v1/api/adjudicator/endpoints/adjudicator-paymentnotice-init).                                                              |

The provider id and policy number apply to the dummy payer only. Codes such as `100001@sbx` and `1000002090@hcx` in examples show the format. Before you address any other code, look it up in [the participant list](/docs/nhcx/v1/api/registry/endpoints/registry-fetch-participants-list).

## What you see when it works

- A [session token call](/docs/nhcx/v1/getting-started/session-token) with your client ID and secret returns an access token.
- The NHCX sandbox registration form is submitted, and roles are assigned to your client.
- [Fetching the certificate](/docs/nhcx/v1/getting-started/fetching-a-recipient-certificate) of `1000003538@hcx` returns a PEM certificate.

## When it goes wrong

| What you see                                                    | What to do                                                                                                   |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| The sandbox application is still in review                      | Wait. A second application is filtered out as a repeat. Ask about a stalled request at the address below.    |
| "No user role found/associated for sender code."                | Your client has no NHCX role yet. Confirm the sandbox registration form went through, then write to support. |
| Participant creation fails the mobile number check              | The number must match the HFR record, or the payer record. Update the registry record first.                 |
| Requests are rejected or misrouted after registration           | Check the role and registry codes you registered with.                                                       |
| The dummy payer sends nothing after a preauthorisation or claim | It waits for the action call. Send it with the correlation ID of your submit.                                |

## Where to get help

| Topic                                                                                                                                                                                                           | Write to                         |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| Fast Healthcare Interoperability Resources (FHIR) bundle validation at sandbox exit, and the internal and [Health Tech Committee (HTC)](/docs/nhcx/v1/getting-started/glossary#identity-and-registration) demos | `hcx.integration@nha.gov.in`     |
| Building a FHIR bundle, and the [NRCeS](/docs/nhcx/v1/getting-started/glossary#organisations-and-programmes) specifications                                                                                     | `nrc-help@cdac.in`               |
| ABDM Milestone 1 integration                                                                                                                                                                                    | `integration.support@nha.gov.in` |
| Facility registration in the HFR                                                                                                                                                                                | `facility@nha.gov.in`            |

Put your participant code, the environment, the use case and the path in the message. Add the `x-hcx-correlation_id`, `x-hcx-api_call_id` and `x-hcx-timestamp` of the failing request. Quote the error exactly as returned. Replies have no fixed turnaround time.

## Next steps

- [Quickstart](/docs/nhcx/v1/getting-started/quickstart): your first three calls, with nothing but these credentials.
- [Base URLs](/docs/nhcx/v1/getting-started/base-urls): every address in the sandbox and in production.
- [Creating and Updating a Participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant): your own participant code.


---

# Glossary

The terms this documentation uses, in the sense it uses them. Where NHA's documents use a term differently from ordinary English, the NHA sense is given.

## Organisations and programmes

- **ABDM.** Ayushman Bharat Digital Mission. The national digital health programme under which NHCX is built.
- **SNOMED CT, ICD, LOINC.** The clinical, diagnosis and laboratory terminologies FHIR bundles carry, alongside the NRCeS value sets for claim-specific codes.
- **NHA.** National Health Authority. Publishes the NHCX specifications, runs the exchange, and administers PMJAY.
- **NRCeS.** National Resource Centre for EHR Standards, at C-DAC Pune. Publishes the FHIR profiles and value sets NHCX bundles must follow.
- **IRDAI.** Insurance Regulatory and Development Authority of India. Consulted on the specifications; the registry insurers and TPAs are identified by.
- **PMJAY.** Pradhan Mantri Jan Arogya Yojana, the Ayushman Bharat health assurance scheme. On NHCX it is a payer with scheme-specific rules.
- **SHA.** State Health Agency. Administers PMJAY in a state; under the trust model, the payer for that state.
- **TPA.** Third-party administrator. Processes claims on an insurer's behalf; on the network it behaves as a payer and is the processor for the policies it handles.
- **ISNP.** Insurance self-network platform; an insurance marketplace, a participant role with aggregated or consented data access.
- **BSP, EUA.** Beneficiary service provider, end-user application. A patient's personal health record app registered as a participant to receive notifications.

## PMJAY systems and roles

- **TMS.** Transaction Management System. NHA's provider and payer applications for PMJAY claims; the system an HMIS integration replaces on the provider side.
- **BIS.** Beneficiary Identification System. PMJAY's beneficiary register.
- **HEM.** Hospital Empanelment Module. PMJAY's hospital register; the HEM ID is mapped to the NHCX participant ID at go-live.
- **PPD.** Preauthorisation Processing Doctor. The payer-side role that adjudicates preauthorisations.
- **CPD.** Claim Processing Doctor. The payer-side role that adjudicates claims.
- **CRC.** Claim Review Committee. Decides appeals; its decision is final.
- **HBP.** Health Benefit Package. PMJAY's package master, from which a hospital's insurance plan is drawn.
- **STG.** Standard Treatment Guideline. A clinical protocol attached to a package, delivered as a questionnaire the provider must answer.

## Identity and registration

- **ABHA.** Ayushman Bharat Health Account. The beneficiary's health ID; sent without hyphens.
- **HFR.** Health Facility Registry. A hospital's registry; its HFR ID is the hospital's registry ID on the exchange.
- **NIN, ROHINI.** Other registries a participant may be identified by.
- **Registry ID.** A participant's identity in the registry it belongs to: HFR ID for a hospital, IRDAI ID for an insurer or TPA, client ID for an app.
- **Participant ID, participant code.** A participant's address on the exchange, in the form `1518@hcx`. The part after the `@` names the exchange instance.
- **Client ID and secret.** The ABDM sandbox credentials used to obtain an access token.
- **Milestone 1, M1.** The ABDM integration level, ABHA creation and verification, that must be complete before NHCX.
- **Bridge URL, endpoint URL.** The base address of a participant's callback server, registered on its participant record.
- **Passcode.** The one-time code sent to a participant's registered mobile to confirm creation or configuration in production.
- **Processor, `processingid`.** The participant that processes claims for a policy: the insurer itself or its TPA. The recipient of every claim-side message.
- **Payer ID, `payerid`.** The insurer's own participant code, named inside the bundle as the insurer.
- **Member ID.** The beneficiary's identifier on the policy.
- **NPI, NIIP.** Identifier types for a provider's HFR ID and a payer's registry ID inside a bundle.
- **WASA.** The security audit completed before ABDM production access.
- **HTC demo.** The demonstration before NRCeS, IRDAI, TCS and NHA that closes sandbox certification.

## Messages

- **JWE.** JSON Web Encryption. The sealed-envelope format every message uses.
- **JWT.** JSON Web Token. The format of the access token and of the signature the exchange puts on calls to a participant.
- **Envelope, protected header.** The readable part of a message: the `x-hcx-` fields and the encryption settings.
- **Letter, payload.** The FHIR bundle inside the envelope, encrypted for the receiver.
- **Domain headers.** A few facts written on the envelope for the exchange's records, such as an amount.
- **Correlation ID.** The number that ties a request and its answers into one conversation.
- **API call ID, request ID.** Fresh identifiers for one call and one request.
- **Workflow code, workflow ID.** The number in the envelope that says which step of the claim a message is.
- **Status word.** The `x-hcx-status` value: `request.initiated`, `response.partial`, `response.complete`, `response.error`, and the exchange's own `request.queued`, `request.dispatched`, `request.stopped`.
- **Receipt.** The `202 Accepted` body returned on taking a message in. Not a decision.
- **Protocol response.** A refusal returned on the callback with `response.error` and error details, when a message could not be opened or failed validation.
- **Callback.** The endpoint a participant hosts to receive answers and payer-initiated messages.
- **Dummy payer.** The sandbox payer, participant `1000003538@hcx`, that answers the provider exchanges listed in the NHCX Use Cases chapter.

## Claims

- **Preauthorisation, preauth.** Approval to treat, sought before treatment. A `Claim` with `use = preauthorization`.
- **Enhancement.** Additional procedures or days sought against an approved preauthorisation.
- **Resubmission.** A revised preauthorisation that replaces an earlier one.
- **Query.** The payer asking for more before it decides. The case stays open.
- **Claim.** The request for payment after discharge. A `Claim` with `use = claim`.
- **Adjudication.** The payer's decision on a preauthorisation or claim.
- **Reprocess.** An appeal against a rejection, raised as a Task.
- **Shortfall.** A request for the difference when a claim was paid short, raised as a Task after payment settles, under reason `partialpayment`.
- **Erroneous claim.** In the value set, a separate reason, `erroneousclaim`, for a reprocess caused by a mistaken submission by the provider. The FAQ uses the phrase for the shortfall case; the two senses coexist in the corpus.
- **Task.** The general-purpose request resource: plan fetch, cancel, reprocess, search, payment notice, acknowledgement, communication.
- **Communication.** A payer-initiated message outside the claim's own request-and-answer: a TAT alert, a grievance, a wallet or policy change, a request for information.
- **TAT.** Turnaround time. The window within which a payer is expected to act; under some policies, silence within it means approval.
- **Wallet.** The beneficiary's remaining cover under PMJAY, shared across the family.
- **Package.** A treatment with a fixed rate under a scheme; the unit a PMJAY claim is built from.
- **Stratification.** A higher bed category, such as ICU or HDU, allowed as an add-on over a package rate.
- **Implant.** A device allowed as an add-on over a package rate.
- **Unspecified procedure.** A treatment not in the package list, allowed under conditions with a free-text name and amount.
- **Cyclic procedure.** A treatment approved once and delivered over several visits, such as dialysis.
- **LAMA, DAMA.** Leave against medical advice, without informing the hospital; discharge against medical advice, with a signed undertaking. Two of the four discharge types, with `DTH` (home) and `DTM` (death).
- **LM100.** The single line item for a LAMA or DAMA stay before surgery, in place of the approved packages.
- **UTR.** Unique transaction reference. The bank's reference for a payment, carried on the payment reconciliation.
- **TDS.** Tax deducted at source, itemised on the payment reconciliation.


---

# The JWE message format

Every NHCX message is a JSON Web Encryption (JWE) token: a readable protected header and an encrypted FHIR bundle. This page lists every part, every header field and every value you set or receive. [JWE Secure Messaging](/docs/nhcx/v1/concepts/jwe-status-and-errors) explains the model in plain terms. [Building and sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe) walks through the first send.

## In short

- Seal with `RSA-OAEP-256` and `A256GCM`, in the compact serialisation of five parts.
- Encrypt with the recipient's public certificate, never your own.
- `api_call_id` is fresh on every message. `correlation_id` threads the conversation and is retired after a failure.
- Answer every delivery with `202` and a receipt within 30 seconds, and host `/v1/error`.

## The five parts

A JWE in compact serialisation is five base64url strings joined by dots.

| Part                     | What it holds                                                           | Readable by the exchange |
| ------------------------ | ----------------------------------------------------------------------- | ------------------------ |
| 1. Protected header      | The envelope: algorithms and every `x-hcx-` field                       | Yes                      |
| 2. Encrypted key         | The one-time content key, encrypted with the recipient's RSA public key | No                       |
| 3. Initialisation vector | A random value for AES-GCM, new per message                             | Not useful alone         |
| 4. Ciphertext            | The FHIR bundle, encrypted with the content key                         | No                       |
| 5. Authentication tag    | The GCM tag over the ciphertext and the protected header                | Not useful alone         |

The request body is a JSON object with one field.

```json
{ "payload": "<header>.<encrypted key>.<iv>.<ciphertext>.<tag>" }
```

## Algorithms

| Setting                   | Send                                                 | Note                                                                                                     |
| ------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Key wrapping, `alg`       | `RSA-OAEP-256`                                       | The handbook, samples and Postman collection agree. One protocol page says `RSA-OAEP`; it is outnumbered |
| Content encryption, `enc` | `A256GCM`                                            | Uncontested in the samples                                                                               |
| Serialisation             | Compact, five parts                                  | The message-security page says flattened JSON. The FAQ, the handbook and every sample use compact        |
| Recipient key             | The recipient's public certificate from the registry | See [Fetching a recipient certificate](/docs/nhcx/v1/getting-started/fetching-a-recipient-certificate)   |

### Sealing, step by step

1. Serialise the FHIR bundle as JSON.
2. Build the protected header and base64url encode it.
3. Generate a random 256-bit content key and a 96-bit initialisation vector.
4. Encrypt the content key with the recipient's public key using RSA-OAEP with SHA-256.
5. Encrypt the bundle with AES-256-GCM, using the encoded header as additional authenticated data.
6. Join header, encrypted key, IV, ciphertext and tag with dots.

### Opening, step by step

1. Split the token on the dots and decode the header.
2. Confirm `x-hcx-recipient_code` is your participant code.
3. Decrypt the encrypted key with your private key to recover the content key.
4. Decrypt the ciphertext with AES-256-GCM. A tag mismatch means the header or body changed, and the message must be refused.
5. Parse and validate the FHIR bundle.

A JOSE library does all of this: `jose` on Node, `jwcrypto` on Python, Nimbus on Java, `jose-jwt` on .NET. Do not implement the steps by hand.

## Protected header fields

Every NHCX header name starts with `x-hcx-`. A full header for a new preauthorisation:

```json
{  "alg": "RSA-OAEP-256",  "enc": "A256GCM",  "x-hcx-sender_code": "1000004446@hcx",  "x-hcx-recipient_code": "1000003538@hcx",  "x-hcx-api_call_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",  "x-hcx-request_id": "f0e1d2c3-b4a5-4978-8fed-cba987654321",  "x-hcx-correlation_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",  "x-hcx-workflow_id": "12",  "x-hcx-timestamp": "2026-09-04T11:46:34+05:30",  "x-hcx-status": "request.initiated",  "x-hcx-ben-abha-id": "91123456781234",  "x-hcx-use_case": "New"}
```

| Field                  | Type        | Obligation | What it carries                                                                                                         |
| ---------------------- | ----------- | ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| `alg`                  | String      | Mandatory  | Key wrapping. `RSA-OAEP-256`                                                                                            |
| `enc`                  | String      | Mandatory  | Content encryption. `A256GCM`                                                                                           |
| `x-hcx-sender_code`    | String      | Mandatory  | Your participant code                                                                                                   |
| `x-hcx-recipient_code` | String      | Mandatory  | The recipient's code. For a provider, the processor code from the policy lookup, not the insurer's                      |
| `x-hcx-api_call_id`    | UUID        | Mandatory  | Fresh on every message, including responses                                                                             |
| `x-hcx-request_id`     | UUID        | Optional   | One per originating request. Send it anyway, as a fresh UUID per originating request                                    |
| `x-hcx-correlation_id` | UUID        | Mandatory  | The conversation thread. See the rule below                                                                             |
| `x-hcx-workflow_id`    | String      | Optional   | The step code, for example `12` for a new preauthorisation. See [Workflow codes](/docs/nhcx/v1/concepts/workflow-codes) |
| `x-hcx-timestamp`      | datetime    | Mandatory  | When the message was sent. See the format below                                                                         |
| `x-hcx-status`         | String      | Mandatory  | Where this message stands. Values below                                                                                 |
| `x-hcx-ben-abha-id`    | String      | Optional   | The beneficiary's ABHA number, when the beneficiary has one                                                             |
| `x-hcx-use_case`       | String      | Optional   | `New`, `Enhancement` or `Resubmit` on preauth and status. `New` or `Resubmit` on claim                                  |
| `x-hcx-error_details`  | JSON object | Optional   | `code`, `message`, `trace`. Mandatory on a protocol response                                                            |
| `x-hcx-debug_details`  | JSON object | Optional   | The same shape, for debugging                                                                                           |
| `x-hcx-debug_flag`     | Enum        | Optional   | The specification lists `Error`, `Info` and `Debug`; the samples send `INFO`. A server may ignore it                    |

Three field rules catch people out.

- **Request ID.** `x-hcx-request_id` is optional here and mandatory on the Open Protocol page. Send it on every message, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules on which one stands.
- **ABHA number format.** Inside the bundle it is 14 digits without hyphens. The published header sample also sends 14 digits, but the gateway's refusal `NHCX-1018` asks for `XX-XXXX-XXXX-XXXX`. Store the digits once and format them where you build the header.
- **Workflow code.** Send the step code where the Workflow Status Sheet gives one. Leave it out where it does not, for example on eligibility, insurance plan, search and status.

[Envelope fields](/docs/nhcx/v1/reference/envelope-fields) records where each obligation comes from and where sources disagree.

### Domain headers

A few facts may be written on the envelope for the exchange's audit trail. The format is `x-hcx-<use_case_name>-<parameter_name>`. The use case name is under 16 characters and the parameter name under 32. Named examples in use:

- `x-hcx-amount_submitted`
- `x-hcx-benefit-category_type`
- `x-hcx-benefit_code`
- `x-hcx-action`

The eObjects page adds a `Usage` header on the Claim carrying `preauthorization` or `claim`. An insurance marketplace must carry the beneficiary's consent in a domain header before it may receive individual claim data. Send none to a payer that has not asked for one.

## Identifiers and the correlation rule

Three identifiers are UUIDs.

| Identifier       | Scope                                                        |
| ---------------- | ------------------------------------------------------------ |
| `api_call_id`    | New on every message, request or response                    |
| `request_id`     | New per originating request                                  |
| `correlation_id` | One per conversation, shared by the request and every answer |

| On a                         | Set `correlation_id` to                                            |
| ---------------------------- | ------------------------------------------------------------------ |
| Request                      | This message's own `api_call_id`                                   |
| Response                     | The `correlation_id` of the request being answered                 |
| Status enquiry, `/v1/status` | The `api_call_id` of the message whose status you are asking about |

- On a response, `api_call_id` and `correlation_id` are different values.
- A correlation ID that failed at the exchange, or whose delivery stopped, is retired. A retry needs a fresh `api_call_id` and a fresh `correlation_id`. Reusing one earns `NHCX-1006`, duplicate request, or is silently dropped.

## Timestamp

Send ISO 8601 with `+05:30`, as every sample bundle does. Accept a Unix epoch on the way in.

The sources disagree on this field:

- The workbook types it as a Unix timestamp, with `1706308383` as its example.
- The handbook says Indian time, and that UTC fails validation.
- The FAQ says UTC with a trailing `Z`.

The reference payer refuses a timestamp more than 24 hours behind the current time, with `PAYR-1005`. The ABDM session call is separate: its `TIMESTAMP` header is UTC with a trailing `Z` and milliseconds.

## Status values

```mermaid
sequenceDiagram
  participant P as Provider
  participant Y as Payer
  P->>Y: 12, request.initiated: new preauthorisation
  Y-->>P: 20, response.partial: received
  Y->>P: 24, request.initiated: query, payer now initiates
  P-->>Y: 19, response.complete: query answered
  Y-->>P: 21, response.complete: approved
```

| Value                | Sent by       | Meaning                                                         |
| -------------------- | ------------- | --------------------------------------------------------------- |
| `request.initiated`  | The initiator | Starting a request cycle                                        |
| `request.queued`     | The exchange  | Passed header validation and waiting in the dispatch queue      |
| `request.dispatched` | The exchange  | Delivered to the recipient's callback                           |
| `request.stopped`    | The exchange  | Delivery abandoned after retries. The correlation ID is retired |
| `response.partial`   | The responder | Received and working on it, or an interim answer                |
| `response.complete`  | The responder | The final answer, closing the cycle                             |
| `response.error`     | The responder | The message was refused                                         |

The status pairs with the workflow code: the code says which step, the status says where that step stands. A preauthorisation's life:

| Who sends | Workflow code | Status              | Meaning                                      |
| --------- | ------------- | ------------------- | -------------------------------------------- |
| Provider  | 12            | `request.initiated` | New preauthorisation                         |
| Payer     | 20            | `response.partial`  | Received, under review                       |
| Payer     | 24            | `request.initiated` | Query raised. The payer is now the initiator |
| Provider  | 19            | `response.complete` | Query answered                               |
| Payer     | 21            | `response.complete` | Approved                                     |

The Open Protocol page lists a different set: `request.initiate`, `request.retry`, `response.success`, `response.fail`, `response.sender_not_supported`, `response.unhandled` and `response.request_retry`. None appears in the workflow sheet, any sample or the gateway's validation. It is a superseded draft; do not build against it.

## The receipt

Whoever receives a message, the exchange or your callback, answers at once with `202 Accepted` and this receipt.

```json
{  "timestamp": "04/09/2026 11:46:35:120",  "api_call_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",  "correlation_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",  "result": {    "sender_code": "1000004446@hcx",    "recipient_code": "1000003538@hcx",    "entity_type": "preauth",    "protocol_status": "request.queued"  },  "error": { "code": "", "message": "" }}
```

- `protocol_status` is `request.queued`, `request.dispatched` or `request.error`.
- `entity_type` comes from the path: the second to last segment, or the last where that is `v1`, with `on_` stripped.
- The receipt's `timestamp` is written day first, as `DD/MM/YYYY HH:mm:ss:SSS`. That form belongs to the receipt only. The `x-hcx-timestamp` header still takes ISO 8601 with `+05:30`, as [Timestamp](#timestamp) sets out.
- Your callback must return exactly this receipt within 30 seconds. Anything else, including a slow `200`, counts as a failed delivery.

The receipt is not the decision. It says only that the message was taken in.

## Errors

| Where it fails                                                                                   | Who refuses   | How the sender hears                                                     |
| ------------------------------------------------------------------------------------------------ | ------------- | ------------------------------------------------------------------------ |
| Envelope: missing header, unknown recipient, expired token, bad status                           | The exchange  | At once: `400` for validation, `401` for the token                       |
| Letter: cannot decrypt, or the bundle fails validation                                           | The recipient | Later, as a protocol response on the callback                            |
| Delivery: the callback never returned a valid receipt                                            | The exchange  | On the sender's `/v1/error` endpoint                                     |
| Business: not covered, an active preauthorisation already open, balance too low, duplicate claim | The payer     | Later, inside a sealed answer on the callback, usually as a `PAYR-` code |

A **protocol response** carries the same envelope fields with `x-hcx-status` set to `response.error` and a `code`, `message` and `trace` in `x-hcx-error_details`. The exchange logs its header for audit. Business refusals, such as "not covered", travel inside a sealed answer instead.

**Retries.** If a callback does not return a proper receipt, the exchange tries five times, moves the message to `request.stopped` and retires the correlation ID. It then reports the failure on `/v1/error`, which every participant must host.

`NHCX-1010`, *no data with given correlation id for call back request*, is what a payer hears when it answers a submission too late. Acknowledge a submission at once with a `ClaimResponse` whose `outcome` is `queued`, then send the decision later on the same correlation ID.

### Codes met live

Several payer codes mean something other than their message suggests. From the September 2026 sandbox run:

| Code                     | The message                                                                                       | Cause                                                                                                                                                                      | What to do                                                                                                                                                                                         |
| ------------------------ | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PAYR-1027`              | Invalid item id found for item in claim component                                                 | `Claim.item` has no FHIR element `id` (`Item/1`). Nothing to do with the package code                                                                                      | Give every `Claim.item` an element `id`, then send again. `PAYR-1028` (item sequence) and `PAYR-1029` (bundle id) are the same kind of fault                                                       |
| `PAYR-1083`              | No HPR details found for the practitioner … category code as HPIN                                 | The `Practitioner` carries no identifier typed `HPIN`                                                                                                                      | Add the HPR id as an identifier typed `HPIN` from the NRCeS `ndhm-identifier-type-code` system. [PMJAY sandbox run](/docs/nhcx/v1/roles/provider/pmjay-sandbox-run) shows the full identifier list |
| `PAYR-1238`              | Beneficiary is having an active preauthorization request at this hospital with reference number … | Scheme rule, not a bundle fault: one live preauthorisation per beneficiary per hospital. The reference number ends in the SHA's case id                                    | Cancel the open preauthorisation with a cancel Task on workflow `PC01` from the hospital that raised it, or raise the claim that goes with it                                                      |
| `PAYR-1401`              | Policy not allowed for the hospital                                                               | The plan was asked for under a policy the hospital is not empanelled under                                                                                                 | Ask again under the beneficiary's policy code from the eligibility answer                                                                                                                          |
| `PAYR-1019`              | Invalid sequence received in supporting info element                                              | A `supportingInfo` entry with no `sequence`, typically one appended after the rest were numbered                                                                           | Number the whole list once it is assembled                                                                                                                                                         |
| `PAYR-1256`, `PAYR-1363` | Response for Authentication Consent Questionnaire is missing                                      | The plan's consent questionnaire, unanswered, where no biometric token was taken. `PAYR-1256` is at the preauthorisation, `PAYR-1363` at the claim                         | Answer the questionnaire named in the package master as a `QuestionnaireResponse`, referenced from a supporting-info entry of category `INF`, code `ODN`                                           |
| `PAYR-1008`              | Invalid content type … / Invalid input, code and reason code …                                    | Two of fifteen uncoded texts all sent as `PAYR-1008`: a document outside pdf, jpg, jpeg, png and fhir+json, or a Task code paired with a reason the scheme does not accept | Attach only those five content types, and pair each Task code with a reason the scheme accepts. [Reading error codes](/docs/nhcx/v1/reference/error-code-guide) lists all fifteen                  |
| `PAYR-1245`              | Only one conservative procedure can be booked for a case                                          | The master's `ProcedureType`: the enhancement added a second `Conservative` package                                                                                        | Add a `Medical` package or an enhanceable add-on instead                                                                                                                                           |
| `ERR-PYR-CLM-007`        | No prior preauthorization or claim record found for case number                                   | The claim was sent under a case number of its own instead of the preauthorisation's                                                                                        | Send the claim under the preauthorisation's case number, in the `Claim` identifier. If no preauthorisation exists, submit one first. Resend with a fresh correlation ID                            |
| `PAYR-1322`              | Active instance found for case number                                                             | A request is already open on that case; the scheme takes one at a time                                                                                                     | Wait for the decision on the open request before sending the next                                                                                                                                  |

A refusal in the `PAYR-102x` block is structural, so check ids and sequences before values. The SHA validates the bundle before applying scheme rules, so `PAYR-1238` is the first sign the bundle itself is right. Every code is in [Error codes](/docs/nhcx/v1/reference/error-codes).

## Common mistakes

1. Wrong status value for the leg of the message.
2. No `/v1/error` endpoint, so failures go unnoticed.
3. Answering a callback with something other than `202` and the receipt.
4. Missing or malformed envelope headers.
5. In production, the wrong registry ID: providers send the HFR ID, payers the IRDAI ID without leading zeros.
6. Forgetting the `Accept: application/json` header.
7. Addressing the insurer's code instead of the processor's.
8. Reusing a correlation ID, especially after an error.
9. Retrying on a `401` with the same expired token instead of fetching a new one.
10. Trying to de-link a policy from a participant that did not link it.
11. Sealing with your own certificate, or a stale one, instead of the recipient's.


---

# NHCX adapter (Optional)

Everything in the nine chapters before this one is work you do once and then maintain for ever:

- Minting a token and refreshing it.
- Fetching the recipient's certificate and caching it.
- Filling in nine envelope headers correctly, and sealing the bundle.
- Hosting a dozen or more callback paths, and answering each one with a receipt in the right shape inside thirty seconds.
- Noticing when the same message arrives twice.

The NHCX Adapter does all of it for you. It is a single binary that sits between your hospital or payer system and the exchange. Your system speaks plain JSON and plain FHIR to it over your own network; it speaks the protocol to NHCX. Nothing else about your system has to change.

Read this chapter after the rest of Getting Started rather than instead of it. The adapter hides the protocol, it does not abolish it, and when something goes wrong the error you get back is a protocol error.

## What it does

```mermaid
flowchart LR
  HMIS[Your system] -->|plain FHIR| A[Adapter]
  A -->|sealed| X((NHCX))
  X -->|sealed| A
  A -->|plain FHIR| HMIS
  A -.->|certificates, token| R[Participant registry]
```

Three jobs, and they map onto the three hard parts of the protocol.

**Send.** You post a FHIR bundle and the recipient's code. It completes the envelope headers, fetches the recipient's certificate, encrypts, posts to NHCX, and hands you back the exchange's answer on the same call.

**Deliver.** NHCX posts a sealed message to it. It decrypts with your private key, posts the plain bundle to a URL of yours, and only then answers NHCX with the receipt the protocol requires.

**Certificates.** It fetches and caches the certificates of everyone you talk to, and can generate and register your own.

## What it does not do

Worth knowing before you plan around it.

- **It does not queue or retry.** Both directions are synchronous. If your callback is down, NHCX is told, and NHCX redelivers up to five times before dropping the correlation ID. The only retry inside the adapter is a single token refresh after a `401`.
- **It does not build or validate bundles.** It checks that what you sent is valid JSON and nothing more. Everything in the FHIR Reference section is still yours to get right.
- **It has no business logic.** No adjudication, no policy modelling, no screens for claims work. The participant and policy calls are passed straight through.
- **It does not verify who sent an inbound message** beyond the fact that it decrypts with your key.

## Download

Take a prebuilt release rather than building it. Pick your operating system and architecture; the list comes from the latest release on GitHub. Each archive holds the binary, the README, a sample configuration and start, stop and update scripts for that platform.

Reading the latest release…

Check the archive against `SHA256SUMS` before you run it. Once it is installed, `nhcx-adapter update` moves between releases, forward or back, and verifies each one the same way.

### Run it with Docker

The adapter is also published as a container image, `ghcr.io/nha-in/nhcx-adapter`, for Linux on amd64, arm64, arm, 386, ppc64le, s390x and riscv64. It reads its settings from the environment and keeps its key, certificate and ledger in the `/data` volume.

Put your settings in a file called `.env`:

```bash
NHCX_ENV=sandboxNHCX_PARTICIPANT_ID=1000003463@hcxNHCX_CLIENT_ID=your-client-idNHCX_CLIENT_SECRET=your-client-secretNHCX_CALLBACK_URL=https://your-hmis.example.org/nhcx/callback
```

Create the key and certificate once, then start it:

```bash
mkdir -p datadocker run --rm --env-file .env -v "$PWD/data:/data" ghcr.io/nha-in/nhcx-adapter:main cert generatedocker run -d --name nhcx-adapter --env-file .env -v "$PWD/data:/data" -p 8090:8090 ghcr.io/nha-in/nhcx-adapter:maindocker logs -f nhcx-adapter
```

The image runs as user 10001, so on Linux the `data` folder must be writable by it: `sudo chown -R 10001:10001 data`. The registry currently carries the `:main` tag, built from every push to the main branch, and a `:sha-<commit>` tag for each build. Pin a `:sha-` tag in production so an update is a deliberate change. Inside a container, `nhcx-adapter update` does not apply: pull a newer tag instead.

## Onboarding

### Before you start

You need a participant code such as `1000003463@hcx`, and the client ID and secret issued when you registered on the ABDM sandbox. If you want to receive callbacks, you also need a public HTTPS address that reaches the machine you will run this on.

### Build it from source

```bash
make build     # produces ./nhcx-adaptermake check     # what the project's own CI runs: vet plus tests with the race detector
```

It is a Go program with no C dependencies, so the binary is self-contained. To skip building, take a release from [Download](#download) above.

### Make a key and a certificate

```bash
./nhcx-adapter config init          # writes config.json; refuses to overwrite one./nhcx-adapter cert generate        # after setting participantId in the config
```

This writes a 2048-bit RSA private key to `private_key.pem` with owner-only permissions and a self-signed certificate to `certificate.pem`. The certificate's common name is your participant code, which is why the code has to be in the config first. It refuses to overwrite an existing pair, so add `--force` when you mean to replace one, which renames the old files rather than deleting them. It dates the certificate five minutes in the past so a registry with a slightly different clock still accepts it.

### Register the certificate and your address

Register `certificate.pem` as the participant's encryption certificate, and your public address as its endpoint, exactly as described in Creating and Updating a Participant. The adapter can do both itself from its startup repair menu, but only if the client ID you are using is the one that created the participant record. If it is not, the registry answers that you are not authorised to modify the details, and the fix is out of band.

Register the address with `/in` on the end, or the host root. The adapter answers its health check under both.

### Fill in the configuration

```bash
./nhcx-adapter config edit
```

An arrow-key form over the whole file. It edits the JSON document in place, so environment-variable references and file references survive editing, and it validates as you type, including checking that your key file exists and parses. Arrow keys move and cycle values, Enter edits, Backspace resets a field to its default, Ctrl+S saves.

Two conveniences make it safe to keep the file in version control. A value written as `${NAME}` is read from the environment, and a missing variable is a startup error naming every one that is missing. A value written as `@filename` is read from that file, relative to the config. That works for the private key. Elsewhere the string is used exactly as written, so an `@` in the API key or the console password is part of the password. So the key is normally `"@private_key.pem"` and the secret is normally `"${NHCX_CLIENT_SECRET}"`.

Unknown keys are rejected outright, so a typo in a field name stops the adapter rather than being silently ignored.

### Check it

```bash
./nhcx-adapter check
```

Five checks, in order, with a line each:

1. **Session token.** Your credentials mint a token at the sessions endpoint.
2. **Participant record.** Your code exists in the registry, with the name and endpoint it holds.
3. **Encryption certificate.** The certificate the registry holds for you matches the private key in your config. This is the check that catches the single most common cause of the other side being unable to read anything you send.
4. **Local listener.** The adapter's own port accepts connections.
5. **Registered endpoint.** This one is worth understanding. It starts the listener, then calls your registered public address from the outside and asks it to sign a random number. Only this adapter, running with this configuration, can produce the right answer. So it distinguishes three different failures: nothing is forwarding to the adapter at all, something is forwarding to a different adapter, and the address answers but not with a success.

Only the token failure is fatal. A certificate mismatch opens a menu offering to generate a new pair and upload it, upload the certificate for the key you already have, or continue anyway. An endpoint failure offers to register the address from your config, or one you type.

`nhcx-adapter serve` runs the same checks and then listens, so in normal use you never run `check` separately.

### Prove it works

```bash
./nhcx-adapter token                                    # a fresh session token./nhcx-adapter cert 1000004805@hcx                      # someone else's certificate./nhcx-adapter send --path v1/coverageeligibility/check \                    --recipient 1000004805@hcx --file bundle.json
```

The command line send and the server share one code path, so a send that works means the server will work.

## The configuration file

The fields you will actually set. Everything has a working default except the four marked required.

| Field                       | Meaning                                                                                                              |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `env`                       | `sandbox` or `production`. Chooses the gateway, registry and sessions addresses, and flips several security defaults |
| `listen`                    | Address and port to listen on. Defaults to loopback only                                                             |
| `publicUrl`                 | How NHCX reaches you from outside. Offered to the registry as your endpoint                                          |
| `apiKey`                    | The key your own system must present. Required in production; off by default in sandbox                              |
| `participant.participantId` | **Required.** Your participant code                                                                                  |
| `participant.clientId`      | **Required.** From onboarding                                                                                        |
| `participant.clientSecret`  | **Required.** From onboarding                                                                                        |
| `participant.privateKey`    | **Required.** The key matching your registered certificate, normally `@private_key.pem`                              |
| `callback.url`              | Where decrypted messages are posted in your system                                                                   |
| `callback.appendPath`       | Whether the NHCX path is added to that URL. On by default                                                            |
| `callback.timeoutSeconds`   | How long one delivery may take. Twenty by default, against the protocol's thirty-second limit                        |
| `callback.routes`           | Per-path overrides, used exactly as written                                                                          |
| `callback.also`             | Extra destinations that all receive the same message                                                                 |
| `auth.mode`                 | `sessions` or `get-session`. See the warning below                                                                   |
| `ledger.storeBodies`        | Set false to record headers and outcomes but keep no patient data on disk                                            |
| `panel.password`            | Enables the browser console. At least eight characters                                                               |

A second block, `participants`, holds additional identities on the same adapter, each with its own code, credentials, key and callback. Inbound, the recipient code on the envelope picks which one receives. Outbound, the sender code picks which one sends. It is edited by hand; the form preserves it but does not edit it.

### Two settings to get right before production

**`auth.mode`.** The two ways of getting a token, described in Session Token, are both implemented, and the project's own README says the NHA documents disagree about which applies. There is no autodetection. Confirm with your onboarding contact, because the wrong choice fails at the first call with a token error.

**The production addresses.** The sandbox addresses are verified. The production ones follow the documented pattern of swapping the sandbox hostnames, and the code says as much in a comment. Check all four against your onboarding letter and override them in the config if they differ.

## Sending

One route, and the NHCX path is the exchange.

```bash
curl -s http://127.0.0.1:8090/out/v1/preauth/submit \  -H "Authorization: Bearer $NHCX_ADAPTER_API_KEY" \  -H 'Content-Type: application/json' \  -d '{"recipient": "1000004805@hcx", "fhir": { "resourceType": "Bundle", "...": "..." }}'
```

Response:

```json
{ "ok": true,  "path": "v1/preauth/submit",  "headers": { "x-hcx-correlation_id": "...", "x-hcx-api_call_id": "..." },  "gateway_status": 202,  "response": { "...": "the exchange's receipt" },  "correlation_id": "...",  "ledger_id": "7UMV0007" }
```

Keep the correlation ID. It is how you will recognise the answer when it arrives.

**Sending a response** rather than a request means posting to the matching `on_` path. The status word defaults correctly and the message type is set for you. The one thing the adapter cannot infer is which request you are answering, so a response should carry the original correlation ID. As a convenience, a response sent without one is threaded onto the most recent inbound request of the same kind from that participant, but do not rely on that when you can pass it.

If a failure happens the answer says so plainly, with the exchange's own status and body underneath, and a code that tells you whether retrying is worthwhile.

## Receiving

NHCX posts to `/in/` plus the path, or to `/v1/` plus the path, so a registry entry pointing at your host root works. These routes are not protected by your API key, because NHCX is the caller.

The adapter decrypts and posts this to your callback:

```json
{ "meta": { "type": "in", "payloadType": "fhir", "path": "v1/preauth/on_submit",            "redelivery": false, "participant": "1000003463@hcx" },  "jwe_headers": { "x-hcx-sender_code": "...", "x-hcx-correlation_id": "...", "x-hcx-status": "..." },  "fhir": { "resourceType": "Bundle", "...": "..." } }
```

Useful facts about that delivery, all of which affect how you write the receiving end.

- **Your answer is what NHCX is told.** The adapter waits for your 2xx and only then sends the receipt. A non-2xx from you becomes a failure to NHCX, which retries.
- **Your callback must be idempotent.** The retry means the same message can arrive several times. The call identifier stays the same across those attempts, and a repeat is flagged both in the body and in a header, so you can recognise one.
- **A protocol message arrives on the same routes** with no sealed payload, marked as a protocol message rather than a bundle. That is how a refusal or a delivery failure reaches you.
- **A message addressed to a code you do not hold is refused** with an error naming every code this adapter does hold, which is usually enough to spot the misconfiguration.

A callback address is not optional: the adapter refuses to start without one. What the ledger gives you instead is a way to poll for what has already arrived, including the whole thread for one correlation ID. That is useful when your receiving end is down and you are catching up.

## Watching what happens

Every message in both directions is written to a file ledger, one file per message plus a daily index. No database. Identifiers sort chronologically as plain strings, so `7UMV0007` came before `7UMV0008`.

```bash
nhcx-adapter ledger follow                      # live, one coloured line per messagenhcx-adapter ledger list --since 24h --entity preauth --status rejectednhcx-adapter ledger show 7UMV0007nhcx-adapter ledger thread <correlation-id>     # the whole conversationnhcx-adapter ledger stats
```

The live view reads the files directly, so it works from another terminal, another shell, or a machine with the directory mounted, and it needs nothing running locally. Each line carries the identifier, the direction, the path, the counterparty, the outcome, the other side's status code and how long it took.

A thread view is the thing to reach for when a case has gone quiet. It states plainly whether you are waiting for them or they are waiting for you.

Setting `ledger.retentionDays` prunes old days hourly. Note that the field defaults to keeping everything if you leave it out of a hand-written config, which is not what the sample file implies.

There is also a browser console, off unless you set a password, with a live view, the ledger, a send form and a participant lookup.

## Running it

One port carries everything. Timeouts are set conservatively: thirty seconds on requests, twenty on a callback delivery against the protocol's thirty-second budget, thirty on calls out to the exchange.

Put it behind a reverse proxy for TLS, forwarding your public path to the adapter's port, and set `publicUrl` to match. If you expose the console, proxy it on the same path, because its session cookie is scoped to that path, and turn response buffering off so the live view streams.

It refreshes every session token a minute before expiry in the background, prunes the ledger hourly, and drains for thirty seconds on shutdown. Bodies and tokens are never written to the log.

## Before you expose it

Three things to settle, because the defaults are tuned for a sandbox on a laptop.

**The compatibility routes under `/internal/` have no authentication at all.** Among them are routes that list recent traffic and return a full decrypted bundle for any record. Others proxy to the participant service using your session token. On an adapter bound only to loopback this does not matter. On one bound to all interfaces it is patient data and a credentialed proxy, readable by anyone who can reach the port. Bind to loopback, or keep the port off any network you do not control.

**In sandbox the API key is not demanded by default.** Anything that can reach the port can send messages as you. Setting `requireApiKey` to true turns the check on regardless of environment, and production turns it on anyway.

**Readiness reflects the first identity only.** If you host several participants, a broken credential on a second one still reports ready.

## What this chapter does not replace

The adapter removes the protocol work. It does not remove the need to understand what you are sending. Which bundle, which workflow code, which supporting information, which status word, and what the payer's answer means are all still yours, and they are the subject of the rest of this documentation.


---

# Quickstart

Make your first three National Health Claims Exchange (NHCX) calls with nothing but your sandbox credentials. You get a session token, look up the dummy payer in the participant registry, and fetch the certificate you would seal its messages with.

## In short

- Three calls, in order: session token, participant search, fetch certificate.
- None of them changes anything and none has a callback, so you need no server yet.
- The two registry calls carry the token in `bearer_auth`, with `Bearer` and a space in front.
- The counterparty is the sandbox [dummy payer](/docs/nhcx/v1/getting-started/glossary#messages), `1000003538@hcx`.

## Prerequisites

- An [ABDM](/docs/nhcx/v1/getting-started/glossary#organisations-and-programmes) sandbox client ID and client secret, with NHCX sandbox roles assigned. [Get your sandbox credentials](/docs/nhcx/v1/getting-started/get-your-sandbox-credentials) if you do not have them.
- A terminal with `curl`, and a way to generate a universally unique identifier (UUID).
- A clock synchronised with NTP, because the session call carries the current time.

## Get a session token

```bash
curl --location --request POST 'https://dev.abdm.gov.in/api/hiecm/gateway/v3/sessions' \  --header 'Content-Type: application/json' \  --header 'REQUEST-ID: <uuid>' \  --header 'TIMESTAMP: <iso timestamp>' \  --header 'X-CM-ID: sbx' \  --data-raw '{    "clientId": "<client id>",    "clientSecret": "<client secret>",    "grantType": "client_credentials"  }'
```

[Session token in the API reference](/docs/nhcx/v1/api/session/endpoints/session-api-hiecm-gateway-v3-sessions)

- `<client id>` and `<client secret>`: your ABDM sandbox client ID and client secret.
- `<uuid>` in `REQUEST-ID`: a fresh UUID you generate for this call. Generate a new one on every call.
- `<iso timestamp>` in `TIMESTAMP`: the current UTC time with milliseconds and a trailing `Z`, such as `2026-09-04T06:15:51.975Z`.

You receive HTTP `200` with a non-empty `accessToken` and `expiresIn` set to `1200`. The token lasts 1200 seconds (20 minutes) from the moment it arrives. Keep it for the next two steps.

## Look up the dummy payer

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/participant/search' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "participant_code": "1518@hcx"  }'
```

[Participant search in the API reference](/docs/nhcx/v1/api/registry/endpoints/registry-participant-search)

- The sample body carries `1518@hcx`. Replace it with the code of the participant you are looking up. For the sandbox dummy payer, that is `1000003538@hcx`.
- `<access token>`: the `accessToken` from step 1.

You receive HTTP `200` with a `participants` array. Its entry carries the code you sent, its roles and its status. A participant is ready to receive messages when its status is `Active`, and its `endpoint_url` and `encryption_cert` are filled.

## Fetch its certificate

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice/fetch/certs' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "participantid": "1518@hcx"  }'
```

[Fetch certificate in the API reference](/docs/nhcx/v1/api/registry/endpoints/registry-fetch-certs)

- The sample body carries `1518@hcx` in `participantid`. Replace it with the code you looked up in step 2, `1000003538@hcx` for the dummy payer.
- `<access token>`: the same `accessToken` from step 1, in the same header.

You receive HTTP `200` with PEM text in `encryption_cert`. Some participants register a bare SubjectPublicKeyInfo (SPKI) public key rather than a full X.509 certificate. Import the value as an X.509 certificate first, and fall back to SPKI if that fails.

## What you have now

A token that every NHCX call accepts, a counterparty you know is on the network, and the key that seals its messages. Those are items 1, 4 and 5 of [the base framework](/docs/nhcx/v1/getting-started/the-base-framework).

## When it goes wrong

| What you see                       | Cause                                                                          | What to do                                                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| The session call is refused        | `grantType` missing, `REQUEST-ID` reused, or `TIMESTAMP` from a drifting clock | Fix all three and call again                                                                                     |
| `401` on step 2 or 3               | The token expired, or went out without the `Bearer `prefix                     | Get a fresh token and retry once                                                                                 |
| `400` or an empty result on step 2 | The body used `participantid`                                                  | This call takes `participant_code`                                                                               |
| `400` or no certificate on step 3  | The body used `participant_code`                                               | This call takes `participantid`                                                                                  |
| No entry for the code              | The code is wrong or not registered                                            | Pick it again from [the participant list](/docs/nhcx/v1/api/registry/endpoints/registry-fetch-participants-list) |

## Next steps

- [Your Certificate](/docs/nhcx/v1/getting-started/your-certificate): make your own key pair, the counterpart of the one step 3 fetched.
- [Creating and Updating a Participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant): register your certificate and callback address.
- [Building and Sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe): seal a message with the certificate from step 3.


---

# Receiving a callback

Every answer on the exchange arrives at your server, not in the response to your call. This chapter builds the endpoint that receives it, and closes the loop opened in the previous one.

## What to host

Under the `endpoint_url` you registered, the exchange will POST to a path per use case. For a provider that starts with:

```text
/v1/coverageeligibility/on_check/v1/insuranceplan/on_request/v1/preauth/on_submit/v1/claim/on_submit/v1/search/on_submit/v1/communication/request/v1/paymentnotice/request/v1/task/on_submit/v1/on_status/v1/error
```

A payer hosts the mirror set, the `submit` and `check` sides. Both host `/v1/error`; it is where the exchange reports a message it could not deliver after five attempts, and without it you never find out.

Build one handler and route by path. The body shape and the steps are the same for all of them except `/v1/error`, which is described below.

## Rules for the address

- A domain name, over HTTPS with TLS 1.2 or newer. Not an IP address, not a port number.
- Hosted in India.
- Reachable from the exchange's outbound addresses: allow `3.109.99.210`, `13.126.152.0` and `13.200.129.223` through the firewall.
- Answering within 30 seconds. Anything slower is treated as a failed delivery and retried.

## What arrives

A POST with a JSON body of two fields:

```json
{ "type": "JWEPayload", "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYi...." }
```

`type` is `JWEPayload` when there is a sealed bundle to open. It is `ProtocolResponse` when the recipient refused the message; then the body carries the `x-hcx-` fields in the clear, `x-hcx-status` set to `response.error`, and the reason in `x-hcx-error_details`:

```json
{  "type": "ProtocolResponse",  "x-hcx-sender_code": "1000003538@hcx",  "x-hcx-recipient_code": "1000004446@hcx",  "x-hcx-api_call_id": "…",  "x-hcx-correlation_id": "11223344-5566-4788-99aa-bbccddeeff00",  "x-hcx-workflow_id": "12",  "x-hcx-timestamp": "…",  "x-hcx-status": "response.error",  "x-hcx-error_details": { "code": "…", "message": "…", "trace": "…" },  "x-hcx-entity-type": "preauth"}
```

`/v1/error` is the exception to the two shapes above. It carries no `payload` and no `x-hcx-` fields. What arrives is a plain JSON report of the request the exchange gave up on, with the rejection details. Its field names are not published, so do not parse it against a fixed schema. Store it whole, and answer it with `202` and the receipt like every other delivery. Fill in whatever identifiers the report happens to carry, and leave the rest of the receipt empty. Do not answer `/v1/error` with a `4xx` because the body is not a shape you recognise. Every delivery the exchange makes to you, on any of the paths listed above, is answered `202`.

The exchange signs its calls to you with a JWT: RS256 over its own private key, carrying the claims `jti`, `iss`, `sub` (the same value as `iss`), `iat` and `exp`. Validate the signature against the NHCX public key before trusting anything in the body.

**This is the one instruction in this documentation you cannot follow from it.** The API Security page gives the algorithm and the claims above, but no published source gives the NHCX public key or an address to fetch it from, and none names the header the token arrives in. Every integration built from these documents alone has therefore shipped with signature checking disabled, because the alternative, rejecting everything, makes the endpoint useless.

Do not leave that as an accident. Build the check, put the key in configuration, and treat a missing key as a deliberate, logged, temporary state rather than a silent default. Ask for the key during onboarding, at the same time you register your endpoint, and turn the check on the day you get it. Until then your callback address is an unauthenticated endpoint that accepts patient data. Keep it behind whatever else you have: an allow-list of the exchange's addresses, mutual TLS at your edge, a shared secret in a header the exchange agrees to send.

## Answer first, read second

The 30-second clock starts when the request lands. Do the minimum, send the receipt, and process afterwards.

The receipt is the same shape you received in the previous chapter, with the roles reversed:

```json
{  "timestamp": "04/09/2026 11:46:41:305",  "api_call_id": "<from the incoming header>",  "correlation_id": "<from the incoming header>",  "result": {    "sender_code": "1000003538@hcx",    "recipient_code": "1000004446@hcx",    "entity_type": "preauth",    "protocol_status": "request.queued"  },  "error": { "code": "", "message": "" }}
```

HTTP status `202`. Not `200`, not an empty body. For a `JWEPayload` the header fields come from the decrypted protected header; for a `ProtocolResponse` they are already in the clear.

## Opening it

The mirror of sealing. Read the body, decide which of the two shapes it is, and for a `JWEPayload` unwrap the compact string with your own private key, the one behind the certificate on your participant record. The protected header comes out of the token in the clear; the bundle is the decrypted plaintext.

```text
body = json.decode(httpRequest.body)if body.type == "ProtocolResponse":    header = fields of body whose name starts with "x-hcx-"    bundle = noneelse:    token = jose.decrypt(        compact    = body.payload,        privateKey = ourPrivateKey,             // PKCS8, the pair of the registered certificate        algorithm  = "RSA-OAEP-256",        encryption = "A256GCM"    )    header = token.protectedHeader    bundle = json.decode(token.plaintext)respond 202 with the receipt abovehandle(header, bundle)
```

warning

This is pseudo-code, not something to paste. Use the same JOSE library you sealed with; decrypting is the reverse call on the same object.

`openssl genpkey` wrote the private key in PKCS8 form, which is what every JOSE library loads directly. If decryption fails, the message was sealed with a certificate that is not the one on your participant record; go back to the update call and check what is registered.

## Then, in order

1. **Match the conversation.** `x-hcx-correlation_id` pairs this answer with the request you sent. Look it up. If you do not recognise it, log it and stop; do not act on it.
2. **Read the status.** `response.complete` is a final answer, `response.partial` an interim one, `response.error` a refusal.
3. **Read the workflow code.** It says what kind of answer this is: `21` a preauthorisation approved, `24` a query raised, and so on. The full table is in the Overview.
4. **Store the raw message** before doing anything with it. Disputes are settled on what was actually received.
5. **Act on the bundle**, if there is one. A `ClaimResponse` for a preauthorisation, a `CoverageEligibilityResponse` for an eligibility check, and so on.

Make the handler idempotent. The exchange retries on a missed receipt, so the same message can arrive twice; the `x-hcx-api_call_id` tells you it is the same one.

## Closing the loop

Send the empty bundle from the previous chapter to the dummy payer, then trigger its answer:

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/dummyhcxpayer/process/request' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "action": "Approve",    "method": "Preauth",    "correlationId": "<correlation id>"  }'
```

[Dummy payer, act on a request in the API reference](/docs/nhcx/v1/api/adjudicator/endpoints/adjudicator-process-request)

`action` is `Approve`, `Reject` or `Query`; `method` is `Preauth` or `Claim`. Your `/v1/preauth/on_submit` then receives the answer, either a sealed `ClaimResponse` or a `ProtocolResponse` carrying the refusal, with the correlation ID you sent. A `Query` action makes the dummy payer raise a communication request instead, which you answer on `/v1/communication/on_request` before the decision arrives.

Whichever comes back, that message proves the whole framework. Your token works, your participant record is live, the exchange can reach your address, the dummy payer could open your message, and you could read its reply. Nothing that follows changes any of it, only what goes in the bundle.

## Where next

- A **provider** goes to the B-series in the Overview's NHCX Use Cases chapter, starting with Check Coverage Eligibility, and to the sample bundles on the portal for a real Claim to put inside.
- A **payer** goes to the C-series, and hosts the `submit` and `check` endpoints this chapter described for the other side.
- Both should read [The JWE message format](/docs/nhcx/v1/getting-started/jwe-message-format) before writing a second use case; it is where the status words and the retry rules live.


---

# Session token

Every call carries a bearer token. The token does not come from NHCX. It comes from the ABDM gateway, with the client ID and secret you received when you registered on the ABDM sandbox. The handbook calls them `ABDM_CLIENT_ID` and `ABDM_CLIENT_SECRET`.

## Getting one

```bash
curl --location --request POST 'https://dev.abdm.gov.in/api/hiecm/gateway/v3/sessions' \  --header 'Content-Type: application/json' \  --header 'REQUEST-ID: <uuid>' \  --header 'TIMESTAMP: <iso timestamp>' \  --header 'X-CM-ID: sbx' \  --data-raw '{    "clientId": "<client id>",    "clientSecret": "<client secret>",    "grantType": "client_credentials"  }'
```

[Session token in the API reference](/docs/nhcx/v1/api/session/endpoints/session-api-hiecm-gateway-v3-sessions)

Three headers matter here, and none of them is optional.

- `REQUEST-ID` is a fresh UUID that you generate for every call. Sending the same one twice is the mistake to avoid; generate it, do not copy it from an example.
- `TIMESTAMP` is the current time in UTC, ISO 8601 with milliseconds and a trailing `Z`, as in `2026-09-04T06:15:51.975Z`. A clock that has drifted will be refused, so take the time from the system rather than constructing it by hand. How to produce it in each language is at the end of this chapter.
- `X-CM-ID` names the environment. It is `sbx` on the sandbox. The mirror and the adapter both use lowercase.

`grantType` is `client_credentials`. The older form of this call omitted it, which is why an otherwise correct request copied from an old sample can be rejected.

The response:

```json
{  "accessToken": "eyJhbGciOiJSUzI1NiIs...",  "expiresIn": 1200,  "refreshTokenIn": 300,  "refreshToken": "eyJhbGciOiJSUzI1NiIs...",  "tokenType": "bearer"}
```

## Using it

On every NHCX call, the token goes in a header called `bearer_auth`, with the word `Bearer` and a space in front. NHCX reads `bearer_auth`, not `Authorization`.

```text
bearer_auth: Bearer eyJhbGciOiJSUzI1NiIs...
```

Leaving out the `Bearer` prefix is the portal's own example of how to get a `401`.

## Keeping it fresh

The token lasts 1200 seconds (20 minutes) from the moment it arrives. Build it like this:

- Keep the token and the time you got it.
- Before each call, if the token is more than about 18 minutes old, get a new one first.
- If any call answers `401`, get a new token and retry that call once. Do not retry with the same token; it will fail the same way.
- Never write the token or the secret to a log.

One token serves every call: the participant service, the use-case endpoints, and the status check.

## The other call named session

The participant service publishes its own [`POST /get/session`](/docs/nhcx/v1/api/registry/endpoints/registry-get-session). It is a different call from the gateway sessions call above, and a request built for one fails on the other.

|             | Gateway sessions call                              | Participant service `/get/session`                            |
| ----------- | -------------------------------------------------- | ------------------------------------------------------------- |
| Address     | `dev.abdm.gov.in/api/hiecm/gateway/v3/sessions`    | `/get/session` on the participant service base                |
| Headers     | `REQUEST-ID`, `TIMESTAMP`, `X-CM-ID`               | None of the three                                             |
| Body        | JSON, with `clientId`, `clientSecret`, `grantType` | Form encoded, with `client_id`, `client_secret`, `grant_type` |
| Token field | `accessToken`                                      | `access_token`                                                |

Use the gateway sessions call by default. The sandbox exit test cases name `/get/session` as the token call, so point your token client there when you demonstrate them. Keep the address, the body format and the field names in configuration, so switching is not a code change.

## What can go wrong

| Symptom                                                                 | Cause                                                                                         |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `401` on the sessions call itself                                       | Wrong client ID or secret                                                                     |
| An error on the sessions call naming a header                           | `REQUEST-ID` reused or absent, `TIMESTAMP` stale or in the wrong format, or `X-CM-ID` missing |
| An error on the sessions call naming the body                           | `grantType` omitted, which the v3 address requires                                            |
| `401 Sender is not authorized to execute the operation` on an NHCX call | Token expired                                                                                 |
| `401` immediately after getting a fresh token                           | `Bearer` prefix missing                                                                       |

## Generating the timestamp

Two ISO 8601 shapes appear on NHCX, and they are not interchangeable.

- The ABDM gateway headers, `TIMESTAMP` on the sessions call, take UTC with milliseconds and a trailing `Z`: `2026-09-04T06:15:51.975Z`.
- The exchange header `x-hcx-timestamp` and `Bundle.timestamp` take Indian Standard Time as an offset, without milliseconds: `2026-09-04T11:46:34+05:30`. The two examples are the same instant.

Take the time from the system clock, keep the clock synchronised with NTP, and let a date library do the formatting. Each snippet below produces `utc` for the gateway and `ist` for the exchange.

### JavaScript and TypeScript

```js
const now = new Date();const utc = now.toISOString();                                    // 2026-09-04T06:15:51.975Zconst ist = new Date(now.getTime() + 330 * 60 * 1000)  .toISOString().slice(0, 19) + "+05:30";                         // 2026-09-04T11:46:34+05:30
```

### Python

```python
from datetime import datetime, timezone, timedeltautc = datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")ist = datetime.now(timezone(timedelta(hours=5, minutes=30))).isoformat(timespec="seconds")
```

### Java and Kotlin

```java
import java.time.*;import java.time.format.DateTimeFormatter;String utc = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.SSSX")    .withZone(ZoneOffset.UTC).format(Instant.now());String ist = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ssXXX")    .format(OffsetDateTime.now(ZoneOffset.ofHoursMinutes(5, 30)));
```

### C# and ASP.NET

```csharp
var now = DateTimeOffset.UtcNow;string utc = now.ToString("yyyy-MM-dd'T'HH:mm:ss.fff'Z'");string ist = now.ToOffset(TimeSpan.FromMinutes(330)).ToString("yyyy-MM-dd'T'HH:mm:sszzz");
```

### PHP

```php
$utc = (new DateTime('now', new DateTimeZone('UTC')))->format('Y-m-d\TH:i:s.v\Z');$ist = (new DateTime('now', new DateTimeZone('Asia/Kolkata')))->format('Y-m-d\TH:i:sP');
```

### Go

```go
now := time.Now()utc := now.UTC().Format("2006-01-02T15:04:05.000Z")ist := now.In(time.FixedZone("IST", 330*60)).Format("2006-01-02T15:04:05-07:00")
```

### C++

C++20 `<chrono>` and `<format>`:

```cpp
#include <chrono>#include <format>using namespace std::chrono;auto now = floor<milliseconds>(system_clock::now());std::string utc = std::format("{:%FT%T}Z", now);                       // 2026-09-04T06:15:51.975Zauto ist = floor<seconds>(now) + hours(5) + minutes(30);std::string istStr = std::format("{:%FT%T}+05:30", ist);               // 2026-09-04T11:46:34+05:30
```

Before C++20, `gmtime` with `strftime("%FT%T")` gives the seconds; append the milliseconds from `gettimeofday` and the `Z` by hand.

### Ruby

```ruby
utc = Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%LZ')ist = Time.now.getlocal('+05:30').strftime('%Y-%m-%dT%H:%M:%S%:z')
```

### Swift

```swift
let f = ISO8601DateFormatter()f.formatOptions = [.withInternetDateTime, .withFractionalSeconds]let utc = f.string(from: Date())f.formatOptions = [.withInternetDateTime]f.timeZone = TimeZone(secondsFromGMT: 19800)let ist = f.string(from: Date())
```

### Shell

GNU `date`, as on Linux:

```bash
utc=$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)ist=$(TZ=Asia/Kolkata date +%Y-%m-%dT%H:%M:%S%:z)
```

macOS `date` has no `%N`; use `gdate` from coreutils, or generate the value in the application rather than the shell.

Whichever language, the check is the same: the gateway value ends in `Z` and has three digits after the seconds; the exchange value ends in `+05:30` and has none.


---

# Status and search

Two exchanges that are not about a claim's progress but about finding out what happened to one. Both sides build them, both are on the sandbox exit checklists, and neither carries clinical content. Status asks the exchange where a message went. Search asks a payer for cases matching criteria.

They belong here rather than in the provider or payer sections because they are shared: the A-series, built once, used by both.

## Status

A sender asks the exchange what became of a message it already sent. It is a protocol operation, not a FHIR one.

|          |                                                                  |
| -------- | ---------------------------------------------------------------- |
| Call     | `POST /v1/status`                                                |
| Callback | `POST /v1/on_status`                                             |
| Payload  | **An empty string.** No bundle, no Task, no resource of any kind |

Everything travels in the protected header. That is the whole design, and it is why a status check costs nothing to answer.

### The request header

| Field                                       | Value                                                                  |
| ------------------------------------------- | ---------------------------------------------------------------------- |
| `x-hcx-status`                              | `request.initiated`                                                    |
| `x-hcx-correlation_id`                      | **The `api_call_id` of the message whose status you are asking about** |
| `x-hcx-api_call_id`                         | A fresh UUID, as always                                                |
| `x-hcx-sender_code`, `x-hcx-recipient_code` | You, and the exchange                                                  |
| `x-hcx-ben-abha-id`                         | Optional                                                               |
| `x-hcx-workflow_id`                         | Optional                                                               |
| `x-hcx-use_case`                            | Optional. `New`, `Enhancement` or `Resubmit` on the status sheet       |

The correlation rule is the exception that proves the rule set out in Envelope Fields. Everywhere else a correlation ID threads a conversation. Here it points at another message's call ID, because that is the only way to name the message you are asking about. Keep your own `api_call_id` values; without them you cannot ask this question at all.

### The answer

Arrives on `/v1/on_status`, again with an empty payload.

| Field                  | What it tells you                                                                                                                       |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `x-hcx-status`         | `request.dispatched` where the message reached the recipient. The other exchange-side values are `request.queued` and `request.stopped` |
| `x-hcx-error_details`  | Present where the original failed, with `code`, `message` and `trace`                                                                   |
| `x-hcx-correlation_id` | The correlation of your status request                                                                                                  |

`request.stopped` is the one to act on. It means redelivery was exhausted and the correlation has been retired, so the original request is dead and a retry needs a fresh correlation ID.

### When to call it

Not on a timer. The exchange delivers answers to your callback, and polling for something that will arrive on its own is wasted traffic on both sides. Call it when a case has gone quiet for longer than the payer's expected turnaround, and call it from a support screen rather than from the claims desk.

The Provider UI Guide makes the point the other way round: do not offer a refresh or chase control unless you have implemented this exchange behind it, because a control that does nothing is worse than no control.

## Search

Two different exchanges share the word. A provider may search, but only its own cases, and the sources do not settle which endpoint that search goes to.

|              | Own-case search                                                                        | Cross-payer search                          |
| ------------ | -------------------------------------------------------------------------------------- | ------------------------------------------- |
| Endpoints    | `/preauth/search`, `/claim/search`, `/paymentnotice/search`, each with its `on_search` | `/v1/search/submit`, `/v1/search/on_submit` |
| Who calls it | The participant whose messages these were                                              | NHA, or a regulator such as IRDAI           |
| Scope        | Requests that originated from the caller                                               | Any claim, at every payer                   |
| Also serves  | Status lookups on those resources                                                      |                                             |

The access-control policy is explicit that providers may make search and status requests for requests that originated from them, and that payers may do the same for their own payment notices. A provider's search over its own cases is `/claim/search` under that policy. A regulator's search is forwarded by the exchange to every payer, each answering under the regulator's policies.

The Technical Specifications route `/search/submit` from NHA through NHCX to the payer: a cross-payer search for NHA or a regulator. But the provider sandbox exit checklist, item 10 "Claim Search", names `/v1/search/submit`, and the payer exit checklist expects that search to arrive from a provider. No source confirms which of the two endpoints the sandbox accepts from a provider. Treat it as open: confirm with NHA before the demo, and keep the endpoint configurable. Access Control and Roles sets out the same rule.

The search service's sandbox specification is at `https://hcxsbx.abdm.gov.in/searchhcxservice/swagger-ui-custom.html`.

### The request bundle

A `Task` in a collection bundle.

| Element        | Value                                                                               |
| -------------- | ----------------------------------------------------------------------------------- |
| `Task.status`  | `requested`                                                                         |
| `Task.basedOn` | The request reference being searched for                                            |
| `Task.code`    | See the warning below                                                               |
| `Task.input[]` | One or more criteria, each with a type from the input value set and a `valueString` |

Input types, from `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-input-type-code`:

| Input                   | What it narrows by        |
| ----------------------- | ------------------------- |
| `ClaimNumber`           | The case number           |
| `IntimationNumber`      | The intimation number     |
| `PolicyNumber`          | The member's policy       |
| `ProductNumber`         | The benefit product       |
| `PayerId`, `ProviderId` | The two participants      |
| `FromDate`, `ToDate`    | The window                |
| `FinanceYear`           | Policy or financial year  |
| `ServiceCode`           | A benefit or service code |

### The answer

A `Task` bundle whose `output` references the matching `ClaimResponse` resources in the same bundle, resolved exactly as a reprocess or cancel answer is. Parse those with the `ClaimResponse` parser you already have.

**A search may be answered across several callbacks.** `response.partial` is valid on `/v1/search/on_submit`, and only the last carries `response.complete`. Accumulate against the correlation ID rather than treating the first answer as the whole result set.

### The Task code is stated three ways

The value set defines `search` as the code for searching claim responses. The Search sheet of the same workbook gives `status` on the request and `poll` on the callback. Nothing has been observed, so none can be confirmed.

Agree the code with the payer in writing before you build this, and record what you agreed. It is the one field that decides whether the message reaches the right queue.

## What neither exchange gives you

Under PMJAY, where a case actually stands is not readable over NHCX. A case sits at `request.initiated` until somebody acts on it in the scheme's own system, and a `Task` coded `status` is refused. The role lookup on the payer service is what answers that question instead; PMJAY Adjudication APIs in Building a Provider has it.

So a provider system needs both: the status exchange for "did my message arrive", and, for PMJAY, the role lookup for "who is holding this case now".


---

# The base framework

Every participant on NHCX, whether it sends claims or answers them, needs the same seven things working before a single use case can be built. This section builds them in order, and ends with a live round trip: a message out to the sandbox, and the reply back on your own server.

None of it is specific to a hospital or an insurer. A provider goes on from here to the B-series use cases; a payer to the C-series. The framework underneath is identical.

## What you will have at the end

```mermaid
sequenceDiagram
  box You
    participant Y as Your system
  end
  box ABDM and NHCX
    participant G as ABDM gateway
    participant P as Participant service
    participant X as NHCX
  end
  box Payer side
    participant D as Dummy payer
  end
  Y->>G: 1. client ID and secret
  G-->>Y: access token
  Note over Y: 2. make a key pair and certificate
  Y->>P: 3. create participant, register certificate and callback URL
  P-->>Y: participant code
  Y->>P: 4. list payers, look up the policy
  P-->>Y: processingid, memberid, productid
  Y->>P: 5. fetch the dummy payer's certificate
  P-->>Y: certificate
  Note over Y: 6. seal a bundle as JWE
  Y->>X: 7. POST payload
  X-->>Y: 202 receipt
  X->>D: forwards
  D->>X: reply
  X->>Y: 8. callback on your URL
  Y-->>X: 202 receipt
```

1. A way to get and refresh an access token.
2. Your own encryption key and certificate.
3. A participant record on the sandbox with your certificate and callback address on it.
4. A way to find the participant a message goes to, and the policy it concerns.
5. A way to fetch any other participant's certificate.
6. Code that turns a FHIR bundle into a sealed message and sends it.
7. A callback endpoint that accepts a message, acknowledges it, opens it and reads it.

Put together, that is the whole loop:

## Before you start

- **An identity in a registry.** A hospital needs its Health Facility Registry (HFR) ID. An insurer or TPA needs its IRDAI registry ID.
- **ABDM sandbox credentials.** A client ID and secret from the ABDM sandbox. NHCX uses these same credentials; there is no separate login.
- **A public HTTPS server in India** with a domain name, for the callback. The exchange will not call an IP address or a port number.
- **openssl** on the machine that will hold the private key.
- **A JOSE library** in your language. The portal's own samples use Nimbus for Java. The examples here use `jwcrypto` and `cryptography` for Python, because they are short; any library that does RSA-OAEP-256 with A256GCM will do.

## Addresses used in this section

All sandbox.

| What                | Where                                                           |
| ------------------- | --------------------------------------------------------------- |
| Session token       | `https://dev.abdm.gov.in/api/hiecm/gateway/v3/sessions`         |
| Participant service | `https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice` |
| Use-case calls      | `https://apisbx.abdm.gov.in/hcx/v1`                             |
| Dummy payer         | participant `1000003538@hcx`                                    |

Every call to the participant service and the use-case endpoints carries the same three headers:

```text
Accept: application/jsonContent-Type: application/jsonbearer_auth: Bearer <access token>
```

Note the header name. It is `bearer_auth`, not `Authorization`, on NHCX's own endpoints. The biometric endpoints used later under PMJAY use `Authorization` instead.


---

# Your certificate

Every message on the exchange is sealed for the receiver. For anyone to send you anything, you need a key pair: a private half you keep, and a public half, wrapped in a certificate, that you publish through your participant record.

## Making the key pair

Three commands, on a machine you control.

```bash
# 1. A 2048-bit RSA private keyopenssl genpkey -algorithm RSA -out private.key -pkeyopt rsa_keygen_bits:2048# 2. A signing request. It will ask for country, state, organisation and so on.openssl req -new -key private.key -out request.csr# 3. A self-signed X.509 certificate, valid for a yearopenssl x509 -req -in request.csr -signkey private.key -out certificate.crt -days 365
```

`private.key` is the secret. It opens every letter addressed to you. It never leaves your server and it is never sent to NHCX.

`certificate.crt` is public. It is what other participants use to seal messages for you.

## Encoding it for registration

The participant service takes the certificate as a single base64 string, not as a file.

```bash
base64 -w 0 certificate.crt > certificate.b64      # Linuxbase64 -i certificate.crt -o certificate.b64       # macOS
```

The contents of `certificate.b64` go into the `encryption_cert` field in the next chapter. It will start with `LS0tLS1CRUdJTi`, which is `-----BEGIN` in base64.

## Keeping it

- Store `private.key` where your callback service can read it and nothing else can.
- Note the expiry. A year from now the certificate lapses and every sender's encryption for you fails.
- NHA recommends replacing the key once a year. Replacing it is a certificate update on the participant record, covered next; there is no passcode step for a certificate-only change.
- If the private key may have leaked, generate a new pair, update the record, and tell NHA.

## A note on what you will see from others

When you fetch another participant's certificate later, you may get back a full X.509 certificate or, for some participants, a bare public key in SPKI form. Your code should try the certificate first and fall back to the key. The portal's Java sample loads the certificate with `CertificateFactory` and takes `getPublicKey()` from it; the Python equivalent is in Building and Sending a JWE.


---

# Going live

Going live is a certification followed by a switch. The sandbox proves the integration against the exchange and its dummy payer. NHA then certifies it, production credentials are issued, and the participant is registered again in production before the first real case travels. This chapter puts the steps in order and names the chapter that covers each one.

## In short

- Finish the sandbox exit list for your side, get your FHIR bundles validated, and give the demos.
- Production credentials come from NHA for a hospital, and through the NHA or IRDAI portal for a payer or TPA.
- Register the participant again in production, through the passcode flow, with your production certificate and callback address.
- Point every base URL at production. Only some production addresses are published; the rest come with your onboarding.
- Pilot on a few real cases before switching the whole organisation.

## Leave the sandbox

Run every test case on the exit list for your side: the Provider Checklist for a hospital, the Payer Checklist for an insurer, scheme or TPA. Cancel and reprocess, status and search are on both lists. A payer is also checked on the four validations every response must pass, on every use case.

Then:

- Email sample FHIR bundles to `hcx.integration@nha.gov.in` for NRCeS validation.
- Give the internal demo to the NHA team, then the HTC demo before NRCeS, IRDAI, TCS and NHA.
- Under PMJAY, add the PMJAY team demo, complete the WASA security audit, and submit the NHCX sandbox exit form.

## Get production credentials

For a hospital, NHA confirms the certification and adds the provider role to the production client ID.

A payer or TPA enrols through the NHA or IRDAI portal. The portal registers it after scrutiny and asks the ABDM gateway team to issue credentials with the payer or TPA role.

Under PMJAY, the integrator receives production keys for NHCX on successful completion, and the same keys serve for private insurer claims.

## Register in production

The production participant service is `https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice`. Registration there takes four steps, and each confirmation needs a passcode sent to the registered mobile number:

1. **Create** the participant, with the mobile number exactly as your HFR record holds it, or for a payer as NHA holds it.
2. **Confirm** with the transaction ID and passcode. The participant becomes active.
3. **Update** it with your production certificate and callback address. A second transaction ID and passcode arrive.
4. **Confirm again.** The certificate and address go live.

Passcodes and transaction IDs are valid for 24 hours; if one is lost, repeat that step. In production the registry ID is the HFR ID for a hospital and the IRDAI ID without leading zeros for a payer, and sending the wrong one is a common production failure. Creating and Updating a Participant has every call.

Fetch your own certificate back from the production registry, and check that it matches your private key, before anything is sent.

## Switch the addresses

Every base URL changes. Base URLs, in Getting Started, lists them for both environments. The exchange's production base is `https://apisprod.nha.gov.in/hcx`, and the participant service's production address is published too. Keep every base in configuration, and check each one against your onboarding letter.

If you run the NHCX Adapter, set `env` to `production`, confirm `auth.mode` with your onboarding contact, and expect the API key to be required. Its production addresses follow the pattern of swapping the sandbox hostnames, which is an inference, so override any that differ from your letter.

## Open the network path

The exchange calls your callback from three addresses. Allow all three inbound:

```text
3.109.99.21013.126.152.013.200.129.223
```

The callback address must be a domain name over HTTPS, with TLS 1.2 or newer, hosted in India. It must not be an IP address, and it must not carry a port number.

## Under PMJAY, plan the cutover

After the participant is created and configured in production, the hospital raises a ticket carrying its existing PMJAY hospital ID, the HEM ID used in TMS, and the new NHCX participant ID. NHA's operations team maps the two by hand, and that mapping is the switch. Preauthorisations and claims raised before it finish their life in TMS; everything raised after it goes through the HMIS. For a while both run at once, so brief the desk and plan the day.

## Pilot, then switch

NHA recommends a small pilot on a few real cases, and staff training, before switching fully.

## Before you switch

- Sandbox exit list complete, bundles validated by NRCeS, and the demos given.
- Production credentials issued with the right role.
- Production participant active, with the certificate and callback address registered and confirmed, and your own certificate fetched back and checked.
- Every base URL pointed at production and held in configuration.
- The three exchange addresses allowed inbound, and the callback on HTTPS with TLS 1.2 or newer, hosted in India.
- For a payer, every policy linked with the correct processor, and the plan master versioned and published for every empanelled hospital.
- Under PMJAY, the mapping ticket raised, and the desk briefed that in-flight TMS cases finish in TMS.
- A pilot planned.

## Next steps

- Provider Checklist and Payer Checklist: the sandbox exit lists
- Creating and Updating a Participant: the production registration calls
- Base URLs: every address in both environments
- PMJAY on NHCX: the scheme's integrator journey from Milestone 1 to the mapping ticket


---

# Security audit

Every National Health Claims Exchange (NHCX) participant passes the functional and security tests for its role before it leaves the sandbox. Production onboarding then asks for the certificates those tests produce. This chapter covers the security half and where it sits in the order.

## In short

- Security tests are part of sandbox certification for every participant, beside the functional use cases.
- A provider completes the [Web Application Security Assessment (WASA)](/docs/nhcx/v1/getting-started/glossary#identity-and-registration) for [ABDM](/docs/nhcx/v1/getting-started/glossary#organisations-and-programmes) Milestone 1. NHCX production runs on that same production client.
- Sandbox certification can require additional security testing, such as an STQC or CERT-In review.
- Production onboarding reviews your functional and security testing certificates before credentials are issued.

## Prerequisites

- Your integration runs every use case on the exit list for your side: the [Provider Checklist](/docs/nhcx/v1/roles/provider/provider-checklist) or the [Payer Checklist](/docs/nhcx/v1/roles/payer/payer-checklist).

## What applies to you

| Review                                      | When it applies                                                                                                                                                                             | What it gives you                      |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| Functional and security tests for your role | Every participant, before sandbox sign-off                                                                                                                                                  | The test results you submit for review |
| WASA security audit                         | ABDM Milestone 1 production access, which NHCX production builds on. Under [PMJAY](/docs/nhcx/v1/getting-started/glossary#organisations-and-programmes) it is also on the sandbox exit list | Clearance for ABDM production access   |
| STQC or CERT-In review                      | When NHCX policy requires it                                                                                                                                                                | An additional security clearance       |

## Pass the security tests for your role

Run the security tests and flows that apply to your role alongside the functional use cases. Submit your test results for review. Include how your application uses and interacts with the exchange APIs.

## Complete the WASA audit

Milestone 1 production credentials follow Milestone 1 functional testing, the WASA security audit and the [Health Tech Committee (HTC)](/docs/nhcx/v1/getting-started/glossary#identity-and-registration) demo. For a hospital, the provider role is then assigned to that Milestone 1 production client ID. The same client ID gives you NHCX production access, so the audit comes before NHCX production.

Under PMJAY, the sandbox exit adds the PMJAY team demo, the WASA audit and the NHCX sandbox exit form. [PMJAY on NHCX](/docs/nhcx/v1/concepts/pmjay-on-nhcx) has the scheme's full order.

## Plan for STQC or CERT-In review

Sandbox certification can require additional security testing, such as an STQC or CERT-In review. Plan for it until your onboarding confirms whether it applies. Request your demos and bundle review by email to `hcx.integration@nha.gov.in`.

## Keep the certificates for production onboarding

On approval, the sandbox issues a completion certificate, valid for a configured period. When you apply for production, a final approval reviews it. You share the functional and security testing certificates issued in the sandbox, and production credentials follow.

## What you see when it works

- You hold the email confirming your successful integration on the NHCX sandbox.
- You hold the security testing certificates that apply to you, ready to share at production onboarding.

## Confirm at onboarding

- **Whether STQC or CERT-In review applies to you.** Plan for it until you are told otherwise.
- **The validity period of your sandbox completion certificate.** Apply for production within it.

## Next steps

- [Going Live](/docs/nhcx/v1/go-live): the production credentials, registration and switch that follow.
- [Governance and Audit](/docs/nhcx/v1/reference/governance-and-audit): the security obligations that continue in production, and the full onboarding question list.


---

# Access control and roles

Most of this documentation talks about two parties. The network recognises nine, and each one has a fixed list of what it may send and what it may receive. That list is an access-control policy, enforced by the exchange against the roles on your participant record, and it decides what your integration is allowed to do before any of your own code runs.

## The roles

The exchange extends the HL7 organisation-role value set and namespaces it for claims.

| Role on the network  | Code  | Who it is                                                                                             |
| -------------------- | ----- | ----------------------------------------------------------------------------------------------------- |
| `provider`           | 10001 | Health service provider. A hospital or clinic                                                         |
| `payer`              | 10002 | Insurance service provider                                                                            |
| `agency.tpa`         | 10003 | Third-party administrator acting for a payer. In this version it behaves as a payer for data exchange |
| `agency.regulator`   | 10004 | IRDAI, IIB and bodies like them                                                                       |
| `research`           | 10005 | Research groups                                                                                       |
| `member.isnp`        | 10006 | Insurance self-network platforms. Marketplaces facilitating insurance adoption                        |
| `agency.sponsor`     | 10007 | Scheme owners, for example NHA for Ayushman Bharat                                                    |
| `HIE/HIO.NHCX`       | 10008 | Another exchange instance                                                                             |
| End-user application | 10009 | A beneficiary's personal health record app                                                            |

The FAQ notes that only four role codes are live in practice on the sandbox and in production: provider, payer, TPA and the end-user application. The rest are specified rather than deployed.

## What each role may do

| Role                  | Eligibility                                                  | Preauthorisation               | Claim                          | Payment                              | Search and status                                                      |
| --------------------- | ------------------------------------------------------------ | ------------------------------ | ------------------------------ | ------------------------------------ | ---------------------------------------------------------------------- |
| `provider`            | Send request, receive response                               | Send request, receive response | Send request, receive response | Receive notice, send acknowledgement | Its own preauthorisations and claims                                   |
| `payer`, `agency.tpa` | Receive request, send response                               | Receive request, send response | Receive request, send response | Send notice, receive acknowledgement | Its own payment notices                                                |
| `agency.regulator`    |                                                              |                                | Search claims                  |                                      | Across every payer                                                     |
| `research`            | Receive request, send response                               |                                |                                |                                      | Aggregate or anonymised only                                           |
| `member.isnp`         | Receive request, send response                               |                                |                                |                                      | Aggregate or anonymised, plus individual claims on beneficiary consent |
| `agency.sponsor`      | Equivalent to payer throughout                               |                                |                                |                                      |                                                                        |
| `HIE/HIO.NHCX`        | Relays as the use case needs, and can never read the payload |                                |                                |                                      |                                                                        |

Five things in that table change how a system is built.

**A provider can search, and only its own.** The policy is explicit: providers may make search and status requests "for multiple requests that originated from them". That is why the provider sandbox exit checklist includes claim search. Which endpoint that search goes to is not settled by the sources, and the next section sets out why.

**A regulator's search fans out.** The exchange forwards a regulator's search to every payer, each of which returns claims data under the regulator's policies. Nobody else on the network can cause one request to reach every payer.

**Research and marketplace access is aggregate by default.** Anything a `research` participant receives is aggregated or anonymised. The key aggregations are named as still to be defined, so treat this role as specified rather than usable.

**A marketplace needs consent, carried on the envelope.** `member.isnp` may see an individual beneficiary's preauthorisations and claims only with that beneficiary's consent, obtained through existing consent-management infrastructure, and "ISNPs are expected to submit the acquired consent as part of the domain header". That is the one place in the corpus where a domain header is load-bearing rather than informational. Envelope Fields has the naming convention.

**Another exchange never sees the payload.** A relaying instance routes on the envelope alone, which is the whole point of sealing the letter separately.

## Two kinds of search

The sources describe two search exchanges with different endpoints and different callers.

|              | Own-case search                                                                    | Cross-payer search                             |
| ------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------- |
| Endpoints    | `/preauth/search`, `/claim/search`, `/paymentnotice/search`, each with `on_search` | `/v1/search/submit` and `/v1/search/on_submit` |
| Who calls it | The participant that originated the messages                                       | NHA, or a regulator such as IRDAI              |
| Flow         | provider to NHCX to payer, and back                                                | NHA to NHCX to payer, and back                 |
| Scope        | Requests that originated from the caller                                           | Any claim, across every payer                  |
| Also serves  | Status lookups on those resources                                                  |                                                |

A provider's search over its own cases, the search the access-control policy allows, is `/claim/search`, the endpoint the Open Protocol page gives for it. The Technical Specifications route `/search/submit` from NHA through NHCX to the payer, and the requests-and-responses workbook gives NHA or IRDAI searching by case number as its example. That is the cross-payer search.

The provider sandbox exit checklist points the other way. Its item 10, "Claim Search", names `/v1/search/submit`, for "the providers/regulatory bodies", and the payer exit checklist expects that search to arrive from a provider. No source confirms which of the two endpoints the sandbox accepts from a provider. Treat it as open: confirm with NHA before the demo, and keep the endpoint configurable.

The Open Protocol page lists `/claim/search` as reachable by `provider | regulator | auditor`, which introduces an auditor role that appears in no other source and in no role table. Treat it as an unmodelled participant type rather than something to build for.

## Roles are set on the participant record

The role is not a claim you make per message. It is the `roles` field on your participant record, set at creation, and the exchange checks every call against it. Three practical consequences.

- **A participant may hold more than one role.** The field is an array.
- **The registry must match the role.** A provider is vouched for by the Health Facility Registry, a payer or TPA by the payer registry. The FAQ warns that incorrect role and registry mapping causes "API access issues, request rejection, or improper routing", and it is one of the harder faults to diagnose because the failure looks like a routing problem.
- **One entity, many participant IDs.** A hospital group holds one participant ID per Health Facility Registry ID, all created under the same credentials.

## What the registry holds about you

The participant registry is the source of truth for who may do what. Its attributes, with their obligations:

| Attribute           | Type   | Obligation | Notes                                                                                      |
| ------------------- | ------ | ---------- | ------------------------------------------------------------------------------------------ |
| `participant_code`  | String | Mandatory  | Generated by the exchange. Unique across installations, namespaced as `code@instance`      |
| `registry_code`     | String | Optional   | The HFR or payer registry code, used to validate and link the participant against the role |
| `participant_name`  | String | Mandatory  | Unique within the instance                                                                 |
| `roles`             | String | Mandatory  | Used for access control                                                                    |
| `address`           | JSON   | Optional   | Physical address including geolocation                                                     |
| `email`             | String | Optional   | Up to 3                                                                                    |
| `phone`             | String | Optional   | Landline, up to 3                                                                          |
| `mobile`            | String | Mandatory  | At least 1, up to 3                                                                        |
| `status`            | String | Mandatory  | `Created` (not yet verified), `Active`, `Inactive`, `Blocked`                              |
| `signing_cert_path` | String | Optional   | URI or path to the JWT signing certificate                                                 |
| `encryption_cert`   | String | Mandatory  | URI or path to the encryption certificate                                                  |
| `endpoint_url`      | String | Mandatory  | The default callback address                                                               |
| `payment_details`   | JSON   | Optional   | A UPI ID, or an account number with an IFSC code                                           |

`payment_details` is the only place on the network where a participant's bank details sit, and it is what `PAYR-1020`, "unable to process payment as no valid bank details found for the provider", refers to. It is optional at registration and not optional if you expect to be paid.

Only `Active` may send or receive. The registry offers create, update, delete and search, with modification controlled by the exchange operator as part of onboarding rather than exposed to participants.


---

# Authentication

Generated from the specifications. Every scheme and header below is declared in one of them.

## Session

**bearerAuth**, `http` `bearer`. On every NHCX call, the token goes in a header called `bearer_auth`, with the word `Bearer` and a space in front. NHCX reads `bearer_auth`, not `Authorization`.

| Header       | Required | What it is                                                                                                                                                                                                                                                                                                 |
| ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `REQUEST-ID` | yes      | `REQUEST-ID` is a fresh UUID that you generate for every call. Sending the same one twice is the mistake to avoid; generate it, do not copy it from an example.                                                                                                                                            |
| `TIMESTAMP`  | yes      | `TIMESTAMP` is the current time in UTC, ISO 8601 with milliseconds and a trailing `Z`, as in `2026-09-04T06:15:51.975Z`. A clock that has drifted will be refused, so take the time from the system rather than constructing it by hand. How to produce it in each language is at the end of this chapter. |
| `X-CM-ID`    | yes      | `X-CM-ID` names the environment. It is `sbx` on the sandbox. The mirror and the adapter both use lowercase.                                                                                                                                                                                                |

## Participant registry

**bearerAuth**, `apiKey`. Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

| Header        | Required | What it is                                                         |
| ------------- | -------- | ------------------------------------------------------------------ |
| `bearer_auth` | yes      | It is `bearer_auth`, not `Authorization`, on NHCX's own endpoints. |
| `Accept`      | yes      | Always `application/json` on the participant service.              |

## Coverage eligibility

**bearerAuth**, `apiKey`. Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

| Header        | Required | What it is                                                         |
| ------------- | -------- | ------------------------------------------------------------------ |
| `bearer_auth` | yes      | It is `bearer_auth`, not `Authorization`, on NHCX's own endpoints. |

## Insurance plan

**bearerAuth**, `apiKey`. Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

| Header        | Required | What it is                                                         |
| ------------- | -------- | ------------------------------------------------------------------ |
| `bearer_auth` | yes      | It is `bearer_auth`, not `Authorization`, on NHCX's own endpoints. |

## Pre-authorisation

**bearerAuth**, `apiKey`. Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

| Header        | Required | What it is                                                         |
| ------------- | -------- | ------------------------------------------------------------------ |
| `bearer_auth` | yes      | It is `bearer_auth`, not `Authorization`, on NHCX's own endpoints. |

## Claim

**bearerAuth**, `apiKey`. Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

| Header        | Required | What it is                                                         |
| ------------- | -------- | ------------------------------------------------------------------ |
| `bearer_auth` | yes      | It is `bearer_auth`, not `Authorization`, on NHCX's own endpoints. |

## Reprocess, cancel and shortfall

**bearerAuth**, `apiKey`. Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

| Header        | Required | What it is                                                         |
| ------------- | -------- | ------------------------------------------------------------------ |
| `bearer_auth` | yes      | It is `bearer_auth`, not `Authorization`, on NHCX's own endpoints. |

## Payment notice

**bearerAuth**, `apiKey`. Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

| Header        | Required | What it is                                                         |
| ------------- | -------- | ------------------------------------------------------------------ |
| `bearer_auth` | yes      | It is `bearer_auth`, not `Authorization`, on NHCX's own endpoints. |

## Communication

**bearerAuth**, `apiKey`. Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

| Header        | Required | What it is                                                         |
| ------------- | -------- | ------------------------------------------------------------------ |
| `bearer_auth` | yes      | It is `bearer_auth`, not `Authorization`, on NHCX's own endpoints. |

## Status and search

**bearerAuth**, `apiKey`. Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

| Header        | Required | What it is                                                         |
| ------------- | -------- | ------------------------------------------------------------------ |
| `bearer_auth` | yes      | It is `bearer_auth`, not `Authorization`, on NHCX's own endpoints. |

## Onboarding

**bearerAuth**, `apiKey`. Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

| Header        | Required | What it is                                                         |
| ------------- | -------- | ------------------------------------------------------------------ |
| `bearer_auth` | yes      | It is `bearer_auth`, not `Authorization`, on NHCX's own endpoints. |
| `Accept`      | yes      | Always `application/json` on the participant service.              |
| `source`      | yes      | Sent on this call, as the package's request carries it.            |

## PMJAY adjudicator

**bearerAuth**, `apiKey`. Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

| Header        | Required | What it is                                                         |
| ------------- | -------- | ------------------------------------------------------------------ |
| `bearer_auth` | yes      | It is `bearer_auth`, not `Authorization`, on NHCX's own endpoints. |
| `Accept`      | yes      | Always `application/json` on the payer service.                    |

## ABHA biometric authentication

**bearerAuth**, `http` `bearer`. The biometric calls go to the ABDM gateway, not to NHCX, so they carry the ABDM session token on `Authorization` as `Bearer <token>`. NHCX's own calls use `bearer_auth` instead.

| Header       | Required | What it is                                                                                                                                                                                                                                                                                                 |
| ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `process`    | yes      | No source puts `process` or `payerid` on `faceauth/init` or `capture/pid`.                                                                                                                                                                                                                                 |
| `payerid`    | yes      | `payerid` is the insurer's own participant code. Every insurer has one, even when it works through a TPA.                                                                                                                                                                                                  |
| `R-token`    | yes      | Sent on this call, as the package's request carries it.                                                                                                                                                                                                                                                    |
| `REQUEST-ID` | yes      | `REQUEST-ID` is a fresh UUID that you generate for every call. Sending the same one twice is the mistake to avoid; generate it, do not copy it from an example.                                                                                                                                            |
| `TIMESTAMP`  | yes      | `TIMESTAMP` is the current time in UTC, ISO 8601 with milliseconds and a trailing `Z`, as in `2026-09-04T06:15:51.975Z`. A clock that has drifted will be refused, so take the time from the system rather than constructing it by hand. How to produce it in each language is at the end of this chapter. |

## Other

**bearerAuth**, `apiKey`. Every NHCX call carries the access token from the session call in a header named `bearer_auth`, as the word `Bearer`, a space and the token. NHCX reads `bearer_auth`, not `Authorization`.

| Header        | Required | What it is                                                         |
| ------------- | -------- | ------------------------------------------------------------------ |
| `bearer_auth` | yes      | It is `bearer_auth`, not `Authorization`, on NHCX's own endpoints. |


---

# Envelope fields

Every field on the JWE protected header, with its obligation, its type and the rule that governs it. JWE, Status and Errors in the Overview explains what the envelope is and why it is separate from the letter. This chapter is the table you check a field against while you are building one.

The authority here is the Technical Specifications page on the portal, which carries the current header table, together with the ten sheets of the NHCX Requests and Responses workbook, which state the obligation of each field per exchange. Where the older Open Protocol page differs it is noted, because it is still published and still read.

## The fields

| Field                  | Type        | Obligation   | What it carries                                                                                                                                                                                                                                                                                          |
| ---------------------- | ----------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alg`                  | String      | Mandatory    | Key wrapping. `RSA-OAEP-256`                                                                                                                                                                                                                                                                             |
| `enc`                  | String      | Mandatory    | Content encryption. `A256GCM`                                                                                                                                                                                                                                                                            |
| `x-hcx-sender_code`    | String      | Mandatory    | Your participant code                                                                                                                                                                                                                                                                                    |
| `x-hcx-recipient_code` | String      | Mandatory    | The recipient's. For a provider, the processor code from the policy lookup                                                                                                                                                                                                                               |
| `x-hcx-api_call_id`    | UUID        | Mandatory    | Fresh on every message, including responses                                                                                                                                                                                                                                                              |
| `x-hcx-request_id`     | UUID        | **Optional** | One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Send it anyway, as a fresh UUID per originating request                                                                                                                     |
| `x-hcx-correlation_id` | UUID        | Mandatory    | The thread. See the rule below                                                                                                                                                                                                                                                                           |
| `x-hcx-workflow_id`    | String      | **Optional** | Which step, or which case. See the two readings below                                                                                                                                                                                                                                                    |
| `x-hcx-timestamp`      | datetime    | Mandatory    | See the format note below                                                                                                                                                                                                                                                                                |
| `x-hcx-status`         | String      | Mandatory    | Where this message stands. Values below                                                                                                                                                                                                                                                                  |
| `x-hcx-ben-abha-id`    | String      | **Optional** | The beneficiary's ABHA number. Send it when the beneficiary has one; exchanges with no beneficiary in the payload, such as the insurance plan poll, can leave it out. The format is per field: the bundle carries 14 digits without hyphens, and `NHCX-1018` asks for `XX-XXXX-XXXX-XXXX` on this header |
| `x-hcx-use_case`       | String      | Optional     | Values differ by exchange, see below                                                                                                                                                                                                                                                                     |
| `x-hcx-error_details`  | JSON object | Optional     | `code`, `message`, `trace`. Mandatory on a protocol response                                                                                                                                                                                                                                             |
| `x-hcx-debug_details`  | JSON object | Optional     | The same shape, for debugging                                                                                                                                                                                                                                                                            |
| `x-hcx-debug_flag`     | Enum        | Optional     | The specification lists `Error`, `Info` and `Debug`; the samples send `INFO`. A server may ignore it                                                                                                                                                                                                     |

**The `x-hcx-use_case` values are not one enum.** The workbook states them on three sheets and they are not the same on all three.

| Sheet   | Permitted values                 |
| ------- | -------------------------------- |
| Preauth | `New`, `Enhancement`, `Resubmit` |
| Status  | `New`, `Enhancement`, `Resubmit` |
| Claim   | `New`, `Resubmit`                |

A claim cannot be enhanced, which is why `Enhancement` is absent from that row. Both workbooks agree, sheet for sheet.

**`x-hcx-debug_flag` is typed two ways.** The Technical Specifications page gives the enum as `Error`, `Info` or `Debug`. The NHCX Requests and Responses workbook types it as Enum with the single value `INFO`, on its response headers, and every header table in the FHIR Reference and every sample in the API collection that carries the field sends `INFO`. The field is optional and a server may ignore it. No source says whether a server checks the case of the value.

Three of those obligations are not stated anywhere else in this documentation and are worth reading twice. `x-hcx-request_id` is optional. `x-hcx-workflow_id` is optional. `x-hcx-ben-abha-id` is optional.

Optional does not mean leave it out. Send `x-hcx-request_id` on every message, as a fresh UUID per originating request. It is cheap, and it satisfies both readings until NHA rules on which one stands.

## The correlation ID rule, in full

The rule is stated in two halves in two places, which has been read as a contradiction. It is not one. The workbook has twenty-five correlation rows: twenty-four state one half or the other, and they fit together, and the twenty-fifth gives the status enquiry its own rule.

| On a           | Set `correlation_id` to                                            | Rows stating it |
| -------------- | ------------------------------------------------------------------ | --------------- |
| Request        | This message's own `api_call_id`                                   | 8               |
| Response       | The `correlation_id` of the request being answered                 | 16              |
| Status enquiry | The `api_call_id` of the message whose status you are asking about | 1               |

So the initiator seeds the thread from its own call ID, and every responder echoes what it received. The Open Protocol page says the same thing in prose: the correlation ID "may be chosen as the message\_id of the original sender's system. For return messages responders are expected to populate with the one in the request."

The sandbox exit checklists describe the initiator's half; the protocol pages describe the responder's. Build both and threading works.

Two further rules, and both bite on retries.

- `api_call_id` and `correlation_id` must be **different values** on a response. The exit checklists check this on every answering use case.
- A correlation ID that has failed is **retired**. The next attempt needs a fresh one. Reusing it earns `NHCX-1006`, duplicate request, or goes nowhere.

## The workflow code means two different things

This is the field most likely to be misunderstood, because the sources define it twice and the definitions are not the same.

**As a step code.** The Workflow Status Sheet assigns a number to each step of a claim: 12 a new preauthorisation, 21 approved, 24 queried, and so on. This is the reading the Workflow Codes chapter documents and the one the reference payer validates.

**As a case thread.** The Open Protocol page defines it as the "unique id of workflow that may span over a series of message exchanges, e.g. an eligibility check, a preauth and then claims submission for a patient may be linked with such an id". The Technical Specifications page keeps both readings in one sentence: "Workflow id depicts the current process/state of the case. It may span over a series of message exchanges for a given transaction."

The field is **Optional** on all twenty-five rows of the workbook, across all ten sheets, including CoverageEligibility and Insurance Plan. So the exchanges for which the Workflow Status Sheet assigns no code are exchanges on which the header may simply be omitted. There is nothing to negotiate.

In practice: send the step code where the sheet gives one, because that is what the payer keys on. Send nothing where it does not. Agree the case-thread reading with a payer only if one asks for it.

## Status words

The Technical Specifications page defines all seven.

| Value                | Sent by       | Meaning                                                         |
| -------------------- | ------------- | --------------------------------------------------------------- |
| `request.initiated`  | The initiator | Starting the request cycle                                      |
| `request.queued`     | The exchange  | Queued at NHCX, waiting to be processed                         |
| `request.dispatched` | The exchange  | Successfully reached the recipient's system                     |
| `request.stopped`    | The exchange  | Stopped completely after failed attempts to reach the recipient |
| `response.partial`   | The responder | A partial response, or an acknowledgement of the request        |
| `response.complete`  | The responder | The final response, closing the cycle                           |
| `response.error`     | The responder | The request was rejected, or an error was met                   |

`request.stopped` is the one nothing else explains. It is what the exchange records when redelivery has been exhausted, and it is the state behind a retired correlation ID.

**The Open Protocol page carries a different set entirely**: `request.initiate`, `request.retry`, `response.success`, `response.fail`, `response.sender_not_supported`, `response.unhandled`, `response.request_retry`. None of those seven appears in the workflow sheet, in any sample, or in the gateway's own validation messages. It is a superseded draft. Do not build against it, and be ready to meet it in older material.

## Timestamp

Contested in format and in zone, and [The JWE message format](/docs/nhcx/v1/getting-started/jwe-message-format) sets out the disagreement. Two facts settle part of it.

- **The workbook types the field as a Unix timestamp** and gives `1706308383` as its example on every sheet. The handbook and the FAQ use ISO 8601. Every sample bundle uses ISO 8601 with `+05:30`.
- **There is one numeric tolerance.** The reference payer refuses a message whose timestamp is more than **24 hours** behind the current time, with `PAYR-1005`. That is the only bound any source states.

Send ISO 8601 with `+05:30`, because that is what the samples carry. Accept a Unix epoch on the way in. Note that the ABDM sessions call is a different matter: its `TIMESTAMP` header is UTC with a trailing `Z` and milliseconds, and a drifted clock is refused.

## Domain headers

The Overview says a few facts may be written on the outside of the envelope for the exchange's records. There is a naming convention for them and there are named examples, which is more than this documentation has said before.

**The convention**, from both the Open Protocol and Technical Specifications pages:

```text
x-hcx-<use_case_name>-<parameter_name>
```

where `use_case_name` is under sixteen characters and ideally matches the API path segment, and `parameter_name` is under thirty-two characters. Both pages print the prefix as `x-NHCX-`. Send `x-hcx-`, for the reason given under The header prefix below.

**The named examples.** The Notification Integration document carries four in its `domain_values` table, which is what the exchange passes to a beneficiary's app so it can render a message without opening anything:

| Header                        | What it carries                                |
| ----------------------------- | ---------------------------------------------- |
| `x-hcx-amount_submitted`      | The amount submitted by the provider           |
| `x-hcx-benefit-category_type` | The benefit category, meaning the specialty    |
| `x-hcx-benefit_code`          | An array of the benefits or services submitted |
| `x-hcx-action`                | The event type, such as `preauth_response`     |

The eObjects page adds a `Usage` domain header on the Claim Request and Claim Response, carrying `preauthorization` or `claim`.

And the access-control policy makes one of them load-bearing: an insurance marketplace must "submit the acquired consent as part of the domain header" before it may be given individual claim data. Access Control and Roles has the rest.

Send none of these to a payer that has not asked for one. But they are named, they have a convention, and the earlier statement in this documentation that no source names any of them was wrong.

## The header prefix

The Open Protocol page writes every field as `x-NHCX-`. The Technical Specifications page, the workbook, the FAQ, the Postman collections and every sample write `x-hcx-`. Send `x-hcx-`.

## What the receipt carries

Not a protected header, but the shape every participant must return within thirty seconds of a delivery.

```json
{  "timestamp": "04/09/2026 11:46:41:305",  "api_call_id": "<from the incoming header>",  "correlation_id": "<from the incoming header>",  "result": {    "sender_code": "…",    "recipient_code": "…",    "entity_type": "preauth",    "protocol_status": "request.queued"  },  "error": { "code": "", "message": "" }}
```

HTTP `202`. Not `200`, not an empty body. `entity_type` is derived from the path: the second-to-last segment, or the last where that is `v1`, with `on_` stripped.

The receipt's `timestamp` is written day first, as `DD/MM/YYYY HH:mm:ss:SSS`. That form belongs to the receipt only. The `x-hcx-timestamp` header still takes ISO 8601 with `+05:30`.


---

# Environments and addresses

Every address this documentation uses, together with the sandbox specifications the portal publishes. Addresses are scattered through the chapters that need them; this is where you check one.

## Base URLs

The base of every service, in both environments. Base URLs, in Getting Started, explains how a path is appended to them and what is easy to get wrong.

| Service                  | Sandbox                                                         | Production                                                    |
| ------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------- |
| ABDM session token       | `https://dev.abdm.gov.in`                                       | `https://apis.abdm.gov.in`                                    |
| NHCX exchange            | `https://apisbx.abdm.gov.in/hcx`                                | `https://apisprod.nha.gov.in/hcx`                             |
| Participant service      | `https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice` | `https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice` |
| ABDM proxy               | `https://apisbx.abdm.gov.in/pmjay/sbxhcx/abdmproxy`             | `https://apisprod.nha.gov.in/pmjay/hcx/abdmproxy`             |
| NHCX portal              | `https://hcxsbx.abdm.gov.in`                                    | `https://nhcx.abdm.gov.in`                                    |
| Face authentication page | `https://phrsbx.abdm.gov.in/face-auth`                          | `https://phr.abdm.gov.in/face-auth`                           |

What each one serves:

- **ABDM session token**: The session token every other call carries, at /api/hiecm/gateway/v3/sessions.
- **NHCX exchange**: Every use-case call under /v1, fingerprint and iris authentication under /abha.
- **Participant service**: Creating and updating a participant, the registry search, certificates and policies.
- **ABDM proxy**: Face authentication for PMJAY biometrics.
- **NHCX portal**: The portal, the sandbox Swagger specifications it publishes, and notification subscribe.
- **Face authentication page**: The QR page a patient opens to complete face authentication, with ?txnId=\<txnId>.

The ABDM gateway also reads `X-CM-ID` on the session call: `sbx` in the sandbox, `abdm` in production.

## Full sandbox addresses

| What                            | Address                                                             |
| ------------------------------- | ------------------------------------------------------------------- |
| Session token                   | `https://dev.abdm.gov.in/api/hiecm/gateway/v3/sessions`             |
| Use-case calls                  | `https://apisbx.abdm.gov.in/hcx/v1`                                 |
| Biometric, fingerprint and iris | `https://apisbx.abdm.gov.in/hcx/abha/biometric/auth/{init,verify}`  |
| Biometric, token refresh        | `https://apisbx.abdm.gov.in/hcx/abha/biometric/auth/refresh/token`  |
| Biometric, face                 | `https://apisbx.abdm.gov.in/pmjay/sbxhcx/abdmproxy/abha/biometric/` |
| Face auth QR page               | `https://phrsbx.abdm.gov.in/face-auth?txnId=<txnId>`                |
| Notification subscribe          | `https://hcxsbx.abdm.gov.in/v1/notification/subscribe`              |
| The portal itself               | `https://hcxsbx.abdm.gov.in`                                        |

The production addresses NHA has not published follow, elsewhere, the pattern of swapping the sandbox hostname, and the NHCX Adapter's own source says as much in a comment, but that is an inference. Check every one against your onboarding letter and make every one configurable. Going Live has the order the switch happens in.

## Headers, by service

Which header carries the token is not uniform, and this is a common first-day failure.

| Service              | Token header                    | Other required headers                        |
| -------------------- | ------------------------------- | --------------------------------------------- |
| ABDM sessions        | none                            | `REQUEST-ID`, `TIMESTAMP`, `X-CM-ID`          |
| Participant service  | `bearer_auth: Bearer <token>`   | `Accept`, `Content-Type`, sometimes `X-CM-ID` |
| Use-case endpoints   | `bearer_auth: Bearer <token>`   | `Accept`, `Content-Type`                      |
| Biometric endpoints  | `Authorization: Bearer <token>` | `process`, `payerid`                          |
| PMJAY payer service  | `bearer_auth: Bearer <token>`   | `Accept`, `Content-Type`                      |
| Notification service | `Authorization: Bearer <token>` | `Content-Type`                                |

The exchange's own endpoints, the participant service and the PMJAY payer service read the token from `bearer_auth`, not `Authorization`.

`Accept: application/json` is the portal's sixth most common mistake when omitted.

## Firewall

The exchange calls your callback from three addresses. All three must be allowed inbound.

```text
3.109.99.21013.126.152.013.200.129.223
```

Your callback address itself must be a domain name over HTTPS with TLS 1.2 or newer, hosted in India, not an IP address and not carrying a port number.

## Sandbox API specifications

The portal publishes a Swagger document per service. These are the authoritative API surface and they cover three exchanges for which no sample bundle exists anywhere, so they are the only concrete description of those available.

No production specification is published. The sandbox specifications below are the only published contract. The paths are the same in production; only the base changes, to the production base in the base-URL table above where one is published. Ask for the production Swagger at onboarding, and check it against these before you switch.

| Service                        | Specification                                                                     |
| ------------------------------ | --------------------------------------------------------------------------------- |
| Coverage eligibility           | `https://hcxsbx.abdm.gov.in/coverageeligibilityhcxservice/swagger-ui-custom.html` |
| Preauthorisation               | `https://hcxsbx.abdm.gov.in/preauthhcxservice/swagger-ui-custom.html`             |
| Claim                          | `https://hcxsbx.abdm.gov.in/claimhcxservice/swagger-ui-custom.html`               |
| Request additional attachments | `https://hcxsbx.abdm.gov.in/communicationhcxservice/swagger-ui-custom.html`       |
| Payment                        | `https://hcxsbx.abdm.gov.in/servicehcxpayment/swagger-ui-custom.html`             |
| Status check                   | `https://hcxsbx.abdm.gov.in/statushcxservice/swagger-ui-custom.html`              |
| Reprocess, the Task service    | `https://hcxsbx.abdm.gov.in/taskhcxservice/swagger-ui-custom.html`                |
| Search                         | `https://hcxsbx.abdm.gov.in/searchhcxservice/swagger-ui-custom.html`              |
| Insurance plan                 | `https://hcxsbx.abdm.gov.in/insuranceplanhcxservice/swagger-ui/index.html`        |
| Communication                  | `https://hcxsbx.abdm.gov.in/communicationhcxservice/swagger-ui/index.html`        |
| Participant                    | `https://hcxsbx.abdm.gov.in/participanthcxservice/swagger-ui/index.html`          |
| Notifications                  | `https://hcxsbx.abdm.gov.in/subscriptionhcxservice/swagger-ui/index.html`         |

The service names are worth noting on their own. Reprocess is served by `taskhcxservice`, notifications by `subscriptionhcxservice`, payment by `servicehcxpayment`. A name in a log will not always match the exchange you think you are calling.

## The endpoint set

Every path in the V1 cashless use case, with its direction.

| Exchange                | Action                                                      | Callback                           | Direction                     |
| ----------------------- | ----------------------------------------------------------- | ---------------------------------- | ----------------------------- |
| Coverage eligibility    | `/v1/coverageeligibility/check`                             | `/v1/coverageeligibility/on_check` | provider to payer             |
| Insurance plan          | `/v1/insuranceplan/request`                                 | `/v1/insuranceplan/on_request`     | provider to payer             |
| Preauthorisation        | `/v1/preauth/submit`                                        | `/v1/preauth/on_submit`            | provider to payer             |
| Claim                   | `/v1/claim/submit`                                          | `/v1/claim/on_submit`              | provider to payer             |
| Communication           | `/v1/communication/request`                                 | `/v1/communication/on_request`     | payer to provider             |
| Payment notice          | `/v1/paymentnotice/request`                                 | `/v1/paymentnotice/on_request`     | payer to provider             |
| Task: reprocess, cancel | `/v1/task/submit`                                           | `/v1/task/on_submit`               | provider to payer             |
| Cross-payer search      | `/v1/search/submit`                                         | `/v1/search/on_submit`             | NHA or regulator to payer     |
| Own-case search         | `/preauth/search`, `/claim/search`, `/paymentnotice/search` | the matching `on_search`           | originator to payer           |
| Status                  | `/v1/status`                                                | `/v1/on_status`                    | either party to the exchange  |
| Error report            |                                                             | `/v1/error`                        | exchange to every participant |
| Notifications           | `/v1/notification/subscribe`                                | `/v1/notification/on_subscribe`    | patient app to exchange       |

## A defect in the published table

The FAQ's own base-URL table gives the payment notice address as `https://apisbx.abdm.gov.inhcx/v1/paymentnotice/on_request`, with the slash after the hostname missing. Anyone copying it will get a DNS failure rather than an API error, which is a confusing first symptom. The address is `https://apisbx.abdm.gov.in/hcx/v1/paymentnotice/on_request`.


---

# Reading error codes

Every error code NHCX and the reference payer can send, in one place. The workflow codes are in the Overview's Workflow Codes chapter and the FHIR value sets in Codes and Value Sets; this chapter is only about failure.

Three hundred and nine distinct codes exist across the seven sheets of the Standard Error Codes workbook, last updated 11 August 2026. They are not one list. They are three, and the first thing to get right is which one you are reading.

[Error codes](/docs/nhcx/v1/reference/error-codes), and the errors page under each API, are generated from the Catalogue's error atoms and are the canonical list. Where a message here differs from that list, the list wins.

## The code spaces

| Space           | Prefix                   | Count | Who sends it                                                        | Where it arrives                                  |
| --------------- | ------------------------ | ----- | ------------------------------------------------------------------- | ------------------------------------------------- |
| Gateway         | `NHCX-`                  | 19    | The exchange                                                        | Synchronously on your own call, or on `/v1/error` |
| Standard payer  | `PAYR-1001 to PAYR-1020` | 20    | A payer implementing the published standard                         | Inside the sealed response                        |
| Reference payer | `PAYR-1001 to PAYR-1520` | 290   | The PMJAY reference implementation                                  | Inside the sealed response                        |
| Observed live   | `ERR-PYR-`               | 1     | The PMJAY reference implementation, on none of its published sheets | Inside the sealed response                        |

The fourth row is not a sheet. It is the one code the reference payer sent on the sandbox run that none of the seven sheets lists; What the live payer sent that the sheets do not say, below, covers it.

**The two `PAYR-` spaces collide.** All twenty codes in the `PAYR-1001` to `PAYR-1020` range are on both the standard sheet and the reference payer's Bridge Error sheet, and eighteen of them carry a different meaning on each. The two that agree are `PAYR-1001` and `PAYR-1002`, a decryption and an encryption failure on both sheets in different words. The reference payer's own sheet marks three of its readings, `PAYR-1003`, `PAYR-1006` and `PAYR-1007`, as deprecated.

| Code        | Standard sheet says                                                | Reference payer says                                                     |
| ----------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| `PAYR-1003` | Error while connecting to NHCX; the system will resend later       | Invalid workflow requested (marked deprecated on the Bridge Error sheet) |
| `PAYR-1004` | Provider is not registered with the payer for the requested policy | Received FHIR bundle is malformed                                        |
| `PAYR-1005` | Beneficiary is not a covered member for the requested policy       | Maximum time limit exceeded in receiving the request                     |
| `PAYR-1006` | Policy does not exist                                              | Invalid name in request (marked deprecated on the Bridge Error sheet)    |
| `PAYR-1007` | Requested policy is expired                                        | Invalid gender in request (marked deprecated on the Bridge Error sheet)  |
| `PAYR-1008` | Eligible coverage amount is insufficient                           | Invalid FHIR bundle received                                             |
| `PAYR-1009` | Requested items are not valid or not covered                       | No identifier found for patient component                                |
| `PAYR-1010` | Preauthorisation is required but was not obtained                  | No type found for patient component identifier                           |
| `PAYR-1011` | The prior approved package does not support enhancement            | No identifier found for claim component                                  |
| `PAYR-1012` | Claim amount is more than the preauthorisation approved amount     | No type found for claim component identifier                             |
| `PAYR-1013` | No prior approval for the requested procedures or packages         | No identifier found for organization component for provider              |
| `PAYR-1014` | Date of birth is after the date of service                         | No type found for organization component identifier for provider         |
| `PAYR-1015` | Date of service is after the date of death                         | No identifier found for organization component for payer                 |
| `PAYR-1016` | Duplicate claim submitted based on service codes and dates         | No type found for organization component identifier for payer            |
| `PAYR-1017` | Amount calculations are not correct                                | No task code received                                                    |
| `PAYR-1018` | Time limit for submission expired                                  | No task reason code received                                             |
| `PAYR-1019` | Requested additional information was not received in time          | Invalid sequence received in supporting info element                     |
| `PAYR-1020` | No valid bank details found for the provider                       | Invalid category received in supporting info element                     |

A system that maps its error handling from the standard sheet and then meets the reference payer will mis-read eighteen codes in that band, and for most of them the two readings point at opposite remedies: a business refusal the desk must act on, against a structural fault only an engineer can fix. The live sandbox run recorded in PMJAY Sandbox Run met the reference payer's readings throughout.

Decide which payer you are talking to before you look a code up. If you support both, key your table on the pair of payer and code, never on the code alone.

## Reading a code by its band

The reference payer's codes are banded by the stage that rejected the message, and the band is more useful than the code when you are triaging.

| Band        | Codes | What rejected it                             | What it means for you                                            |
| ----------- | ----- | -------------------------------------------- | ---------------------------------------------------------------- |
| `NHCX-1xxx` | 19    | The exchange, on the envelope                | The message never reached the payer                              |
| `PAYR-10xx` | 98    | Transport and bundle structure               | An element, id, sequence or type is missing. Not a value problem |
| `PAYR-11xx` | 23    | Coverage eligibility                         | The policy, the beneficiary or the hospital configuration        |
| `PAYR-12xx` | 73    | Preauthorisation                             | Codes, amounts, dates, sequencing and scheme rules               |
| `PAYR-13xx` | 70    | Claim                                        | The same, against the approved preauthorisation                  |
| `PAYR-14xx` | 26    | Insurance plan, and the scheme's outer rules | Empanelment, policy association, plan configuration              |

Two consequences follow, both confirmed live.

**The bands are applied in order.** The bundle is validated before the scheme's rules are applied, so a `PAYR-12xx` or `PAYR-13xx` refusal is the first sign that the bundle itself is structurally sound. Reaching `PAYR-1238` is progress.

**The `PAYR-10xx` band is structural, not semantic.** When you meet one, check ids, sequences and types before you go looking at values. `PAYR-1027`, "invalid item id", is not about the package code at all; it means the `Claim.item` has no FHIR element `id`.

## Gateway codes

| Code        | Message                                                                                                               |
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `NHCX-401`  | User Unauthorized                                                                                                     |
| `NHCX-1001` | Receiver system is not reachable.                                                                                     |
| `NHCX-1002` | Sender not registered in NHCX. Please register in NHCX portal and try again.                                          |
| `NHCX-1003` | Receiver not registered in NHCX. Please try again with valid receiver details.                                        |
| `NHCX-1004` | No receiver registered in NHCX for the requested scheme. Please try again with valid receiver details for the scheme. |
| `NHCX-1005` | Invalid request header. Please try again with valid headers.                                                          |
| `NHCX-1006` | Duplicate request. Request with same correlation id already exist in the system.                                      |
| `NHCX-1007` | Something went wrong while processing the request. Please check the request structure and values and try again.       |
| `NHCX-1008` | Something went wrong while processing the request. Please try again after sometime.                                   |
| `NHCX-1009` | Something went wrong while processing the request. Please check log for more details.                                 |
| `NHCX-1010` | No Data with given Correlation id for call back request, please check status for more details                         |
| `NHCX-1011` | Invalid Status, please check x-hcx-status value from the protected header                                             |
| `NHCX-1012` | No records found with the requested api caller id. Please try again with a valid api caller id.                       |
| `NHCX-1013` | Invalid or blank request found.                                                                                       |
| `NHCX-1014` | Unable to send protocol response to sender.                                                                           |
| `NHCX-1015` | Invalid response received from receiver.                                                                              |
| `NHCX-1016` | Invalid Api Action, please check the request action for this correlationId before trying again                        |
| `NHCX-1017` | Invalid response received from receiver                                                                               |
| `NHCX-1018` | Invalid ABHA number received. ABHA number should be sent in the format XX-XXXX-XXXX-XXXX                              |

`NHCX-1010` is the one to understand before you build a payer. The exchange redelivers a submission you have not answered, drops it after a few attempts and retires the correlation ID, so a verdict decided minutes later has nowhere to land. Acknowledge every submission at once with an interim response and send the decision later on the same thread.

`NHCX-1006`, duplicate correlation ID, is what a retry earns if you reuse a correlation ID after a failure. Mint a fresh one.

`NHCX-1015` and `NHCX-1017` share one message on the sheet, "Invalid response received from receiver". They are not one condition. `NHCX-1017` is the invalid receipt: a delivery answered with the wrong status or body. `NHCX-1015` is what the participant registry sends, as "You are not authorized to update/modify details", when a client id that did not create a participant tries to change its endpoint or certificate. Send the change with the creator's credentials, or through the NHCX portal or support.

## Standard payer codes

The twenty codes a payer implementing the published standard sends. These are business refusals and belong on the claims desk, shown in the payer's own words.

| Code        | Message                                                                                                           |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| `PAYR-1001` | Error while decrypting request. Please reprocess the request encrypting with valid certificate of the payer.      |
| `PAYR-1002` | Error while encrypting request. Please update encryption certificate in NHCX.                                     |
| `PAYR-1003` | Error while connecting to NHCX. System will try to resend the message to NHCX after some time.                    |
| `PAYR-1004` | Provider is not registered with the payer for requested policy.                                                   |
| `PAYR-1005` | Beneficiary is not a covered member for requested policy. Please enroll beneficiary for the policy and try again. |
| `PAYR-1006` | Policy does not exist. Please try with a valid policy.                                                            |
| `PAYR-1007` | Requested policy is expired. Please try with a valid policy.                                                      |
| `PAYR-1008` | Eligible coverage amount of the beneficiary for the requested policy is insufficient to process the request.      |
| `PAYR-1009` | Requested items are not valid or not covered. Please try again with valid or covered items.                       |
| `PAYR-1010` | Preauthorization is required to process the request but was not obtained.                                         |
| `PAYR-1011` | Enhancement request can not be processed as the prior approved package/procedure does not support enhancement.    |
| `PAYR-1012` | Claim amount requested is more than the preauthorization approved amount.                                         |
| `PAYR-1013` | No prior approval for the requested procedures/packages obtained.                                                 |
| `PAYR-1014` | Date of birth of the beneficiary can not be after date of service.                                                |
| `PAYR-1015` | Date of service cannot be after date of death.                                                                    |
| `PAYR-1016` | Duplicate claim submitted based on service codes and dates.                                                       |
| `PAYR-1017` | Amount calculations are not correct. Please verify calculated amount.                                             |
| `PAYR-1018` | Time limit for submission expired.                                                                                |
| `PAYR-1019` | Requested additional information was not received or was not received within time limit                           |
| `PAYR-1020` | Unable to process payment as no valid bank details found for the provider.                                        |

## Reference payer: structure and transport, `PAYR-10xx`

Ninety-eight codes. Almost all of them say that an element the payer addresses by id, sequence or type is missing its handle. None of them is a code lookup.

| Code        | Message                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PAYR-1001` | Error occurred while decrypting payload for receiver code \<receiver\_code> with correlation id \<sender\_correlation\_id>.                                                                                                                                                                                                                                                                                            |
| `PAYR-1002` | Error occurred while encrypting payload for receiver code \<receiver\_code> with correlation id \<sender\_correlation\_id>.                                                                                                                                                                                                                                                                                            |
| `PAYR-1003` | Invalid workflow requested. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1004` | Received FHIR bundle is malformed. Please correct the bundle and try again. \<Error details>                                                                                                                                                                                                                                                                                                                           |
| `PAYR-1005` | Maximum time limit exceeded in receiving the request. Please try again.                                                                                                                                                                                                                                                                                                                                                |
| `PAYR-1006` | Invalid name in request. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                  |
| `PAYR-1007` | Invalid gender in request. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                |
| `PAYR-1008` | Invalid FHIR bundle received. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                             |
| `PAYR-1009` | No identifier found for patient component. Hence request will not be processed further. <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html>                                                                                                                                                                                                                                                           |
| `PAYR-1010` | No type found for patient component identifier. Hence request will not be processed further. <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html>                                                                                                                                                                                                                                                      |
| `PAYR-1011` | No identifier found for claim component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                  |
| `PAYR-1012` | No type found for claim component identifier. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                             |
| `PAYR-1013` | No identifier found for organization component for provider. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                              |
| `PAYR-1014` | No type found for organization component identifier for provider. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                         |
| `PAYR-1015` | No identifier found for organization component for payer. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                 |
| `PAYR-1016` | No type found for organization component identifier for payer. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                            |
| `PAYR-1017` | No task code received. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                    |
| `PAYR-1018` | No task reason code received. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                             |
| `PAYR-1019` | Invalid sequence received in supporting info element. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                     |
| `PAYR-1020` | Invalid category received in supporting info element for sequence %s. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                     |
| `PAYR-1021` | Invalid code received in supporting info element for sequence %s. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                         |
| `PAYR-1023` | Invalid procedure category received for procedure component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                              |
| `PAYR-1024` | Invalid procedure status received for procedure component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                |
| `PAYR-1025` | Invalid procedure sequence received for procedure component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                              |
| `PAYR-1026` | No procedure component found for reference in claim component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                            |
| `PAYR-1027` | Invalid item id found for item in claim component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                        |
| `PAYR-1028` | Invalid item sequence received for item in claim component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                               |
| `PAYR-1029` | Invalid bundle id received for FHIR bundle. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1030` | Invalid questionnaire id received in FHIR bundle for questionnaire component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                             |
| `PAYR-1031` | Invalid url received for bundle entry in FHIR bundle. Hence request will not be processed further. Please reach out to technical team.                                                                                                                                                                                                                                                                                 |
| `PAYR-1032` | Invalid purpose received for coverage eligibility request. Hence request will not be processed further. Please try again with valid purpose details.                                                                                                                                                                                                                                                                   |
| `PAYR-1033` | No items received for coverage eligibility purpose. Since items are mandatory for the requested purpose, hence request will not be processed further. Please try again with valid item details.                                                                                                                                                                                                                        |
| `PAYR-1034` | Invalid procedure code received. Please try again with valid procedure details.                                                                                                                                                                                                                                                                                                                                        |
| `PAYR-1035` | Invalid policy code received. Please try again with valid policy details.                                                                                                                                                                                                                                                                                                                                              |
| `PAYR-1036` | Invalid attachment received in supporting info with sequence number %s. Please try again with valid attachment details as attachment value is expected. If issue is not resolved, please reach out to technical team.                                                                                                                                                                                                  |
| `PAYR-1037` | No identifier found for communication component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                          |
| `PAYR-1038` | No type found for communication component identifier. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                     |
| `PAYR-1039` | No payload found for communication component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                             |
| `PAYR-1040` | No component found for given reference. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                   |
| `PAYR-1041` | No identifier found for procedure component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                              |
| `PAYR-1042` | No type found for procedure component identifier. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                         |
| `PAYR-1043` | Date received in the request does not adhere to the NRCES date datatype format. Hence request will not be processed further. Please refere to the date format in NRCES portal.                                                                                                                                                                                                                                         |
| `PAYR-1044` | Date and time received in the request does not adhere to the NRCES date datatype format. Hence request will not be processed further. Please refere to the date time format in NRCES portal.                                                                                                                                                                                                                           |
| `PAYR-1045` | Invalid quantity received for item. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                       |
| `PAYR-1046` | No value or timing details received for supporting info for sequence %s. Hence request will not be processed further. Please reach out to technical team.                                                                                                                                                                                                                                                              |
| `PAYR-1047` | Invalid reference received in supporting info with sequence number %s. Please try again with valid resource as reference value.                                                                                                                                                                                                                                                                                        |
| `PAYR-1048` | No reference resource received for supporting info with sequence number %s. Please try again with valid resource for reference value.                                                                                                                                                                                                                                                                                  |
| `PAYR-1049` | Invalid FHIR bundle received. Hence request will not be processed further. please reach out to technical team.                                                                                                                                                                                                                                                                                                         |
| `PAYR-1050` | No type found for practitioner component identifier. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                      |
| `PAYR-1051` | No section found for composition component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1052` | No references found in composition section. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1053` | Invalid reference found in child sections of composition section. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                         |
| `PAYR-1054` | No section content found for composition component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                       |
| `PAYR-1055` | No subject found for composition component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1056` | Invalid contact organization found for subject in composition component. This should be of type Organization. Hence request will not be processed further. Please try again with valid data.                                                                                                                                                                                                                           |
| `PAYR-1057` | Invalid general practioner type found for subject in composition component. This should be of type Organization/Practitioner/PractitionerRole. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html>                                                                                                                                       |
| `PAYR-1058` | Invalid managing organization type found for subject in composition component. This should be of type Organization. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html>                                                                                                                                                                  |
| `PAYR-1059` | Invalid encounter type found for composition/observation component. This should be of type Encounter. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-DiagnosticReportRecord.html>                                                                                                                                                                 |
| `PAYR-1060` | No encounter found for composition/observation component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                 |
| `PAYR-1061` | Invalid subject type found for encounter in composition/observation component. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html>                                                                                                                                                                                                     |
| `PAYR-1062` | No episode of care found for encounter in composition/observation component. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html>                                                                                                                                                                                                       |
| `PAYR-1063` | Invalid episode of care type found for encounter in composition/observation component. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html>                                                                                                                                                                                             |
| `PAYR-1064` | No based on found for encounter in composition/observation component. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html>                                                                                                                                                                                                              |
| `PAYR-1065` | Invalid based on type found for encounter in composition/observation component. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html>                                                                                                                                                                                                    |
| `PAYR-1066` | No appointment found for encounter in composition/observation component. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html>                                                                                                                                                                                                           |
| `PAYR-1067` | Invalid appointment type found for encounter in composition/observation component. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html>                                                                                                                                                                                                 |
| `PAYR-1068` | No reason reference found for encounter in composition/observation component. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html>                                                                                                                                                                                                      |
| `PAYR-1069` | Invalid reason reference type found for encounter in composition/observation component. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html>                                                                                                                                                                                            |
| `PAYR-1070` | No author found for composition component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                |
| `PAYR-1071` | Invalid author type found for composition component. This should be of type Practitioner / PractitionerRole / Organization / Patient / Device / RelatedPerson. Hence request will not be processed further. Please try again with valid author type for the composition.                                                                                                                                               |
| `PAYR-1072` | No procedure reference received for procedure element in claim resource. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                  |
| `PAYR-1073` | No based on found for observation component. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Observation.html>                                                                                                                                                                                                                                     |
| `PAYR-1074` | Invalid based on type found for observation component. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Observation.html>                                                                                                                                                                                                                           |
| `PAYR-1075` | No part of found for observation component. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Observation.html>                                                                                                                                                                                                                                      |
| `PAYR-1076` | Invalid part of type found for observation component. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Observation.html>                                                                                                                                                                                                                            |
| `PAYR-1077` | No subject found for observation component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1078` | Invalid subject type found for observation component. This should be of type Patient. Hence request will not be processed further. Please try again with valid subject type for the observation.                                                                                                                                                                                                                       |
| `PAYR-1079` | No care team details received. Hence request will not be processed further. Please add the care team details and try again.                                                                                                                                                                                                                                                                                            |
| `PAYR-1080` | Invalid HPR details received for practioner resource with url %s. Hence request will not be processed further. Please try again with valid HPR id.                                                                                                                                                                                                                                                                     |
| `PAYR-1081` | Invalid service date received for item with sequence %s in claim resource. Hence request will not be processed further. Please try again with valid item service date.                                                                                                                                                                                                                                                 |
| `PAYR-1082` | Invalid title received for composition for supporting info with sequence %s in claim resource. Hence request will not be processed further. Please try again with valid composition title.                                                                                                                                                                                                                             |
| `PAYR-1083` | No HPR details found for the practitioner for resource %s. Hence request will not be processed further. Please send the details in the identifier for Practitioner resource with category code as HPIN.                                                                                                                                                                                                                |
| `PAYR-1084` | No questionnaire response resource found for url %s. Hence request will not be processed further. Please add the resources for all the references given in the FHIR bundle and try again.                                                                                                                                                                                                                              |
| `PAYR-1085` | Invalid questionnaire response resource type found in the FHIR bundle for url %s. Hence request will not be processed further.                                                                                                                                                                                                                                                                                         |
| `PAYR-1086` | No procedure resource found for url %s. Hence request will not be processed further. Please add the resources for all the references given in the FHIR bundle and try again.                                                                                                                                                                                                                                           |
| `PAYR-1087` | Invalid procedure resource type found in the FHIR bundle for url %s. Hence request will not be processed further. Procedure resource type is expected.                                                                                                                                                                                                                                                                 |
| `PAYR-1088` | Invalid composition details.                                                                                                                                                                                                                                                                                                                                                                                           |
| `PAYR-1089` | No billing items found. Hence request will not be processed further. Please try again with valid billing items.                                                                                                                                                                                                                                                                                                        |
| `PAYR-1090` | No identifier found for coverage component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1091` | No type found for coverage component identifier. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                          |
| `PAYR-1092` | Something went wrong while processing request, kindly intiate new request                                                                                                                                                                                                                                                                                                                                              |
| `PAYR-1093` | No subject found for encounter in composition component. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html>                                                                                                                                                                                                                           |
| `PAYR-1094` | Invalid subject type found for encounter in composition/observation component. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html>                                                                                                                                                                                                     |
| `PAYR-1095` | Invalid discharge information received for claim request. Hence request will not be processed further. Please send the discharge information in supporting info in claim resource, with category as DIS (refer - <https://www.nrces.in/ndhm/fhir/r4/ValueSet-ndhm-supportinginfo-category.html>), and codes in LAMA/DAMA/DTH/DTM (refer - <https://www.nrces.in/ndhm/fhir/r4/ValueSet-ndhm-supportinginfo-code.html>). |
| `PAYR-1096` | Invalid death date received for claim request. Hence request will not be processed further. Please send the death date information in supporting info in claim resource, with category as ONS (refer - <https://www.nrces.in/ndhm/fhir/r4/ValueSet-ndhm-supportinginfo-category.html>), and code as DTM (refer - <https://www.nrces.in/ndhm/fhir/r4/ValueSet-ndhm-supportinginfo-code.html>).                          |
| `PAYR-1097` | No payload found in the request. Please ensure that the request that is being sent, contains encrypted payload within the mandatory payload properties.                                                                                                                                                                                                                                                                |
| `PAYR-1098` | Value type received as %s for category - OTH and code - EDT for item with sequence %s in supporting info in claim resource. In supporting info list, item with category - OTH and code - EDT combination is used to get the registration date. So the registration date should be sent as timing (date or period) or as a string value, adhering to the NRCES standards, with the category - OTH and code - EDT.       |
| `PAYR-1099` | Value type received as %s for category - ONS and code - DSDE for item with sequence %s in supporting info in claim resource. In supporting info list, item with category - ONS and code - DSDE combination is used to get the discharge date. So the discharge date should be sent as timing (date or period) or as a string value, adhering to the NRCES standards, with the category - ONS and code - DSDE.          |

### The fifteen texts the sheet prints without a code

Directly under `PAYR-1008`, the Bridge Error sheet lists fifteen more messages with an empty code cell. The PMJAY payer sends every one of them as `PAYR-1008`, so the message is the only way to tell them apart. The sandbox run met the content type and the code-and-reason texts this way.

| Arrives as  | Message                                                                                                                                                                                                                                                                                                                                  |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PAYR-1008` | Invalid input, code and reason code received. Please try again with valid combination. To get the valid combination for task request, please refer to the document.                                                                                                                                                                      |
| `PAYR-1008` | Invalid case number received. Please try again with valid case number.                                                                                                                                                                                                                                                                   |
| `PAYR-1008` | Invalid Base64 value received in attachment. Please try again with valid Base64 value. Please refer to <https://hl7.org/fhir/R4/datatypes.html#Attachment>                                                                                                                                                                               |
| `PAYR-1008` | Invalid attachment name received in attachment. Please try again with valid name.                                                                                                                                                                                                                                                        |
| `PAYR-1008` | Invalid content type received in attachment. Please try again with valid name. Applicable content types are - application/pdf, application/jpg, application/jpeg, application/png, application/fhir+json. For further information please refer to NHCX Integration Handbook document.                                                    |
| `PAYR-1008` | No user role found/associated for sender code %s in NHCX system. Please try again with valid sender details.                                                                                                                                                                                                                             |
| `PAYR-1008` | Invalid HFR Id received. Please try again with valid HFR details.                                                                                                                                                                                                                                                                        |
| `PAYR-1008` | HFR Id in the request does not match with the associated registry id in NHCX. Please try again with valid HFR details. Please ensure the HFR id sent in the FHIR request must match with the registry id specified in NHCX for the sender.                                                                                               |
| `PAYR-1008` | Invalid Base64 value received in attachment for item \<item code>. Please try again with valid Base64 value. Please refer to <https://hl7.org/fhir/R4/datatypes.html#Attachment>                                                                                                                                                         |
| `PAYR-1008` | Invalid attachment name received in attachment for item %s. Please try again with valid name.                                                                                                                                                                                                                                            |
| `PAYR-1008` | Invalid content type received in attachment for item %s. Please try again with valid content type. Applicable content types are - application/pdf, application/jpg, application/jpeg, application/png, application/fhir+json. For further information please refer to NHCX Integration Handbook document.                                |
| `PAYR-1008` | Invalid Base64 value received in attachment for date of birth for new born beneficiary. Please try again with valid Base64 value. Please refer to <https://hl7.org/fhir/R4/datatypes.html#Attachment>                                                                                                                                    |
| `PAYR-1008` | Invalid attachment name received in attachment for date of birth for new born beneficiary. Please try again with valid name.                                                                                                                                                                                                             |
| `PAYR-1008` | Invalid content type received in attachment for date of birth for new born beneficiary. Please try again with valid content type. Applicable content types are - application/pdf, application/jpg, application/jpeg, application/png, application/fhir+json. For further information please refer to NHCX Integration Handbook document. |
| `PAYR-1008` | Invalid hospital id received. Please try again with valid hospital details.                                                                                                                                                                                                                                                              |

`PAYR-1055` and `PAYR-1060` each have two rows on the sheet as well. The tables above keep the first row of each; the second texts are "Invalid subject type found for composition component. This should be of type Patient." and "No subject found for encounter in composition component." Both arrive under the same code.

## Reference payer: coverage eligibility, `PAYR-11xx`

| Code        | Message                                                                                                                                                                                   |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PAYR-1101` | Invalid purpose received as (%s) for beneficiary id (%s) from hospital id (%s). Hence no result will be returned. Please try again with a valid purpose.                                  |
| `PAYR-1102` | Invalid search parameter requested. Please try again with a valid id.                                                                                                                     |
| `PAYR-1103` | Invalid careplan id received. Please try again with valid careplan id.                                                                                                                    |
| `PAYR-1104` | Multiple records found for the beneficiary. Hence request will not be processed further.                                                                                                  |
| `PAYR-1105` | Hospital configuration not found. Please contact support team.                                                                                                                            |
| `PAYR-1106` | No details found for the requested procedures in the system.                                                                                                                              |
| `PAYR-1107` | No billable item received. Please try again with valid item data.                                                                                                                         |
| `PAYR-1108` | No details found for the requested stratification in the system.                                                                                                                          |
| `PAYR-1109` | No details found for the requested investigations in the system.                                                                                                                          |
| `PAYR-1110` | No details found for the requested implants in the system.                                                                                                                                |
| `PAYR-1111` | Rule failure.                                                                                                                                                                             |
| `PAYR-1112` | Invalid payer id received. Please try again ith valid payer details                                                                                                                       |
| `PAYR-1113` | Invalid item code received as %s. Please try again with valid data                                                                                                                        |
| `PAYR-1114` | Invalid speciality code received as %s for item %s. Please try again with valid data. Speciality code is available as the code of the category for specific cost of plan in isurance plan |
| `PAYR-1115` | Invalid procedure quantity received as %s for item %s. Please try again with valid data. Item quantity should be greater than 1                                                           |
| `PAYR-1116` | Hospital is not authorized to raise any case under policy %s. Hence request will not be processed further. Please connect with the support team to get the required authorization         |
| `PAYR-1117` | No policy details found for %s. Hence request will not be processed further                                                                                                               |
| `PAYR-1118` | No details found for requested items. Hence request will not be processed further                                                                                                         |
| `PAYR-1119` | No payer details received for payer id %s from HCX. Please try again with valid payer details.                                                                                            |
| `PAYR-1120` | Duplicate reference id found as %s. Please try again with valid reference details.                                                                                                        |
| `PAYR-1121` | No policy details found for %s for beneficiary %s. Hence request will not be processed further.                                                                                           |
| `PAYR-1122` | No policy details found for beneficiary %s. Hence request will not be processed further.                                                                                                  |
| `PAYR-1123` | Beneficiary is not a covered member for requested payer. Please enroll beneficiary for applicable policy of requested payer and try again.                                                |

`PAYR-1114` is the one PMJAY Sandbox Run cites without defining: the specialty on `item.category` must be the code of the category the package master files the package under, not a generic value.

## Reference payer: preauthorisation, `PAYR-12xx`

| Code        | Message                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PAYR-1201` | Invalid claimed amount received for case number %s. Please try again with a valid claim amount. Claimed amount should be greater than INR 0 and less than equals to balance wallet amount of the beneficiary.                                                                                                                                                                                                                                                                                                                                                                                  |
| `PAYR-1202` | Invalid speciality code received as %s for item %s for case number %s. Please try again with valid data. Speciality code is available as the code of the category for specific cost of plan in isurance plan.                                                                                                                                                                                                                                                                                                                                                                                  |
| `PAYR-1203` | Invalid speciality description received as %s for procedure %s for case number %s. Please try again with valid data. Speciality description is available as the display of the category for specific cost of plan in isurance plan.                                                                                                                                                                                                                                                                                                                                                            |
| `PAYR-1204` | Invalid procedure code received as %s for case number %s. Please try again with valid data. Procedure code is available as the code of the type for benefit component, of specific cost, of plan in isurance plan.                                                                                                                                                                                                                                                                                                                                                                             |
| `PAYR-1205` | Invalid procedure description received as %s for procedure %s for case number %s. Please try again with valid data. Procedure description is available as the display of the type for benefit component, of specific cost, of plan in isurance plan.                                                                                                                                                                                                                                                                                                                                           |
| `PAYR-1206` | Invalid procedure type received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `PAYR-1207` | Invalid procedure factor received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `PAYR-1208` | Invalid procedure quantity received as %s for item %s for case number %s. Please try again with valid data. Item quantity should be greater than 1.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `PAYR-1209` | Invalid net amount received as INR %s for item %s for case number %s. Please try again with valid data. Item net amount should be greater than INR 0.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `PAYR-1210` | Invalid procedure status received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `PAYR-1211` | Requested beneficary details and careplan details does not match any criteria for processing the case at this hospital. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `PAYR-1212` | No previous preauthorization approved record found for the enhancement request for case number %s. Hence request will not be processed further. Please initiate a new preauthorization.                                                                                                                                                                                                                                                                                                                                                                                                        |
| `PAYR-1213` | Existing case in progress found for case number %s. Hence enhancement request will not be accepted. Please try after the adjudication is completed for the current case.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `PAYR-1214` | No previous preauthorization approved record found for the resubmission request for case number %s. Hence request will not be processed further. Please initiate a new preauthorization.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `PAYR-1215` | Existing case in progress found for case number %s. Hence resubmission request will not be accepted. Please try after the adjudication is completed for the current case.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `PAYR-1216` | Existing case in progress found for case number %s. Hence new preauthorization request will not be accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `PAYR-1217` | Previous preauthorization approved record found for the new preauthorization request for case number %s. Hence request will not be processed further. Please initiate enhancement/resubmission.                                                                                                                                                                                                                                                                                                                                                                                                |
| `PAYR-1218` | No queried preauthorization record found for the query update request for case number %s. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `PAYR-1219` | Case number %s is not queried. Hence query updation request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `PAYR-1220` | Invalid investigation description received as %s for investigation code %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1221` | Invalid investigation code received as %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `PAYR-1222` | Invalid investigation status received as %s for investigation %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `PAYR-1223` | Invalid investigation attachment received for investigation %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `PAYR-1224` | Invalid implant description received as %s for implant code %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `PAYR-1225` | Invalid implant code received as %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `PAYR-1226` | Invalid implant status received as %s for investigation %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1227` | Invalid implant attachment received for investigation %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `PAYR-1228` | Invalid implant quantity received as %s for implant %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `PAYR-1229` | Invalid implant net amount received as INR %s for implant %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `PAYR-1230` | Invalid implant unit price received as INR %s for implant %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `PAYR-1231` | Claim has already been raised for case number %s. Hence preauthorization request will not be accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `PAYR-1232` | No investigation found for case number %s. Investigation details are mandatory for private hospitals.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `PAYR-1233` | Patient liability is not aplicable for the hospital and beneficiary do not have enough wallet balance with deficit amount INR %s for the requested preauthorization for case number %s.                                                                                                                                                                                                                                                                                                                                                                                                        |
| `PAYR-1234` | No preauthorization record found for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `PAYR-1235` | Insufficient wallet balance. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `PAYR-1236` | Invalid claim type (in-patient/out-patient) received. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `PAYR-1237` | Beneficiary is having an active preauthorization request at %s. Hence the request will not be processed. Kindly inform %s to cancel the active preauthorization request or raise a claim to proceed with current preauthorization.                                                                                                                                                                                                                                                                                                                                                             |
| `PAYR-1238` | Beneficiary is having an active preauthorization request at this hospital with reference number %s. Hence the request will not be processed. Kindly cancel the active preauthorization request or raise a claim to proceed with current preauthorization.                                                                                                                                                                                                                                                                                                                                      |
| `PAYR-1239` | Hospital configuration not found. Please contact support team.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `PAYR-1240` | No details found for the requested procedures in the system.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `PAYR-1241` | Invalid registration date received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `PAYR-1242` | Invalid registration date format received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `PAYR-1243` | Invalid admission date received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `PAYR-1244` | Invalid admission date format received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `PAYR-1245` | Rule failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `PAYR-1246` | Invalid payer id received as %s. Please try again with valid payer id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `PAYR-1247` | Payer details for payer id %s is not received from HCX for the request. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1248` | Invalid item code received as %s for item sequence %s case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `PAYR-1249` | Invalid item sequence received as %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `PAYR-1250` | Requested policy %s is not listed. Please try again with valid policy code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `PAYR-1251` | No billable treatment plan received for case number %s. Please try again with valid treatment plan data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `PAYR-1252` | Case number %s is not in active preauthorization state with the current status of the case with the payer system is %s. Hence the preauthorization can not be cancelled. Only the cases with current status as preauthorization submitted or preauthorization approved can be cancelled.                                                                                                                                                                                                                                                                                                       |
| `PAYR-1253` | Case number %s is already cancelled. Hence the preauthorization can not be cancelled again. Only the cases with current status as preauthorization submitted or preauthorization approved can be cancelled.                                                                                                                                                                                                                                                                                                                                                                                    |
| `PAYR-1254` | Response for STG Questionnaire id %s is mandatory for procedure code %s. Hence the preauthorization request will not be processed as the questionnaire response is not received for procedure code.                                                                                                                                                                                                                                                                                                                                                                                            |
| `PAYR-1255` | Case number %s is already cancelled. Hence no preauthorization request will be accepted for this case number. New preauthorization request needs to be raised with new case/reference number to proceed further.                                                                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1256` | Response for Authentication Consent Questionnaire is missing for case number %s. This must be sent if the biometric authentication for patient is not available. For new preauthorization request, either biometric authentication for patient or response for Authentication Consent questionnaire must be sent. Please check/update the insurance plan for the policy for the details of the questionnaire. Please adhere to the response of the coverage eligibility for auth-requirements purpose to check the mandatory documents to be attached with the request                         |
| `PAYR-1257` | Payment is initiated for case number %s. Hence the preauthorization can not be cancelled again. Only the cases with current status as preauthorization submitted or preauthorization approved can be cancelled                                                                                                                                                                                                                                                                                                                                                                                 |
| `PAYR-1258` | Payment is accomplished/cleared for case number %s. Hence the preauthorization can not be cancelled again. Only the cases with current status as preauthorization submitted or preauthorization approved can be cancelled                                                                                                                                                                                                                                                                                                                                                                      |
| `PAYR-1259` | DOB is missing for new born for the case number (%s) with correlation id as (%s) at (%s)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `PAYR-1260` | DOB cannot be a future date for the case number (%s) with correlation id as (%s) at (%s)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `PAYR-1261` | Invalid new born details for the case number (%s) with correlation id as (%s) at (%s)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `PAYR-1262` | Gender is mandatory for the new born beneficiary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1263` | Documents are mandatory for the new born beneficiary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `PAYR-1264` | Documents are mandatory for the new born beneficiary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `PAYR-1265` | Documents are mandatory for the new born beneficiary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `PAYR-1266` | Documents are mandatory for the new born beneficiary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `PAYR-1267` | Beneficiary is having an active preauthorization request for new born case at this hospital with reference number %s. Hence the request will not be processed. Kindly cancel the active preauthorization request or raise a claim to proceed with current preauthorization                                                                                                                                                                                                                                                                                                                     |
| `PAYR-1268` | Beneficiary is having an active preauthorization request for new born case at %s. Hence the request will not be processed. Kindly inform %s to cancel the active preauthorization request or raise a claim to proceed with current preauthorization                                                                                                                                                                                                                                                                                                                                            |
| `PAYR-1269` | Date of birth received for new born beneficiary exceeds 6 years before the current date. New born cases can be raised only for the beneficiary whose date of birth is within 6 years of current date                                                                                                                                                                                                                                                                                                                                                                                           |
| `PAYR-1270` | Item LM100 is not applicable for preauthorization request. This item is expected/mandated only during claim submission if the patient is discharged after/during surgery under LAMA/DAMA category for PMJAY cases.                                                                                                                                                                                                                                                                                                                                                                             |
| `PAYR-1271` | No value received for link id %s for Authentication Consent Questionnaire for preauthorization request. This must be sent if the biometric authentication for patient is not available. For new preauthorization request, either biometric authentication for patient or response for Authentication Consent questionnaire must be sent. Please check/update the insurance plan for the policy for the details of the questionnaire. Please adhere to the response of the coverage eligibility for auth-requirements purpose to check the mandatory documents to be attached with the request. |
| `PAYR-1272` | Invalid biometric user token received. Please try again with valid valid biometric details of the beneficiary. For any issues with biometric, please try with Authentication Consent Questionnaire, details for which has been received in response for coverage eligibliity auth-requirements.                                                                                                                                                                                                                                                                                                |
| `PAYR-1273` | No questionnaire found for the received selection. Please validate the questionnaire url from insurance plan/coverage auth-requirements response.                                                                                                                                                                                                                                                                                                                                                                                                                                              |

## Reference payer: claim, `PAYR-13xx`

| Code        | Message                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `PAYR-1301` | Claim has already been raised for case number %s. Hence new claim request will not be accepted.                                                                                                                                                                                                                                                                                                                                                              |
| `PAYR-1302` | No preauthorization approved record found for case number %s. Hence new claim request will not be accepted.                                                                                                                                                                                                                                                                                                                                                  |
| `PAYR-1303` | No active claim record found for case number %s. Hence query updation request will not be accepted.                                                                                                                                                                                                                                                                                                                                                          |
| `PAYR-1304` | No claim queried record found for case number %s. Hence query updation request will not be accepted.                                                                                                                                                                                                                                                                                                                                                         |
| `PAYR-1305` | Invalid usecase requested for case number %s. Please try again with valid usecase.                                                                                                                                                                                                                                                                                                                                                                           |
| `PAYR-1306` | No item found in preauthorization request for procedure %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                      |
| `PAYR-1307` | Invalid quantity requested for procedure %s with item sequence %s for case number %s. Please try again with valid quantity.                                                                                                                                                                                                                                                                                                                                  |
| `PAYR-1308` | No item found in active claim request for procedure %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                          |
| `PAYR-1309` | No item found in preauthorization request for implant %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                        |
| `PAYR-1310` | Invalid quantity requested for implant %s with item sequence %s for case number %s. Please try again with valid quantity.                                                                                                                                                                                                                                                                                                                                    |
| `PAYR-1311` | No item found in active claim request for implant %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                            |
| `PAYR-1312` | No item found in preauthorization request for investigation %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                  |
| `PAYR-1313` | Invalid quantity requested for investigation %s with item sequence %s for case number %s. Please try again with valid quantity.                                                                                                                                                                                                                                                                                                                              |
| `PAYR-1314` | No item found in active claim request for investigation %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                      |
| `PAYR-1315` | Rejected item found for preauthorization for procedure %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                       |
| `PAYR-1316` | Rejected item found for preauthorization for investigation %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                   |
| `PAYR-1317` | Rejected item found for preauthorization for implant %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                         |
| `PAYR-1318` | No requested treatment plan found for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                                                                     |
| `PAYR-1319` | No requested investigation plan found for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                                                                 |
| `PAYR-1320` | No details found for the requested investigations in the system. Hence request will not be processed.                                                                                                                                                                                                                                                                                                                                                        |
| `PAYR-1321` | Error occurred while processing the request due to invalid workflow id as (%s)                                                                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1322` | No active case found for the given case number.                                                                                                                                                                                                                                                                                                                                                                                                              |
| `PAYR-1323` | Insufficient wallet balance. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                        |
| `PAYR-1324` | Invalid discharge stage received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                |
| `PAYR-1325` | Invalid admission date received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                 |
| `PAYR-1326` | Invalid discharge date received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                 |
| `PAYR-1327` | Invalid admission date format received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                          |
| `PAYR-1328` | Invalid discharge date format received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                          |
| `PAYR-1329` | Invalid registration date received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                              |
| `PAYR-1330` | Invalid registration date format received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                       |
| `PAYR-1331` | Receiver not registered in NHCX. Please try again with valid receiver details.                                                                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1332` | Invalid CRC request.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `PAYR-1333` | Invalid claim type (in-patient/out-patient) received. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1334` | Hospital configuration not found. Please contact support team.                                                                                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1335` | Invalid implant quantity received as %s for implant %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                 |
| `PAYR-1336` | Invalid implant unit price received as INR %s for implant %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                           |
| `PAYR-1337` | Invalid implant net amount received as INR %s for implant %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                           |
| `PAYR-1338` | Invalid implant attachment received for investigation %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1339` | Invalid implant status received as %s for investigation %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                             |
| `PAYR-1340` | Invalid investigation status received as %s for investigation %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                       |
| `PAYR-1341` | Invalid investigation attachment received for investigation %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                         |
| `PAYR-1342` | Existing case in progress found for case number %s. Hence new reimbursement request will not be accepted.                                                                                                                                                                                                                                                                                                                                                    |
| `PAYR-1343` | Previous reimbursement approved record found for the new reimbursement request for case number %s. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                              |
| `PAYR-1344` | No details found for the requested procedures in the system.                                                                                                                                                                                                                                                                                                                                                                                                 |
| `PAYR-1345` | Invalid procedure status received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1346` | Invalid procedure description received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                          |
| `PAYR-1347` | Invalid procedure type received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                 |
| `PAYR-1348` | Invalid procedure factor received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1349` | Invalid procedure quantity received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                             |
| `PAYR-1350` | Invalid procedure net amount received as INR %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                       |
| `PAYR-1351` | Invalid speciality code received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                |
| `PAYR-1352` | Requested beneficary details and careplan details does not match any criteria for processing the case at this hospital. Please try again with valid data.                                                                                                                                                                                                                                                                                                    |
| `PAYR-1353` | Invalid careplan id received. Please try again with valid careplan id.                                                                                                                                                                                                                                                                                                                                                                                       |
| `PAYR-1354` | Rule failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `PAYR-1355` | No details found for the requested implants in the system. Hence request will not be processed.                                                                                                                                                                                                                                                                                                                                                              |
| `PAYR-1356` | Patient liability is not aplicable for the hospital and beneficiary do not have enough wallet balance with deficit amount INR %s for the requested preauthorization for case number %s.                                                                                                                                                                                                                                                                      |
| `PAYR-1357` | Admission date cannot be after the discharge date. Hence request will not be processed. Please correct the data and try again.                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1358` | Registration of the patient is allowed maximum upto %s days after admission. Hence request will not be processed. Please correct the data and try again.                                                                                                                                                                                                                                                                                                     |
| `PAYR-1359` | No billable treatment plan received for case number %s. Please try again with valid treatment plan data.                                                                                                                                                                                                                                                                                                                                                     |
| `PAYR-1360` | Invalid item code received as %s for item sequence %s case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                      |
| `PAYR-1361` | Invalid item sequence received as %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                   |
| `PAYR-1362` | No procedure with code LM100 received with 'Requested' status for case number %s. Please try again with valid data. For PMJAY claims, if case comes under LAMA/DAMA scenario with beneficiary being discharged before surgery or during surgery, procedure with code LM100 is mandatory. Only this procedure code will be accepted for LAMA/DAMA case, and all other previous preauthorization approved items will get disqualified for the claim submission |
| `PAYR-1363` | Response for Authentication Consent Questionnaire is missing for case number %s. This must be sent if the biometric authentication for patient is not available during discharge. For new claim request, either biometric authentication for patient during discharge, or response for Authentication Consent questionnaire must be sent. Please check/update the insurance plan for the policy for the details of the questionnaire.                        |
| `PAYR-1364` | No value received for link id %s for Authentication Consent Questionnaire for claim request. This must be sent if the biometric authentication for patient is not available during discharge. For new claim request, either biometric authentication for patient during discharge, or response for Authentication Consent questionnaire must be sent. Please check/update the insurance plan for the policy for the details of the questionnaire.            |
| `PAYR-1365` | Response for STG Questionnaire id %s is mandatory for procedure code %s. Hence the preauthorization request will not be processed as the questionnaire response is not received for procedure code.                                                                                                                                                                                                                                                          |
| `PAYR-1366` | Invalid biometric user token received. Please try again with valid biometric details of the beneficiary. For any issues with biometric, please try with Authentication Consent Questionnaire for discharge, details for which has been received in insurance plan.                                                                                                                                                                                           |
| `PAYR-1367` | No biometric records found for the beneficiary for %s. Please ensure correctness of biometric authentication date for the day for cyclic procedure %s.                                                                                                                                                                                                                                                                                                       |
| `PAYR-1368` | %s units of cycle information received for procedure code %s with item sequence %s. Cycle information should be sent for all the requested/processed cycles.                                                                                                                                                                                                                                                                                                 |
| `PAYR-1369` | Biometric authentication cannot be performed more than once on the same date. Multiple biometric authentication information has been provided for same date for cyclic procedure %s. Hence case will not be processed. Please check and update biometric authentication execution dates and try again.                                                                                                                                                       |
| `PAYR-1370` | Received invalid start date as %s for supporting details with item sequence %s. Please try again with valid start date.                                                                                                                                                                                                                                                                                                                                      |

## Reference payer: plan and scheme rules, `PAYR-14xx` and above

| Code        | Message                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PAYR-1401` | \<policy\_code> policy not allowed for the hospital. Please reach out to technical support team.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `PAYR-1402` | Requested policy \<policy\_code> found not be associated with any payer for insurance plan request. Hence request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `PAYR-1403` | Requested renewal \<renewal\_code> found not be associated with requested policy \<policy\_code> for insurance plan request. Hence request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `PAYR-1404` | No treatment provided for policy \<policy\_code> under any speciality. Please reach out to technical support team.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `PAYR-1405` | No enrolled hospital found for HFR id \<hfr\_id> or sender id \<sender\_code>. Please reach out to technical support team.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `PAYR-1406` | Existing request with correlation id %s is in progress with the payer. Hence this request will not be accepted until the execution for previous request is complete. Please wait for 15 - 60 minutes to allow the execution of previous requests. For further assistance, please reach out to technical support team.                                                                                                                                                                                                                                                                                                             |
| `PAYR-1501` | Value type received as %s for category - ONS and code - PSP for item with sequence %s in supporting info in claim resource. In supporting info list, item with category - ONS and code - PSP combination is used to get the surgery date. So the surgery date should be sent as timing (date or period) or as a string value, adhering to the NRCES standards, with the category - ONS and code - PSP.                                                                                                                                                                                                                            |
| `PAYR-1502` | Value type received as %s for category - ONS and code - ADDD for item with sequence %s in supporting info in claim resource. In supporting info list, item with category - ONS and code - ADDD combination is used to get the admission date. So the admission date should be sent as timing (date or period) or as a string value, adhering to the NRCES standards, with the category - ONS and code - ADDD.                                                                                                                                                                                                                     |
| `PAYR-1503` | Value type received as %s for category - ONS and code - DTM for item with sequence %s in supporting info in claim resource. In supporting info list, item with category - ONS and code - DTM combination is used to get the death date. So the death date should be sent as timing (date or period) or as a string value, adhering to the NRCES standards, with the category - ONS and code - DTM.                                                                                                                                                                                                                                |
| `PAYR-1504` | Value type received as %s for category - NMI and code - CQD for item with sequence %s in supporting info in claim resource. In supporting info list, item with category - NMI and code - CQD combination is used to get the overall case remarks for query response. So the case remarks for query response should be sent as a string value, adhering to the NRCES standards, with the category - NMI and code - CQD.                                                                                                                                                                                                            |
| `PAYR-1505` | Category received as %s and code received as %s for item with sequence %s in supporting info in claim resource, where the reference value redirects to Questionnaire Response resource in the FHIR bundle. To include a policy/case level Questionnaire Response, in supporting info list there should be an entry with category - INF and code - ODN , and the value as reference. This reference value should refer to a resource of Questionnaire Response in the FHIR bundle. To include response for any STG questionnaire, in supporting info list there should be an entry with category - STG, and the value as reference |
| `PAYR-1506` | Invalid gender received for new born patient. Please try agian with valid gender data as it is mandatory for PMJAY in new born case. Please refer to the valid gender values at <https://hl7.org/fhir/R4/valueset-administrative-gender.html>                                                                                                                                                                                                                                                                                                                                                                                     |
| `PAYR-1507` | Invalid date of birth received for new born patient. Please try agian with valid date of birth as it is mandatory for PMJAY in new born case.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `PAYR-1508` | Invalid resource received for new born patient for url %s. Please try agian with valid Patient resource for the link reference as linked Patient resource is mandatory for PMJAY in new born case                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `PAYR-1509` | Invalid attachment received for new born patient. Please try agian with valid attachment as attachment is mandatory for PMJAY in new born case                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `PAYR-1510` | Invalid parameter code received. Please check and try again with a valid parameter code                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `PAYR-1511` | Invalid parameter value received. Please check and try again with a valid parameter value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `PAYR-1512` | Invalid resource received for patient for url %s. Please try agian with valid Patient resource for the reference                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `PAYR-1513` | Invalid diagnosis received in DiagnosisComponent. In DiagnosisComponent, diagnosis should be sent as CodeableConcept. Please try agian with valid data                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `PAYR-1514` | Value type received as %s for category - DIS for item with sequence %s in supporting info in claim resource. In supporting info list, item with category - DIS is used to get the discharge related information. So the discharge information should be sent as string value, with value representing discharge stage (After Surgery / Before Surgery / During Surgery), with the category - DIS and code - DTH/LAMA/DAMA/DTM                                                                                                                                                                                                     |
| `PAYR-1515` | Invalid name received for organization resource with url %s. Name is mandatory for organization resource. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html>                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `PAYR-1516` | No event found for api-caller-id %s and correlation id %s for sender code %s. Hence error response willnot be accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `PAYR-1517` | Invalid error structure received for NHCX error. Protocol response structure is expected, but received JWEPayloadResponse.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `PAYR-1518` | No input parameters received for task resource. Input parameters are expected for task resource, but not received. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `PAYR-1519` | No type found for task input parameters. Hence request will not be processed further. Please refer to <https://www.nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html>                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `PAYR-1520` | Invalid resource received for communication for url %s. Please try agian with valid Communication resource for the reference.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

## What the live payer sent that the sheets do not say

The SHA HP sandbox run recorded in PMJAY Sandbox Run met three codes whose live message is not the one in the tables above. The tables keep the sheet's message; the live one is here.

| Code              | The sheet says                                  | The sandbox sent                                                | What it meant                                                            |
| ----------------- | ----------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `PAYR-1245`       | Rule failure.                                   | Only one conservative procedure can be booked for a case        | An enhancement added a second `Conservative` package                     |
| `PAYR-1322`       | No active case found for the given case number. | Active instance found for case number                           | A second request on a case while the first was still queued              |
| `ERR-PYR-CLM-007` | On no sheet                                     | No prior preauthorization or claim record found for case number | The claim went out under a number of its own, not the preauthorisation's |

`PAYR-1322` is the one to watch: the sheet and the live message point opposite ways. Act on the live reading and wait for the open request to be decided. `PAYR-1245` is one of three codes the sheet gives only as "Rule failure", with `PAYR-1111` and `PAYR-1354`, and the live message names the rule. None of the live messages is published; confirm them with the payer before you key logic on them.

## Denial codes are a separate thing again

A refusal stops a message. A denial decides a case. The denial families, `ClaimError-1` to `ClaimError-28` and `PreauthError-1` to `PreauthError-15` with no 14 defined, arrive inside an adjudicated `ClaimResponse` and are the adjudicator's reason, not a fault in what you sent. They belong on the appeal screen. Codes and Value Sets in the FHIR Reference lists them.

## Which desk gets which

| Family                              | Who acts                                                                                     |
| ----------------------------------- | -------------------------------------------------------------------------------------------- |
| `NHCX-`                             | The integration team. The message did not arrive                                             |
| `PAYR-10xx`                         | The integration team. Structural                                                             |
| `ERR-PYR-CLM-007`                   | The integration team. The claim was sent under the wrong case number                         |
| `PAYR-11xx` to `PAYR-14xx`          | Read the message. Some name a field, some name a policy fact. The band alone does not decide |
| Standard `PAYR-1001` to `PAYR-1020` | The claims desk, in the payer's own words                                                    |
| `ClaimError-`, `PreauthError-`      | The claims desk, on the appeal screen                                                        |

Show the payer's sentence verbatim in every case. The reference payer's messages already name the field, the code or the case number, and a system that rewrites them into a generic failure throws away the only diagnosis available.


---

# Error codes

Read [reading error codes](/docs/nhcx/v1/reference/error-code-guide) first. Eighteen `PAYR-` codes mean different things from two payers, and this list cannot show which reading you have met.

A code is on this page because the Catalogue records it. The specifications carry no code in their response examples, because a code reaches you sealed inside a callback rather than in the response to your call.

## ERR-PYR-CLM

| Code              | What it means                                                   | Arrives on                                |
| ----------------- | --------------------------------------------------------------- | ----------------------------------------- |
| `ERR-PYR-CLM-007` | No preauthorisation or claim exists for the claim's case number | `/v1/claim/on_submit`, `/v1/claim/submit` |

## NHCX

| Code        | What it means                                                            | Arrives on                                  |
| ----------- | ------------------------------------------------------------------------ | ------------------------------------------- |
| `NHCX-401`  | The exchange does not accept your authorisation for this call            | `/v1/error`, `/v3/sessions`                 |
| `NHCX-1001` | The recipient's system is not reachable                                  | `/v1/error`                                 |
| `NHCX-1002` | The sender is not a registered participant                               | `/v1/error`                                 |
| `NHCX-1003` | The recipient is not a registered participant                            | `/v1/error`, `/v2/participant/get/policies` |
| `NHCX-1004` | No recipient is registered for the scheme you asked for                  | `/v1/error`, `/v2/participant/get/policies` |
| `NHCX-1005` | A request header is missing or not valid                                 | `/v1/error`                                 |
| `NHCX-1006` | The correlation id has already been used                                 | `/v1/error`                                 |
| `NHCX-1007` | The exchange could not process the request's structure or values         | `/v1/error`                                 |
| `NHCX-1008` | The exchange had a temporary failure                                     | `/v1/error`                                 |
| `NHCX-1009` | The exchange failed and recorded the cause in its own logs               | `/v1/error`                                 |
| `NHCX-1010` | No request matches the correlation id on your answer                     | `/v1/error`, `/v1/status`                   |
| `NHCX-1011` | The x-hcx-status value is not valid                                      | `/v1/error`                                 |
| `NHCX-1012` | No message matches the api\_call\_id you gave                            | `/v1/error`, `/v1/on_status`, `/v1/status`  |
| `NHCX-1013` | The request body is empty or not valid                                   | `/v1/error`                                 |
| `NHCX-1014` | The exchange could not deliver the response to its sender                | `/v1/error`                                 |
| `NHCX-1015` | The client is not allowed to change this participant's registry details  | `/v2/participant/update`, `/v2/update/cert` |
| `NHCX-1016` | The call does not fit the exchange open on this correlation id           | `/v1/error`                                 |
| `NHCX-1017` | The recipient answered a delivery in a form the exchange does not accept | `/v1/error`                                 |
| `NHCX-1018` | The ABHA number is not in the XX-XXXX-XXXX-XXXX form                     | `/v1/error`                                 |

## PAYR

| Code        | What it means                                                                                                                | Arrives on                                                                                                                                                                                                                 |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PAYR-1001` | The recipient could not decrypt your request                                                                                 | `/v1/claim/on_submit`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`                                                                                                                                         |
| `PAYR-1002` | The payer could not encrypt its answer to you                                                                                | `/v1/claim/on_submit`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v2/update/cert`                                                                                                                      |
| `PAYR-1003` | The payer's system could not reach the exchange and will resend, or the workflow requested is not valid                      | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1004` | Your facility is not registered with the payer for the policy, or the FHIR bundle is malformed                               | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1005` | The beneficiary is not a covered member of the policy, or the request is more than 24 hours old                              | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1006` | The policy does not exist, or a name in the request is not valid                                                             | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1007` | The policy has expired, or the gender in the request is not valid                                                            | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1008` | The beneficiary's remaining cover is not enough for the request, or the FHIR bundle is not valid or cannot be parsed         | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1009` | The requested items are not valid or not covered, or the Patient resource has no identifier                                  | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1010` | A preauthorisation was required but not obtained, or the Patient identifier has no type                                      | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1011` | The approved package does not support enhancement, or the Claim resource has no identifier                                   | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1012` | The claim amount is more than the approved preauthorisation amount, or the Claim identifier has no type                      | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1013` | The procedures or packages have no prior approval, or the provider Organization resource has no identifier                   | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1014` | The date of birth is after the date of service, or the provider Organization identifier has no type                          | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1015` | The date of service is after the date of death, or the payer Organization resource has no identifier                         | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1016` | The claim duplicates one already submitted for the same services and dates, or the payer Organization identifier has no type | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1017` | The amount calculations are not correct, or the Task resource has no task code                                               | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`, `/v1/task/on_submit`, `/v1/task/submit`                                                                                          |
| `PAYR-1018` | The time limit for submission has expired, or the Task resource has no reason code                                           | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`, `/v1/task/on_submit`, `/v1/task/submit`                                                                                          |
| `PAYR-1019` | The additional information the payer asked for did not arrive in time, or a supporting info sequence is not valid            | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1020` | The payer holds no valid bank details for your facility, or a supporting info category is not valid                          | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/paymentnotice/request`                                                                                                                                                     |
| `PAYR-1021` | A supporting info entry has an invalid code                                                                                  | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1023` | A procedure has an invalid category                                                                                          | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1024` | A procedure has an invalid status                                                                                            | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1025` | A procedure has an invalid sequence                                                                                          | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1026` | The claim references a procedure that is not in the bundle                                                                   | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1027` | A claim item has an invalid id                                                                                               | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1028` | A claim item has an invalid sequence                                                                                         | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1029` | The bundle id is invalid                                                                                                     | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1030` | A questionnaire id in the bundle is invalid                                                                                  | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1031` | A bundle entry has an invalid URL                                                                                            | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1032` | The eligibility check has an invalid purpose                                                                                 | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1033` | The eligibility check has no items for its purpose                                                                           | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1034` | A procedure code is invalid                                                                                                  | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1035` | The policy code is invalid                                                                                                   | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/insuranceplan/on_request`, `/v1/insuranceplan/request`, `/v1/preauth/on_submit`, `/v1/preauth/submit` |
| `PAYR-1036` | A supporting info entry lacks a valid attachment                                                                             | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1037` | The communication has no identifier                                                                                          | `/v1/communication/on_request`, `/v1/communication/request`                                                                                                                                                                |
| `PAYR-1038` | The communication identifier has no type                                                                                     | `/v1/communication/on_request`, `/v1/communication/request`                                                                                                                                                                |
| `PAYR-1039` | The communication has no payload                                                                                             | `/v1/communication/on_request`, `/v1/communication/request`                                                                                                                                                                |
| `PAYR-1040` | A reference points at a resource that is not in the bundle                                                                   | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1041` | A procedure has no identifier                                                                                                | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1042` | A procedure identifier has no type                                                                                           | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1043` | A date is in the wrong format                                                                                                | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1044` | A date and time is in the wrong format                                                                                       | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1045` | A claim item has an invalid quantity                                                                                         | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1046` | A supporting info entry has no value or date                                                                                 | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1047` | A supporting info entry has an invalid reference                                                                             | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1048` | A supporting info entry references a resource that is not in the bundle                                                      | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1049` | The payer cannot accept the bundle                                                                                           | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1050` | A practitioner identifier has no type                                                                                        | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1051` | A clinical record has no section                                                                                             | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1052` | A clinical record section has no references                                                                                  | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1053` | A nested clinical record section has an invalid reference                                                                    | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1054` | A clinical record section is empty                                                                                           | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1055` | A clinical record has no subject or its subject is not a patient                                                             | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1056` | The patient's contact organization is not an Organization                                                                    | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1057` | The patient's general practitioner has the wrong type                                                                        | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1058` | The patient's managing organization is not an Organization                                                                   | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1059` | A clinical record points at something other than an encounter                                                                | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1060` | A clinical record has no encounter or its encounter has no subject                                                           | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1061` | An encounter's subject has the wrong resource type                                                                           | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1062` | An encounter has no episode of care the payer can find                                                                       | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1063` | An encounter's episode of care has the wrong resource type                                                                   | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1064` | An encounter has no based-on reference the payer can find                                                                    | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1065` | An encounter's based-on reference has the wrong resource type                                                                | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1066` | An encounter has no appointment the payer can find                                                                           | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1067` | An encounter's appointment has the wrong resource type                                                                       | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1068` | An encounter has no reason reference the payer can find                                                                      | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1069` | An encounter's reason reference has the wrong resource type                                                                  | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1070` | A composition has no author                                                                                                  | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1071` | A composition's author has the wrong resource type                                                                           | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1072` | A claim procedure has no procedure reference                                                                                 | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1073` | An observation has no based-on reference                                                                                     | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1074` | An observation's based-on reference has the wrong resource type                                                              | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1075` | An observation has no part-of reference                                                                                      | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1076` | An observation's part-of reference has the wrong resource type                                                               | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1077` | An observation has no subject                                                                                                | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1078` | An observation's subject is not a Patient                                                                                    | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1079` | The claim has no care team                                                                                                   | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1080` | A practitioner's HPR id is not valid                                                                                         | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1081` | An item's service date is not valid                                                                                          | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1082` | A composition linked from supporting info has an invalid title                                                               | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1083` | A practitioner has no HPR id                                                                                                 | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1084` | A reference points at a questionnaire response that is not in the bundle                                                     | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1085` | A questionnaire response reference points at the wrong resource type                                                         | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1086` | A reference points at a procedure that is not in the bundle                                                                  | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1087` | A procedure reference points at the wrong resource type                                                                      | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1088` | A composition failed the payer's checks                                                                                      | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1089` | The claim has no billing items                                                                                               | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1090` | The coverage has no identifier                                                                                               | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1091` | The coverage identifier has no type                                                                                          | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1092` | The payer failed while processing your request                                                                               | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1093` | An encounter linked from a composition has no subject                                                                        | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1094` | An encounter's subject has the wrong resource type                                                                           | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1095` | The claim carries no valid discharge information                                                                             | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1096` | A death discharge carries no valid death date                                                                                | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1097` | The request arrived with no encrypted payload                                                                                | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1098` | The registration date has the wrong value type                                                                               | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1099` | The discharge date has the wrong value type                                                                                  | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1101` | The eligibility purpose is not valid                                                                                         | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                         |
| `PAYR-1102` | The id you searched with is not valid                                                                                        | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1103` | The care plan id is not valid                                                                                                | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                         |
| `PAYR-1104` | More than one beneficiary record matches                                                                                     | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                         |
| `PAYR-1105` | The payer has no configuration for your hospital                                                                             | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1106` | The payer has no details for a requested procedure                                                                           | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1107` | The check carries no billable item                                                                                           | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1108` | The payer has no details for the requested stratification                                                                    | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1109` | The payer has no details for a requested investigation                                                                       | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1110` | The payer has no details for a requested implant                                                                             | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1111` | A payer rule rejected the request                                                                                            | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1112` | The payer id is not valid                                                                                                    | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1113` | An item code is not valid                                                                                                    | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1114` | An item's speciality code is not valid                                                                                       | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1115` | An item's quantity is not valid                                                                                              | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1116` | Your hospital is not authorised under the policy                                                                             | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1117` | The payer has no details for the policy                                                                                      | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1118` | The payer has no details for the requested items                                                                             | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1119` | The payer received no details for the payer id from the exchange                                                             | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1120` | The reference id has been used before                                                                                        | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1121` | The policy is not found for this beneficiary                                                                                 | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1122` | The beneficiary has no policy with the payer                                                                                 | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1123` | The beneficiary is not covered by this payer                                                                                 | `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`                                                                                                                                                        |
| `PAYR-1201` | Claimed amount is zero or above the wallet balance                                                                           | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1202` | Speciality code is not in the insurance plan                                                                                 | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1203` | Speciality description does not match the insurance plan                                                                     | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1204` | Procedure code is not in the insurance plan                                                                                  | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1205` | Procedure description does not match the insurance plan                                                                      | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1206` | Procedure type is not accepted                                                                                               | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1207` | Procedure factor is not accepted                                                                                             | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1208` | Item quantity is not accepted                                                                                                | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1209` | Item net amount is zero or less                                                                                              | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1210` | Procedure status is not accepted                                                                                             | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1211` | Beneficiary and care plan match no rule at this hospital                                                                     | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1212` | Enhancement has no approved preauthorisation                                                                                 | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1213` | Enhancement sent while the case is still in progress                                                                         | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1214` | Resubmission has no approved preauthorisation                                                                                | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1215` | Resubmission sent while the case is still in progress                                                                        | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1216` | New preauthorisation sent for a case already in progress                                                                     | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1217` | New preauthorisation sent for a case already approved                                                                        | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1218` | Query response sent for a case that was not queried                                                                          | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1219` | Case is not in the queried state                                                                                             | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1220` | Investigation description does not match its code                                                                            | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1221` | Investigation code is not valid                                                                                              | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1222` | Investigation status is not accepted                                                                                         | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1223` | Investigation attachment is not valid                                                                                        | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1224` | Implant description does not match its code                                                                                  | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1225` | Implant code is not valid                                                                                                    | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1226` | Implant status is not accepted                                                                                               | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1227` | Implant attachment is not valid                                                                                              | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1228` | Implant quantity is not accepted                                                                                             | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1229` | Implant net amount is not accepted                                                                                           | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1230` | Implant unit price is not accepted                                                                                           | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1231` | Claim already raised for this case                                                                                           | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1232` | Investigations missing for a private hospital                                                                                | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1233` | Wallet short and patient liability not allowed                                                                               | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1234` | No preauthorisation found for the case number                                                                                | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1235` | Wallet balance is insufficient                                                                                               | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1236` | Claim type is not in-patient or out-patient                                                                                  | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1237` | Beneficiary has an active preauthorisation at another hospital                                                               | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1238` | Beneficiary has an active preauthorisation at your hospital                                                                  | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1239` | Hospital configuration not found                                                                                             | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1240` | Requested procedures not found                                                                                               | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1241` | Registration date is not valid                                                                                               | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1242` | Registration date format is not valid                                                                                        | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1243` | Admission date is not valid                                                                                                  | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1244` | Admission date format is not valid                                                                                           | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1245` | A scheme rule failed                                                                                                         | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1246` | Payer id is not valid                                                                                                        | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1247` | Payer details not received from the exchange                                                                                 | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1248` | Item code is not valid                                                                                                       | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1249` | Item sequence is not valid                                                                                                   | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1250` | Policy is not listed                                                                                                         | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1251` | No billable treatment plan                                                                                                   | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1252` | Case is not in a state that can be cancelled                                                                                 | `/v1/preauth/on_submit`, `/v1/preauth/submit`, `/v1/task/on_submit`, `/v1/task/submit`                                                                                                                                     |
| `PAYR-1253` | Case is already cancelled                                                                                                    | `/v1/preauth/on_submit`, `/v1/preauth/submit`, `/v1/task/on_submit`, `/v1/task/submit`                                                                                                                                     |
| `PAYR-1254` | Treatment guideline questionnaire response missing                                                                           | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1255` | Case number already cancelled                                                                                                | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1256` | No biometric authentication and no consent questionnaire                                                                     | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1257` | Payment already initiated for the case                                                                                       | `/v1/preauth/on_submit`, `/v1/preauth/submit`, `/v1/task/on_submit`, `/v1/task/submit`                                                                                                                                     |
| `PAYR-1258` | Payment already cleared for the case                                                                                         | `/v1/preauth/on_submit`, `/v1/preauth/submit`, `/v1/task/on_submit`, `/v1/task/submit`                                                                                                                                     |
| `PAYR-1259` | Newborn date of birth missing                                                                                                | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1260` | Newborn date of birth is in the future                                                                                       | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1261` | Newborn details are not valid                                                                                                | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1262` | Newborn gender missing                                                                                                       | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1263` | Newborn documents missing                                                                                                    | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1264` | Newborn documents missing                                                                                                    | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1265` | Newborn documents missing                                                                                                    | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1266` | Newborn documents missing                                                                                                    | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1267` | Active newborn preauthorisation at your hospital                                                                             | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1268` | Active newborn preauthorisation at another hospital                                                                          | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1269` | Newborn is older than 6 years                                                                                                | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1270` | Item LM100 sent on a preauthorisation                                                                                        | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1271` | Consent questionnaire answer missing                                                                                         | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1272` | Biometric user token is not valid                                                                                            | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1273` | Questionnaire not found for the selection                                                                                    | `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                                                              |
| `PAYR-1301` | A claim already exists for this case                                                                                         | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1302` | No approved preauthorisation for this case                                                                                   | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1303` | No active claim to update for this case                                                                                      | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1304` | The claim for this case is not under query                                                                                   | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1305` | The use case is not valid for this case                                                                                      | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1306` | The procedure is not in the preauthorisation request                                                                         | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1307` | The procedure quantity is not valid                                                                                          | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1308` | The procedure is not in the active claim                                                                                     | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1309` | The implant is not in the preauthorisation request                                                                           | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1310` | The implant quantity is not valid                                                                                            | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1311` | The implant is not in the active claim                                                                                       | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1312` | The investigation is not in the preauthorisation request                                                                     | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1313` | The investigation quantity is not valid                                                                                      | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1314` | The investigation is not in the active claim                                                                                 | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1315` | The procedure was rejected at preauthorisation                                                                               | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1316` | The investigation was rejected at preauthorisation                                                                           | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1317` | The implant was rejected at preauthorisation                                                                                 | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1318` | The claim has no requested treatment plan                                                                                    | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1319` | The claim has no requested investigation plan                                                                                | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1320` | The payer has no details for the requested investigations                                                                    | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1321` | The workflow id is not valid for this step                                                                                   | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1322` | The case is not in a state that accepts this request                                                                         | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1323` | The beneficiary's wallet balance is too low                                                                                  | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1324` | The discharge stage is not valid                                                                                             | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1325` | The admission date is not valid                                                                                              | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1326` | The discharge date is not valid                                                                                              | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1327` | The admission date is in the wrong format                                                                                    | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1328` | The discharge date is in the wrong format                                                                                    | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1329` | The registration date is not valid                                                                                           | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1330` | The registration date is in the wrong format                                                                                 | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1331` | The receiver is not registered in NHCX                                                                                       | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1332` | The Claim Review Committee request is not valid                                                                              | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1333` | The claim type is not valid                                                                                                  | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1334` | The payer has no configuration for your hospital                                                                             | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1335` | The implant quantity is not valid                                                                                            | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1336` | The implant unit price is not valid                                                                                          | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1337` | The implant net amount is not valid                                                                                          | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1338` | The implant attachment is not valid                                                                                          | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1339` | The implant status is not valid                                                                                              | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1340` | The investigation status is not valid                                                                                        | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1341` | The investigation attachment is not valid                                                                                    | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1342` | A case in progress blocks a new reimbursement request                                                                        | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1343` | A reimbursement was already approved for this case                                                                           | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1344` | The payer has no details for the requested procedures                                                                        | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1345` | The procedure status is not valid                                                                                            | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1346` | The procedure description is not valid                                                                                       | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1347` | The procedure type is not valid                                                                                              | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1348` | The procedure factor is not valid                                                                                            | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1349` | The procedure quantity is not valid                                                                                          | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1350` | The procedure net amount is not valid                                                                                        | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1351` | The procedure speciality code is not valid                                                                                   | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1352` | The beneficiary and care plan do not fit this hospital                                                                       | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1353` | The care plan id is not valid                                                                                                | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1354` | The claim failed a payer rule                                                                                                | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1355` | The payer has no details for the requested implants                                                                          | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1356` | The wallet is short and the patient cannot pay the difference                                                                | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1357` | The admission date is after the discharge date                                                                               | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1358` | The patient was registered too long after admission                                                                          | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1359` | The claim has no billable treatment plan                                                                                     | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1360` | An item code is not valid                                                                                                    | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1361` | An item sequence is not valid                                                                                                | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1362` | A discharge against medical advice needs the LM100 procedure                                                                 | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1363` | No biometric authentication and no consent questionnaire at discharge                                                        | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1364` | A consent questionnaire answer is empty                                                                                      | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1365` | The standard treatment guideline response is missing                                                                         | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1366` | The biometric user token is not valid                                                                                        | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1367` | No biometric record for a cycle date                                                                                         | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1368` | Cycle information is missing for some cycles                                                                                 | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1369` | Two biometric authentications on one date for a cyclic procedure                                                             | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1370` | A supporting detail has an invalid start date                                                                                | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1401` | The policy is not allowed for your hospital                                                                                  | `/v1/insuranceplan/on_request`, `/v1/insuranceplan/request`                                                                                                                                                                |
| `PAYR-1402` | The payer has no policy with the code you requested                                                                          | `/v1/insuranceplan/on_request`, `/v1/insuranceplan/request`                                                                                                                                                                |
| `PAYR-1403` | The renewal does not belong to the requested policy                                                                          | `/v1/insuranceplan/on_request`, `/v1/insuranceplan/request`                                                                                                                                                                |
| `PAYR-1404` | No treatment is configured for the policy under any speciality                                                               | `/v1/insuranceplan/on_request`, `/v1/insuranceplan/request`                                                                                                                                                                |
| `PAYR-1405` | The payer has no enrolled hospital for your HFR id or sender code                                                            | `/v1/insuranceplan/on_request`, `/v1/insuranceplan/request`                                                                                                                                                                |
| `PAYR-1406` | An earlier insurance plan request for the same policy is still running                                                       | `/v1/insuranceplan/on_request`, `/v1/insuranceplan/request`                                                                                                                                                                |
| `PAYR-1501` | The surgery date entry carries the wrong kind of value                                                                       | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1502` | The admission date entry carries the wrong kind of value                                                                     | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1503` | The death date entry carries the wrong kind of value                                                                         | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1504` | The case remarks in your query response are not text                                                                         | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1505` | A questionnaire response is attached under the wrong category or code                                                        | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1506` | The newborn's gender is not valid                                                                                            | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1507` | The newborn's date of birth is not valid                                                                                     | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1508` | The newborn link does not lead to a Patient resource                                                                         | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1509` | The newborn's proof of birth attachment is not valid                                                                         | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                                                                                                   |
| `PAYR-1510` | A parameter code in your request is not valid                                                                                | `/v1/insuranceplan/on_request`, `/v1/insuranceplan/request`, `/v1/task/on_submit`, `/v1/task/submit`                                                                                                                       |
| `PAYR-1511` | A parameter value in your request is not valid                                                                               | `/v1/insuranceplan/on_request`, `/v1/insuranceplan/request`, `/v1/task/on_submit`, `/v1/task/submit`                                                                                                                       |
| `PAYR-1512` | A patient reference does not lead to a Patient resource                                                                      | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1513` | A diagnosis is not sent as a coded concept                                                                                   | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1514` | The discharge information entry does not name a discharge stage                                                              | `/v1/claim/on_submit`, `/v1/claim/submit`                                                                                                                                                                                  |
| `PAYR-1515` | An organisation in your bundle has no name                                                                                   | `/v1/claim/on_submit`, `/v1/claim/submit`, `/v1/coverageeligibility/check`, `/v1/coverageeligibility/on_check`, `/v1/preauth/on_submit`, `/v1/preauth/submit`                                                              |
| `PAYR-1516` | The payer cannot match your error response to any message                                                                    | `/v1/communication/on_request`, `/v1/communication/request`, `/v1/error`                                                                                                                                                   |
| `PAYR-1517` | Your error was sent encrypted instead of as a protocol response                                                              | `/v1/communication/on_request`, `/v1/communication/request`, `/v1/error`                                                                                                                                                   |
| `PAYR-1518` | Your Task resource carries no input parameters                                                                               | `/v1/communication/on_request`, `/v1/insuranceplan/on_request`, `/v1/insuranceplan/request`, `/v1/task/on_submit`, `/v1/task/submit`                                                                                       |
| `PAYR-1519` | A Task input parameter has no type                                                                                           | `/v1/communication/on_request`, `/v1/insuranceplan/on_request`, `/v1/insuranceplan/request`, `/v1/task/on_submit`, `/v1/task/submit`                                                                                       |
| `PAYR-1520` | The communication reference does not lead to a Communication resource                                                        | `/v1/communication/on_request`, `/v1/communication/request`                                                                                                                                                                |

310 codes are recorded. Read a code with its message text beside it: [reading error codes](/docs/nhcx/v1/reference/error-code-guide) has the collisions and what to do about each.


---

# Cancel, reprocess and shortfall

The post-decision exchanges. All are `Task` bundles on `/v1/task/submit`, answered on `/v1/task/on_submit`, and `Task.code` with its reason is the only thing that tells them apart.

## One endpoint, five requests

`/v1/task/submit` has no path per purpose. Build the request from this table, and route an inbound one by the same three columns.

| You want to                | `Task.code` | Reason                                                                     | Workflow on the request | Workflow on the answer                       |
| -------------------------- | ----------- | -------------------------------------------------------------------------- | ----------------------- | -------------------------------------------- |
| Cancel a preauthorisation  | `cancel`    | One of the seven `ndhm-reason-code` values in the [Cancel rule](#cancel-1) | `PC01`                  | `PC02`                                       |
| Reprocess a rejected claim | `reprocess` | `claimrejected`                                                            | `36`                    | `37`, then the verdict on the claim's thread |
| Claim a shortfall          | `reprocess` | `partialpayment`                                                           | `36`                    | `37`, then the verdict on the claim's thread |
| Release an amount          | `release`   | `partialpayment`                                                           | Not published           | Not published                                |
| Nullify a claim            | `nullify`   | Not published                                                              | Not published           | Not published                                |

`suspend` is a listed code with no exchange behind it, so it has no row. A payment acknowledgement does not travel here: it goes on `/v1/paymentnotice/on_request`, as [Payment notice and acknowledgement](/docs/nhcx/v1/reference/fhir/payment-notice-and-acknowledgement) sets out.

## The answer is nested, unlike every other callback

On every other use case the decision is an entry you read straight from the callback bundle. Here the callback's first resource is a `Task`, and the decision sits behind it:

1. Read `Task.output[0].valueReference.reference`, for example `ClaimResponse/cr-reprocess-approved`.
2. Find the `ClaimResponse` entry with that identity in the same bundle.
3. Read the result from that `ClaimResponse`, as the rule [The answer](#the-answer) sets out.

A parser that looks for a `ClaimResponse` as the bundle's leading resource finds nothing on this callback.

## Cancel

Sent on `/v1/task/submit`, workflow PC01.

### The bundle

| # | Resource              | Profile                                                                             |
| - | --------------------- | ----------------------------------------------------------------------------------- |
| 1 | `Task`                | [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)                 |
| 2 | `Organization (prov)` | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html) |
| 3 | `Organization (pay)`  | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html) |

### Elements

#### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                 | Example                                                                                                                             |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `status`                | `requested`                                                                                                                         |
| `intent`                | `order`                                                                                                                             |
| `code.coding[]`         | `cancel` in `http://terminology.hl7.org/CodeSystem/financialtaskcode`                                                               |
| `authoredOn`            | `2026-09-10T23:52:03+05:30`                                                                                                         |
| `requester`             | reference `https://nhcx.abdm.gov.in/provider`                                                                                       |
| `owner`                 | reference `https://nhcx.abdm.gov.in/payer`                                                                                          |
| `description`           | `Treatment plan changed; withdrawn.`                                                                                                |
| `reasonCode.coding[]`   | `treatmentplanchanged` Treatment plan changed during hospitalization in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-reason-code` |
| `input[]`               | valueString `NM-26-0SE00002I`                                                                                                       |
| `input[].type.coding[]` | `claimNumber` ClaimNumber in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-input-type-code`                                   |
|                         | `intimationNumber` Intimation Number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-input-type-code`                        |

#### Organization (prov)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `identifier[]`               | system `https://nhcx.abdm.gov.in`, value `IN1910000151`                                 |
| `identifier[].type.coding[]` | `NPI` National provider identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`   |
| `type[].coding[]`            | `prov` Healthcare Provider in `http://terminology.hl7.org/CodeSystem/organization-type` |
| `name`                       | `XYZ Multispeciality Hospital`                                                          |

#### Organization (pay)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                               |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `identifier[]`               | system `https://nhcx.abdm.gov.in`, value `1000004805`                                                 |
| `identifier[].type.coding[]` | `NIIP` National Insurance Payor Identifier (Payor) in `http://terminology.hl7.org/CodeSystem/v2-0203` |
| `type[].coding[]`            | `pay` Payer in `http://terminology.hl7.org/CodeSystem/organization-type`                              |
| `name`                       | `Sandbox Payer`                                                                                       |

## Reprocess

Sent on `/v1/task/submit`, workflow 36.

### The bundle

| # | Resource              | Profile                                                                             |
| - | --------------------- | ----------------------------------------------------------------------------------- |
| 1 | `Task`                | [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)                 |
| 2 | `Organization (prov)` | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html) |
| 3 | `Organization (pay)`  | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html) |

### Elements

#### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                              | Example                                                                                                                         |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `status`                             | `requested`                                                                                                                     |
| `intent`                             | `order`                                                                                                                         |
| `code.coding[]`                      | `reprocess` in `http://terminology.hl7.org/CodeSystem/financialtaskcode`                                                        |
| `authoredOn`                         | `2026-09-10T23:53:27+05:30`                                                                                                     |
| `requester`                          | reference `https://nhcx.abdm.gov.in/provider`                                                                                   |
| `owner`                              | reference `https://nhcx.abdm.gov.in/payer`                                                                                      |
| `description`                        | `Package rate revised; please reassess the approved amount.`                                                                    |
| `reasonCode.coding[]`                | `claimrejected` Reprocess request due to claim rejected by payer in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-reason-code` |
| `basedOn[]`                          | display `Claim NM-26-0SE00002L`                                                                                                 |
| `basedOn[].identifier`               | system `https://nhcx.abdm.gov.in`, value `NM-26-0SE00002L`                                                                      |
| `basedOn[].identifier.type.coding[]` | `CLN` Claim number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`                                      |
| `input[]`                            | valueString `NM-26-0SE00002L`                                                                                                   |
| `input[].type.coding[]`              | `claimNumber` ClaimNumber in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-input-type-code`                               |
|                                      | `intimationNumber` Intimation Number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-input-type-code`                    |
| `for.identifier`                     | value `MRAV1985001`                                                                                                             |
| `for.identifier.type.coding[]`       | `MB` Member Number in `http://terminology.hl7.org/CodeSystem/v2-0203`                                                           |

#### Organization (prov)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `identifier[]`               | system `https://nhcx.abdm.gov.in`, value `IN1910000151`                                 |
| `identifier[].type.coding[]` | `NPI` National provider identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`   |
| `type[].coding[]`            | `prov` Healthcare Provider in `http://terminology.hl7.org/CodeSystem/organization-type` |
| `name`                       | `XYZ Multispeciality Hospital`                                                          |

#### Organization (pay)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                               |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `identifier[]`               | system `https://nhcx.abdm.gov.in`, value `1000004805`                                                 |
| `identifier[].type.coding[]` | `NIIP` National Insurance Payor Identifier (Payor) in `http://terminology.hl7.org/CodeSystem/v2-0203` |
| `type[].coding[]`            | `pay` Payer in `http://terminology.hl7.org/CodeSystem/organization-type`                              |
| `name`                       | `Sandbox Payer`                                                                                       |

## Release

Sent on `/v1/task/submit`.

### The bundle

| # | Resource              | Profile                                                                             |
| - | --------------------- | ----------------------------------------------------------------------------------- |
| 1 | `Task`                | [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)                 |
| 2 | `Organization (prov)` | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html) |
| 3 | `Organization (pay)`  | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html) |

### Elements

#### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                              | Example                                                                                                                           |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `status`                             | `requested`                                                                                                                       |
| `intent`                             | `order`                                                                                                                           |
| `code.coding[]`                      | `release` in `http://terminology.hl7.org/CodeSystem/financialtaskcode`                                                            |
| `description`                        | `Release the balance amount for claim EO26AA2700001`                                                                              |
| `authoredOn`                         | `2026-03-05T11:20:00+05:30`                                                                                                       |
| `requester`                          | reference `https://nhcx.abdm.gov.in/provider`                                                                                     |
| `owner`                              | reference `https://nhcx.abdm.gov.in/payer`                                                                                        |
| `reasonCode.coding[]`                | `partialpayment` Reprocess request due to partial payment by payer in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-reason-code` |
| `basedOn[]`                          | display `Claim EO26AA2700001`                                                                                                     |
| `basedOn[].identifier`               | system `https://nhcx.abdm.gov.in`, value `EO26AA2700001`                                                                          |
| `basedOn[].identifier.type.coding[]` | `CLN` Claim number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`                                        |
| `input[]`                            | valueString `EO26AA2700001`                                                                                                       |
| `input[].type.coding[]`              | `claimNumber` ClaimNumber in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-input-type-code`                                 |
|                                      | `amount` Amount in `https://nhcx.abdm.gov.in/task-input-type`                                                                     |
| `input[].valueMoney`                 | value `1650`, currency `INR`                                                                                                      |

#### Organization (prov)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `identifier[]`               | system `https://nhcx.abdm.gov.in`, value `IN1910000151`                                 |
| `identifier[].type.coding[]` | `NPI` National provider identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`   |
| `type[].coding[]`            | `prov` Healthcare Provider in `http://terminology.hl7.org/CodeSystem/organization-type` |
| `name`                       | `Facility Name`                                                                         |

#### Organization (pay)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                               |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `identifier[]`               | system `https://nhcx.abdm.gov.in`, value `1518`                                                       |
| `identifier[].type.coding[]` | `NIIP` National Insurance Payor Identifier (Payor) in `http://terminology.hl7.org/CodeSystem/v2-0203` |
| `type[].coding[]`            | `pay` Payer in `http://terminology.hl7.org/CodeSystem/organization-type`                              |
| `name`                       | `Insurance Company`                                                                                   |

## Cancellation done

Sent on `/v1/task/on_submit`, workflow PC02.

### The bundle

| # | Resource              | Profile                                                                                                    |
| - | --------------------- | ---------------------------------------------------------------------------------------------------------- |
| 1 | `Task`                | none declared; NRCeS [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)                   |
| 2 | `ClaimResponse`       | none declared; NRCeS [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html) |
| 3 | `Patient`             | none declared; NRCeS [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)             |
| 4 | `Organization (pay)`  | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)   |
| 5 | `Organization (prov)` | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)   |
| 6 | `Coverage`            | none declared; NRCeS [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)           |

### Elements

#### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                   | Example                                                                                     |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| `status`                  | `completed`                                                                                 |
| `intent`                  | `order`                                                                                     |
| `code.coding[]`           | `approve` Activate/approve the focal resource in `http://hl7.org/fhir/CodeSystem/task-code` |
| `description`             | `Pre-authorisation withdrawn by 1000003463@hcx: Treatment plan changed; withdraw…`          |
| `authoredOn`              | `2026-09-10T23:52:05+05:30`                                                                 |
| `requester`               | reference `<participant-defined>`                                                           |
| `owner`                   | reference `<participant-defined>`                                                           |
| `output[].type.coding[]`  | `include` Include in `http://terminology.hl7.org/CodeSystem/financialtaskinputtype`         |
| `output[].valueReference` | reference `<participant-defined>`                                                           |

#### ClaimResponse

NRCeS profile: [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html).

| Element                            | Example                                                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `identifier[]`                     | system `<participant-defined>`, value `NM-26-0SE00002I`                                                       |
| `identifier[].type.coding[]`       | `CLN` Claim number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`                    |
| `status`                           | `active`                                                                                                      |
| `type.coding[]`                    | `737481003` Inpatient care management (procedure) in `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-claim-type` |
| `use`                              | `preauthorization`                                                                                            |
| `patient`                          | reference `<participant-defined>`                                                                             |
| `created`                          | `2026-09-10T23:52:05+05:30`                                                                                   |
| `insurer`                          | reference `<participant-defined>`                                                                             |
| `requestor`                        | reference `<participant-defined>`                                                                             |
| `outcome`                          | `complete`                                                                                                    |
| `disposition`                      | `Pre-authorisation withdrawn by 1000003463@hcx: Treatment plan changed; withdraw…`                            |
| `payeeType.coding[]`               | `provider` Provider in `http://terminology.hl7.org/CodeSystem/payeetype`                                      |
| `adjudication[].category.coding[]` | `status` Status                                                                                               |
| `adjudication[].reason.coding[]`   | `cancelled` Cancelled                                                                                         |
| `total[].category.coding[]`        | `benefit` Benefit Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`                              |
|                                    | `submitted` Submitted Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`                          |
| `total[].amount`                   | value `150000`                                                                                                |

The `Patient`, `Organization`, `Coverage` entries are shaped as in the chapters that introduce them.

## Reprocess acknowledged

Sent on `/v1/task/on_submit`, workflow 37.

### The bundle

| # | Resource              | Profile                                                                                                    |
| - | --------------------- | ---------------------------------------------------------------------------------------------------------- |
| 1 | `Task`                | none declared; NRCeS [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)                   |
| 2 | `ClaimResponse`       | none declared; NRCeS [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html) |
| 3 | `Patient`             | none declared; NRCeS [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)             |
| 4 | `Organization (pay)`  | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)   |
| 5 | `Organization (prov)` | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)   |
| 6 | `Coverage`            | none declared; NRCeS [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)           |

### Elements

#### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                   | Example                                                                                     |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| `status`                  | `accepted`                                                                                  |
| `intent`                  | `order`                                                                                     |
| `code.coding[]`           | `approve` Activate/approve the focal resource in `http://hl7.org/fhir/CodeSystem/task-code` |
| `description`             | `Claim reopened for reprocessing (round 1) at the request of 1000003463@hcx: Pac…`          |
| `authoredOn`              | `2026-09-10T23:53:28+05:30`                                                                 |
| `requester`               | reference `<participant-defined>`                                                           |
| `owner`                   | reference `<participant-defined>`                                                           |
| `output[].type.coding[]`  | `include` Include in `http://terminology.hl7.org/CodeSystem/financialtaskinputtype`         |
| `output[].valueReference` | reference `<participant-defined>`                                                           |

#### ClaimResponse

NRCeS profile: [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html).

| Element                            | Example                                                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `identifier[]`                     | system `<participant-defined>`, value `NM-26-0SE00002L`                                                       |
| `identifier[].type.coding[]`       | `CLN` Claim number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`                    |
| `status`                           | `active`                                                                                                      |
| `type.coding[]`                    | `737481003` Inpatient care management (procedure) in `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-claim-type` |
| `use`                              | `claim`                                                                                                       |
| `patient`                          | reference `<participant-defined>`                                                                             |
| `created`                          | `2026-09-10T23:53:28+05:30`                                                                                   |
| `insurer`                          | reference `<participant-defined>`                                                                             |
| `requestor`                        | reference `<participant-defined>`                                                                             |
| `outcome`                          | `queued`                                                                                                      |
| `disposition`                      | `Claim reopened for reprocessing (round 1) at the request of 1000003463@hcx: Pac…`                            |
| `payeeType.coding[]`               | `provider` Provider in `http://terminology.hl7.org/CodeSystem/payeetype`                                      |
| `adjudication[].category.coding[]` | `status` Status                                                                                               |
| `adjudication[].reason.coding[]`   | `submitted` Submitted                                                                                         |
| `total[].category.coding[]`        | `benefit` Benefit Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`                              |
|                                    | `submitted` Submitted Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`                          |
| `total[].amount`                   | value `0`                                                                                                     |
|                                    | value `150000`                                                                                                |

The `Patient`, `Organization`, `Coverage` entries are shaped as in the chapters that introduce them.

## Rules

### Cancel

`Task.code` `cancel`, a reason from `ndhm-reason-code` (`treatmentplanchanged`, `patientrequest`, `financialconstraints`, `alternativetreatment`, `duplicateclaim`, `administrativeerror`, `other`), and the inputs `claimNumber` and `intimationNumber`.

### Reprocess

`Task.code` `reprocess`, reason `claimrejected` for a rejected claim or `partialpayment` for one paid short, `basedOn` naming the claim by its `CLN` identifier, `for` the member, and the inputs `claimNumber` and `intimationNumber`, spelled so.

### Release

`Task.code` `release`, reason `partialpayment`, with the claim number and the amount sought as a `valueMoney` input.

### Nullify

The Reprocess sheet of the requests-and-responses workbook gives `Task.code` on `/v1/task/submit` as `reprocess`, `cancel`, `release` or `nullify`, as the use case needs, each with a `ClaimNumber` input carrying the claim number and `Task.status` `requested`; the answer is a `Task` whose output is the `ClaimResponse`. The provider sandbox exit checklist names the same four codes. The value sets describe `nullify` as closing a claim the provider submitted. No sample bundle, reason code or workflow code is published for it.

### Suspend

`suspend` appears only as a code. The value sets list it, glossed "suspend the preauthorization or claim that was submitted by provider", beside the task output `claimsuspended`. No exchange carries it: no request shape, answer or workflow code is published.

### The answer

A `Task` whose `output` of type `include` references a `ClaimResponse` in the same bundle. Read the result from that `ClaimResponse`'s adjudication reason, not from `outcome` and not from `Task.code`. A cancellation is `completed` with reason `cancelled`; a reprocess is `accepted` with the `ClaimResponse` `queued`, and the new verdict follows on the claim's own thread.

### Switch on system and code together

The Task code systems differ between request and response.

### A cancelled case still reports money

Zero the figure yourself once the reason reads `cancelled`.

## PMJAY

The generic bundle above is what every payer takes, IRDAI-regulated insurers and TPAs included. PMJAY takes it with the changes and requirements below.

### What changes in the bundle

#### Cancel

The PMJAY bundle has the same resources, elements and systems as the generic one.

#### Reprocess

##### Elements PMJAY adds

| Element                        | Example                                                                                           |
| ------------------------------ | ------------------------------------------------------------------------------------------------- |
| `Task.input[].valueAttachment` | contentType `application/pdf`, title `Medical Superintendent Declaration Form (During Admission)` |

##### Systems PMJAY binds differently

| Element                             | Generic                                         | PMJAY                                                                |
| ----------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------- |
| `Task.for.identifier.type.coding[]` | `http://terminology.hl7.org/CodeSystem/v2-0203` | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code` |

### What PMJAY specifies

- A shortfall is the reprocess `Task` with reason `partialpayment` and an amount capped at the difference.
- The reprocess carries the supporting document as a `document` input with a `valueAttachment`, and names the member by the `PMJAY` identifier.
- The reprocess is acknowledged on 37; the new verdict then arrives on the claim's own thread.

### What PMJAY requires

- Cancel is allowed until the claim is raised, and refused once payment has been initiated (`PAYR-1257`).
- Reprocess once, the moment the rejection arrives, with a supporting document. The Claim Review Committee is final.
- Shortfall only after payment notice 33 has arrived and been acknowledged on 17, once, and never after a reprocess.
- A `Task` coded `status` is not taken (`PAYR-1018`, `PAYR-1008`). Read where a case stands from the payer service instead.

## Use cases, APIs and data elements

### B8 Reprocess or cancel (provider)

One endpoint, several jobs, told apart by the Task's code and reason: reprocess with claimrejected, shortfall with partialpayment, cancel. A reprocess goes on 36 and is acknowledged on 37; a cancel goes on PC01 and is done on PC02. Both carry the input intimationNumber. A supporting document is mandatory on a reprocess.

|                    |                                                                                                                       |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/task/submit` [`apis/13-other/v1-task-submit.bru`](/docs/nhcx/v1/api/task/endpoints/task-v1-task-submit)          |
| **Callback**       | `/v1/task/on_submit` [`apis/13-other/v1-task-on-submit.bru`](/docs/nhcx/v1/api/task/endpoints/task-v1-task-on-submit) |
| **Workflow**       | PC01 cancel, 36 reprocess or shortfall                                                                                |
| **Carries JWE**    | yes                                                                                                                   |
| **Focal resource** | `Task`                                                                                                                |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `PC01`              |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |

**Workflow codes**

| Code   | Name                                | Authored by | `x-hcx-status`      | Means                                                                        |
| ------ | ----------------------------------- | ----------- | ------------------- | ---------------------------------------------------------------------------- |
| `PC01` | Preauth Cancel Initiated            | provider    | `request.initiated` | Cancel an existing preauth                                                   |
| `36`   | Claim Arbitration Request Submitted | provider    | `request.initiated` | Reprocess/Erroneous request, with input intimationNumber; acknowledged on 37 |

**Data elements**

| Element              | Label                          | Group      | Type           | Card.  | FHIR path                                            | Example           | Notes |
| -------------------- | ------------------------------ | ---------- | -------------- | ------ | ---------------------------------------------------- | ----------------- | ----- |
| `taskCode`           | Action Code                    | Task       | `code`         | `1..1` | `Task.code.coding[0].code`                           | `reprocess`       |       |
| `taskReason`         | Appeal Reason Code             | Task       | `code`         | `1..1` | `Task.reasonCode.coding[0].code`                     | `claimrejected`   |       |
| `originalCaseNumber` | Original Case Number           | Task Input | `string`       | `1..1` | `Task.input[0].valueString`                          | `CL0000000001`    |       |
| `appealDocument`     | Dispute Justification Document | Task Input | `base64Binary` | `1..1` | `Task.input[category=document].valueAttachment.data` | `JVBERi0xLjQK...` |       |

NRCeS profiles: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

### D8 Cancel pre-authorisation (pmjay)

A Task with code cancel, the case number as input and one of seven reasons: treatmentplanchanged, patientrequest, financialconstraints, alternativetreatment, duplicateclaim, administrativeerror, other. Allowed at any point until the claim is raised.

|                       |                                                                                                                       |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **API**               | `/v1/task/submit` [`apis/13-other/v1-task-submit.bru`](/docs/nhcx/v1/api/task/endpoints/task-v1-task-submit)          |
| **Callback**          | `/v1/task/on_submit` [`apis/13-other/v1-task-on-submit.bru`](/docs/nhcx/v1/api/task/endpoints/task-v1-task-on-submit) |
| **Workflow**          | PC01                                                                                                                  |
| **Carries JWE**       | yes                                                                                                                   |
| **Focal resource**    | `Task`                                                                                                                |
| **Simulator console** | `/builder?family=preauth&usecase=cancel`                                                                              |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `PC01`              |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |

**Workflow codes**

| Code   | Name                     | Authored by | `x-hcx-status`      | Means                      |
| ------ | ------------------------ | ----------- | ------------------- | -------------------------- |
| `PC01` | Preauth Cancel Initiated | provider    | `request.initiated` | Cancel an existing preauth |

**Data elements**

| Element      | Label                | Group      | Type     | Card.  | FHIR path                   | Example         | Notes |
| ------------ | -------------------- | ---------- | -------- | ------ | --------------------------- | --------------- | ----- |
| `taskCode`   | Action Code          | Task       | `code`   | `1..1` | `Task.code.coding[0].code`  | `cancel`        |       |
| `caseNumber` | Pre-auth Case Number | Task Input | `string` | `1..1` | `Task.input[0].valueString` | `VB26AA2600001` |       |

NRCeS profiles: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

### D11 Reprocess a rejected claim (pmjay)

An appeal, not a resubmission: a Task with code reprocess and reason claimrejected, a supporting document attached, no amount. Raise it the moment the rejection arrives. Once only; the Claim Review Committee is final.

|                       |                                                                                                                       |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **API**               | `/v1/task/submit` [`apis/13-other/v1-task-submit.bru`](/docs/nhcx/v1/api/task/endpoints/task-v1-task-submit)          |
| **Callback**          | `/v1/task/on_submit` [`apis/13-other/v1-task-on-submit.bru`](/docs/nhcx/v1/api/task/endpoints/task-v1-task-on-submit) |
| **Workflow**          | 36                                                                                                                    |
| **Carries JWE**       | yes                                                                                                                   |
| **Focal resource**    | `Task`                                                                                                                |
| **Simulator console** | `/builder?family=claim&usecase=reprocess`                                                                             |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `36`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |

**Workflow codes**

| Code | Name                                | Authored by | `x-hcx-status`      | Means                                                                        |
| ---- | ----------------------------------- | ----------- | ------------------- | ---------------------------------------------------------------------------- |
| `36` | Claim Arbitration Request Submitted | provider    | `request.initiated` | Reprocess/Erroneous request, with input intimationNumber; acknowledged on 37 |

**Data elements**

| Element       | Label             | Group      | Type     | Card.  | FHIR path                        | Example         | Notes |
| ------------- | ----------------- | ---------- | -------- | ------ | -------------------------------- | --------------- | ----- |
| `taskCode`    | Task Code         | Task       | `code`   | `1..1` | `Task.code.coding[0].code`       | `reprocess`     |       |
| `taskReason`  | Dispute Reason    | Task       | `code`   | `1..1` | `Task.reasonCode.coding[0].code` | `claimrejected` |       |
| `claimNumber` | Rejected Claim ID | Task Input | `string` | `1..1` | `Task.input[0].valueString`      | `CL26AA2600001` |       |

NRCeS profiles: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

### D12 Claim a shortfall (pmjay)

The same Task with reason partialpayment and an amount capped at the difference, allowed only after payment notice 33 has arrived and been acknowledged with 17. Once only, and never after a reprocess.

|                       |                                                                                                                       |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **API**               | `/v1/task/submit` [`apis/13-other/v1-task-submit.bru`](/docs/nhcx/v1/api/task/endpoints/task-v1-task-submit)          |
| **Callback**          | `/v1/task/on_submit` [`apis/13-other/v1-task-on-submit.bru`](/docs/nhcx/v1/api/task/endpoints/task-v1-task-on-submit) |
| **Workflow**          | 36                                                                                                                    |
| **Carries JWE**       | yes                                                                                                                   |
| **Focal resource**    | `Task`                                                                                                                |
| **Simulator console** | `/builder?family=claim&usecase=shortfall`                                                                             |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `36`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |

**Workflow codes**

| Code | Name                                | Authored by | `x-hcx-status`      | Means                                                                        |
| ---- | ----------------------------------- | ----------- | ------------------- | ---------------------------------------------------------------------------- |
| `36` | Claim Arbitration Request Submitted | provider    | `request.initiated` | Reprocess/Erroneous request, with input intimationNumber; acknowledged on 37 |

**Data elements**

| Element       | Label                   | Group      | Type     | Card.  | FHIR path                        | Example          | Notes |
| ------------- | ----------------------- | ---------- | -------- | ------ | -------------------------------- | ---------------- | ----- |
| `taskCode`    | Task Code               | Task       | `code`   | `1..1` | `Task.code.coding[0].code`       | `reprocess`      |       |
| `taskReason`  | Reason Code             | Task       | `code`   | `1..1` | `Task.reasonCode.coding[0].code` | `partialpayment` |       |
| `claimNumber` | Partially Paid Claim ID | Task Input | `string` | `1..1` | `Task.input[0].valueString`      | `CL26AA2600001`  |       |

NRCeS profiles: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

### C10 Respond to a Task (payer)

The answer to a reprocess, shortfall or cancel. A cancellation done is PC02 and carries the case's ClaimResponse in its output; a reprocess on 36 is acknowledged on 37 as arbitration. Both payers answer this way.

|                    |                                                                                                                       |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/task/on_submit` [`apis/13-other/v1-task-on-submit.bru`](/docs/nhcx/v1/api/task/endpoints/task-v1-task-on-submit) |
| **Callback**       | `/v1/task/submit` [`apis/13-other/v1-task-submit.bru`](/docs/nhcx/v1/api/task/endpoints/task-v1-task-submit)          |
| **Workflow**       | 252 approved, 253 rejected, 254 queried, PC02 cancelled, 37 arbitration acknowledged                                  |
| **Carries JWE**    | yes                                                                                                                   |
| **Focal resource** | `Task`                                                                                                                |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1518@hcx`          |
| `x-hcx-recipient_code` | `1000004446@hcx`    |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `252`               |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `response.complete` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |

**Workflow codes**

| Code   | Name                                       | Authored by       | `x-hcx-status`      | Means                      |
| ------ | ------------------------------------------ | ----------------- | ------------------- | -------------------------- |
| `252`  | Reprocess Request Approved                 | payer             | `response.complete` | Reprocess request approved |
| `253`  | Reprocess Request Rejected                 | payer             | `response.complete` | Reprocess request rejected |
| `254`  | Reprocess Request Queried                  | payer             | `request.initiated` | Reprocess request queried  |
| `PC02` | Preauthorization Cancellation Accomplished | status sheet only | `response.complete` |                            |
| `37`   | Claim Arbitration Acknowledgement          | status sheet only | `response.complete` |                            |

**Data elements**

| Element          | Label              | Group       | Type        | Card.  | FHIR path                                 | Example                               | Notes |
| ---------------- | ------------------ | ----------- | ----------- | ------ | ----------------------------------------- | ------------------------------------- | ----- |
| `taskStatus`     | Task Status        | Task        | `code`      | `1..1` | `Task.status`                             | `completed`                           |       |
| `outputDecision` | Decision Reference | Task Output | `reference` | `0..1` | `Task.output[0].valueReference.reference` | `ClaimResponse/cr-reprocess-approved` |       |

NRCeS profiles: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).


---

# Claim query and answer

The payer asking for something before it adjudicates a claim. A private insurer asks through a communication; PMJAY asks in the claim response and takes the whole claim back as the answer.

## The query

Sent on `/v1/communication/request`, workflow 27.

### The bundle

| # | Resource               | Profile                                                                                             |
| - | ---------------------- | --------------------------------------------------------------------------------------------------- |
| 1 | `Task`                 | [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)                                 |
| 2 | `CommunicationRequest` | [CommunicationRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CommunicationRequest.html) |
| 3 | `Claim`                | [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html)                               |
| 4 | `Patient`              | [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)                           |
| 5 | `Organization (ins)`   | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                 |
| 6 | `Organization (prov)`  | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                 |
| 7 | `Practitioner`         | [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html)                 |
| 8 | `Coverage`             | [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)                         |

### Elements

#### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                  | Example                                                                                                        |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `status`                 | `requested`                                                                                                    |
| `intent`                 | `order`                                                                                                        |
| `reasonCode.coding[]`    | `additionalinfo` Additional Information Request in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-reason-code` |
| `code.coding[]`          | `poll` in `http://terminology.hl7.org/CodeSystem/financialtaskcode`                                            |
| `description`            | `Share the final bill breakup and the discharge summary.`                                                      |
| `authoredOn`             | `2026-09-10T23:52:39+05:30`                                                                                    |
| `requester`              | reference `urn:uuid:39cd4b51-bddd-5cc1-a65a-6fa4a2a83cb5`, display `Organization`                              |
| `owner`                  | reference `urn:uuid:84d112ec-041c-57f8-986c-6619ccd8245e`, display `Organization`                              |
| `input[].type.coding[]`  | `include` in `http://terminology.hl7.org/CodeSystem/financialtaskinputtype`                                    |
| `input[].valueReference` | reference `urn:uuid:e6c95fe2-3bd5-5c9f-bf78-47959029cfe2`, display `CommunicationRequest`                      |

#### CommunicationRequest

NRCeS profile: [CommunicationRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CommunicationRequest.html).

| Element                 | Example                                                                                                        |
| ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `identifier[]`          | value `NM-26-0SE00002K`                                                                                        |
| `basedOn[]`             | reference `urn:uuid:5c997608-ee6c-5496-9fdb-f8415e3eb8d5`, display `Claim-claim`                               |
| `status`                | `active`                                                                                                       |
| `category[].coding[]`   | `alert` in `http://terminology.hl7.org/CodeSystem/communication-category`                                      |
| `priority`              | `routine`                                                                                                      |
| `payload[]`             | contentString `Share the final bill breakup and the discharge summary.`                                        |
| `authoredOn`            | `2026-09-10T23:52:39+05:30`                                                                                    |
| `requester`             | reference `urn:uuid:39cd4b51-bddd-5cc1-a65a-6fa4a2a83cb5`, display `Organization`                              |
| `recipient[]`           | reference `urn:uuid:84d112ec-041c-57f8-986c-6619ccd8245e`, display `Organization`                              |
| `sender`                | reference `urn:uuid:39cd4b51-bddd-5cc1-a65a-6fa4a2a83cb5`, display `Organization`                              |
| `reasonCode[]`          | text `Share the final bill breakup and the discharge summary.`                                                 |
| `reasonCode[].coding[]` | `additionalinfo` Additional Information Request in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-reason-code` |

The `Claim`, `Patient`, `Organization`, `Practitioner`, `Coverage` entries are shaped as in the chapters that introduce them.

## The answer

Sent on `/v1/communication/on_request`, workflow 27, echoed.

### The bundle

| # | Resource               | Profile                                                                                             |
| - | ---------------------- | --------------------------------------------------------------------------------------------------- |
| 1 | `Task`                 | [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)                                 |
| 2 | `Communication`        | [Communication](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Communication.html)               |
| 3 | `CommunicationRequest` | [CommunicationRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CommunicationRequest.html) |
| 4 | `Claim`                | [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html)                               |
| 5 | `Patient`              | [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)                           |
| 6 | `Organization (prov)`  | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                 |
| 7 | `Organization (pay)`   | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                 |
| 8 | `Practitioner`         | [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html)                 |
| 9 | `Coverage`             | [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)                         |

### Elements

#### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                  | Example                                                                                                        |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `status`                 | `completed`                                                                                                    |
| `intent`                 | `order`                                                                                                        |
| `code.coding[]`          | `deliver` in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-codes`                                        |
| `authoredOn`             | `2026-09-10T23:52:45+05:30`                                                                                    |
| `requester`              | reference `https://nhcx.abdm.gov.in/provider`, display `Organization`                                          |
| `owner`                  | reference `https://nhcx.abdm.gov.in/payer`, display `Organization`                                             |
| `input[].type.coding[]`  | `include` in `http://terminology.hl7.org/CodeSystem/financialtaskinputtype`                                    |
| `input[].valueReference` | reference `urn:uuid:6840ec3f-7126-4bfc-8a56-c2a2e9576d8d`, display `Communication`                             |
| `reasonCode.coding[]`    | `additionalinfo` Additional Information Request in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-reason-code` |

#### Communication

NRCeS profile: [Communication](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Communication.html).

| Element                       | Example                                                                                                                        |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `identifier[]`                | value `NM-26-0SE00002K`                                                                                                        |
| `basedOn[]`                   | reference `urn:uuid:e6c95fe2-3bd5-5c9f-bf78-47959029cfe2`, display `CommunicationRequest`                                      |
| `inResponseTo[]`              | reference `urn:uuid:e6c95fe2-3bd5-5c9f-bf78-47959029cfe2`, display `CommunicationRequest`                                      |
| `about[]`                     | reference `https://nhcx.abdm.gov.in/claim/request`, display `Claim urn:uuid:5c997608-ee6c-5496-9fdb-f8415e3eb8d5`              |
| `status`                      | `completed`                                                                                                                    |
| `category[].coding[]`         | `notification` in `http://terminology.hl7.org/CodeSystem/communication-category`                                               |
| `priority`                    | `routine`                                                                                                                      |
| `recipient[]`                 | reference `https://nhcx.abdm.gov.in/payer`, display `Organization`                                                             |
| `sender`                      | reference `https://nhcx.abdm.gov.in/provider`, display `Organization`                                                          |
| `payload[]`                   | contentString `Final bill and discharge summary attached.`                                                                     |
| `payload[].contentAttachment` | contentType `application/pdf`, title `Proof of Identity (Aadhaar / Passport / Voter ID)`, creation `2026-09-10T23:52:21+05:30` |
|                               | contentType `application/pdf`, title `Medical Certificate / Doctor Referral`, creation `2026-09-10T23:52:21+05:30`             |
|                               | contentType `application/pdf`, title `Radiology / X-Ray / CT / MRI Scan Reports`, creation `2026-09-10T23:52:21+05:30`         |
|                               | and 6 more                                                                                                                     |
| `payload[].extension[]`       | url `<participant-defined>`, valueString `POI`                                                                                 |
|                               | url `<participant-defined>`, valueString `CER`                                                                                 |
|                               | url `<participant-defined>`, valueString `RAD`                                                                                 |
|                               | and 6 more                                                                                                                     |

The `CommunicationRequest`, `Claim`, `Patient`, `Organization`, `Practitioner`, `Coverage` entries are shaped as in the chapters that introduce them.

## Rules

### The generic query

A `Task` coded `poll`, reason `additionalinfo`, with an `include` input referencing a `CommunicationRequest` whose `basedOn` names the claim. Sent on `/v1/communication/request` under 27.

### The generic answer

A `Task` coded `deliver` in `ndhm-task-codes`, `completed`, with an `include` input referencing a `Communication` whose `basedOn` names the request and whose `payload` carries the message and the documents. Posted on `/v1/communication/on_request`, echoing the correlation id and workflow id.

### Keep attachments on their codes

When rebuilding a bundle to answer a query, key each attachment to its document code as you assemble it, and check the pairing before you send.

## PMJAY

The generic bundle above is what every payer takes, IRDAI-regulated insurers and TPAs included. PMJAY takes it with the changes and requirements below.

### What changes in the bundle

#### The query

PMJAY uses a different bundle for this step, headed by `ClaimResponse` rather than `Task`.

| # | Resource              | Profile                                                                                                    |
| - | --------------------- | ---------------------------------------------------------------------------------------------------------- |
| 1 | `ClaimResponse`       | none declared; NRCeS [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html) |
| 2 | `Patient`             | none declared; NRCeS [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)             |
| 3 | `Organization (pay)`  | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)   |
| 4 | `Organization (prov)` | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)   |
| 5 | `Coverage`            | none declared; NRCeS [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)           |

###### ClaimResponse

NRCeS profile: [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html).

| Element                                   | Example                                                                                      |
| ----------------------------------------- | -------------------------------------------------------------------------------------------- |
| `identifier[]`                            | system `https://hcx.pmjay.gov.in/v1/preauthorization`, value `NM-26-0SF00002T`               |
| `identifier[].type.coding[]`              | `CLN` Claim number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`   |
| `status`                                  | `active`                                                                                     |
| `use`                                     | `claim`                                                                                      |
| `patient`                                 | reference `https://payer.nha.gov.in/claim/v1/claim/on_submit/claimresponse/patient/PMJAY00…` |
| `created`                                 | `2026-09-11T00:04:37+05:30`                                                                  |
| `insurer`                                 | reference `https://payer.nha.gov.in/claim/v1/claim/on_submit/claimresponse/organization/pa…` |
| `requestor`                               | reference `https://payer.nha.gov.in/claim/v1/claim/on_submit/claimresponse/organization/pr…` |
| `outcome`                                 | `partial`                                                                                    |
| `disposition`                             | `query`                                                                                      |
| `payeeType.coding[]`                      | `provider` Provider in `http://terminology.hl7.org/CodeSystem/payeetype`                     |
| `item[]`                                  | id `Item/Item/1`, itemSequence `1`                                                           |
| `item[].adjudication[].category.coding[]` | `submitted` Submitted Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`         |
|                                           | `eligible` Eligible Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`           |
|                                           | `reason` Reason for Adjudication in `https://hl7.org/fhir/R4/valueset-adjudication.html`     |
|                                           | and 3 more                                                                                   |
| `item[].adjudication[].amount`            | value `1800`                                                                                 |
|                                           | value `2070`                                                                                 |
| `item[].adjudication[].reason.coding[]`   | display `: null`                                                                             |
|                                           | `Queried` Queried                                                                            |
| `item[].adjudication[]`                   | value `100`                                                                                  |
|                                           | value `0`                                                                                    |
| `adjudication[].category.coding[]`        | `status` Status                                                                              |
| `adjudication[].reason.coding[]`          | `queried` Queried                                                                            |
| `total[].category.coding[]`               | `benefit` Benefit Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`             |
|                                           | `submitted` Submitted Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`         |
|                                           | `tax` Tax in `https://hl7.org/fhir/R4/valueset-adjudication.html`                            |
|                                           | and 2 more                                                                                   |
| `total[].amount`                          | value `0`                                                                                    |
|                                           | value `1800`                                                                                 |
|                                           | value `2070`                                                                                 |
| `total[]`                                 | id `PMJAY0000X/PMJAY-T`                                                                      |

The `Patient`, `Organization`, `Coverage` entries are shaped as in the chapters that introduce them.

#### The answer

PMJAY uses a different bundle for this step, headed by `Claim` rather than `Task`.

| #  | Resource                | Profile                                                                                                                                      |
| -- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| 1  | `Claim`                 | [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html)                                                                        |
| 2  | `Patient`               | [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)                                                                    |
| 3  | `Organization (prov)`   | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                                                          |
| 4  | `Organization (pay)`    | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                                                          |
| 5  | `Coverage`              | [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)                                                                  |
| 6  | `Practitioner`          | [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html)                                                          |
| 7  | `Procedure`             | [Procedure](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Procedure.html)                                                                |
| 8  | `QuestionnaireResponse` | `QuestionnaireResponse`, which NRCeS does not publish; base FHIR [QuestionnaireResponse](https://hl7.org/fhir/R4/questionnaireresponse.html) |
| 9  | `QuestionnaireResponse` | `QuestionnaireResponse`, which NRCeS does not publish; base FHIR [QuestionnaireResponse](https://hl7.org/fhir/R4/questionnaireresponse.html) |
| 10 | `QuestionnaireResponse` | `QuestionnaireResponse`, which NRCeS does not publish; base FHIR [QuestionnaireResponse](https://hl7.org/fhir/R4/questionnaireresponse.html) |
| 11 | `QuestionnaireResponse` | `QuestionnaireResponse`, which NRCeS does not publish; base FHIR [QuestionnaireResponse](https://hl7.org/fhir/R4/questionnaireresponse.html) |
| 12 | `QuestionnaireResponse` | `QuestionnaireResponse`, which NRCeS does not publish; base FHIR [QuestionnaireResponse](https://hl7.org/fhir/R4/questionnaireresponse.html) |
| 13 | `QuestionnaireResponse` | `QuestionnaireResponse`, which NRCeS does not publish; base FHIR [QuestionnaireResponse](https://hl7.org/fhir/R4/questionnaireresponse.html) |

###### Claim

NRCeS profile: [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html).

| Element                                         | Example                                                                                                                                                                                                                                                                                |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `identifier[]`                                  | system `https://nhcx.abdm.gov.in`, value `NM-26-0SF00002T`                                                                                                                                                                                                                             |
| `identifier[].type.coding[]`                    | `CLN` Claim number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`                                                                                                                                                                                             |
| `status`                                        | `active`                                                                                                                                                                                                                                                                               |
| `type.coding[]`                                 | `737481003` Inpatient care management (procedure) in `http://snomed.info/sct`                                                                                                                                                                                                          |
| `use`                                           | `claim`                                                                                                                                                                                                                                                                                |
| `patient`                                       | reference `https://nhcx.abdm.gov.in/patient`                                                                                                                                                                                                                                           |
| `billablePeriod`                                | start `2026-09-10T00:00:00+05:30`, end `2026-09-10T00:00:00+05:30`                                                                                                                                                                                                                     |
| `created`                                       | `2026-09-11T00:04:45+05:30`                                                                                                                                                                                                                                                            |
| `insurer`                                       | reference `https://nhcx.abdm.gov.in/payer`                                                                                                                                                                                                                                             |
| `provider`                                      | reference `https://nhcx.abdm.gov.in/provider`                                                                                                                                                                                                                                          |
| `priority.coding[]`                             | `normal` Normal in `http://terminology.hl7.org/CodeSystem/processpriority`                                                                                                                                                                                                             |
| `careTeam[]`                                    | sequence `1`                                                                                                                                                                                                                                                                           |
| `careTeam[].provider`                           | reference `https://nhcx.abdm.gov.in/practitioner`                                                                                                                                                                                                                                      |
| `careTeam[].role.coding[]`                      | `primary` Primary provider in `http://terminology.hl7.org/CodeSystem/claimcareteamrole`                                                                                                                                                                                                |
| `careTeam[].qualification.coding[]`             | `394802001` General medicine in `http://snomed.info/sct`                                                                                                                                                                                                                               |
| `supportingInfo[]`                              | id `SupportingInformation/1`, sequence `1`                                                                                                                                                                                                                                             |
|                                                 | id `SupportingInformation/2`, sequence `2`                                                                                                                                                                                                                                             |
|                                                 | id `SupportingInformation/3`, sequence `3`                                                                                                                                                                                                                                             |
|                                                 | and 24 more                                                                                                                                                                                                                                                                            |
| `supportingInfo[].category.coding[]`            | `INV` Document Type - Investigation in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`                                                                                                                                                                         |
|                                                 | `HDS` Hospital discharge summary in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`                                                                                                                                                                            |
|                                                 | `ONS` Period, start or end dates of aspects of the Condition. (e.g. admission, discha… in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`                                                                                                                      |
|                                                 | and 4 more                                                                                                                                                                                                                                                                             |
| `supportingInfo[].code.coding[]`                | `ODN` Death Certificate in `https://nhcx.abdm.gov.in/document-code`                                                                                                                                                                                                                    |
|                                                 | `ODN` Clinical Note/Death Summary in `https://nhcx.abdm.gov.in/document-code`                                                                                                                                                                                                          |
|                                                 | `ODN` Mortality audit report in `https://nhcx.abdm.gov.in/document-code`                                                                                                                                                                                                               |
|                                                 | and 17 more                                                                                                                                                                                                                                                                            |
| `supportingInfo[].valueAttachment`              | contentType `application/pdf`, title `Death Certificate`                                                                                                                                                                                                                               |
|                                                 | contentType `application/pdf`, title `Clinical Note/Death Summary`                                                                                                                                                                                                                     |
|                                                 | contentType `application/pdf`, title `Mortality audit report`                                                                                                                                                                                                                          |
|                                                 | and 10 more                                                                                                                                                                                                                                                                            |
| `supportingInfo[].valueReference`               | reference `https://nhcx.abdm.gov.in/questionnaireresponse/1`, display `Death`                                                                                                                                                                                                          |
|                                                 | reference `https://nhcx.abdm.gov.in/questionnaireresponse/2`, display `Discharge Against Medical Advice (DAMA)`                                                                                                                                                                        |
|                                                 | reference `https://nhcx.abdm.gov.in/questionnaireresponse/3`, display `Discharge Consent`                                                                                                                                                                                              |
|                                                 | and 3 more                                                                                                                                                                                                                                                                             |
| `diagnosis[]`                                   | sequence `1`                                                                                                                                                                                                                                                                           |
| `diagnosis[].diagnosisCodeableConcept.coding[]` | `E11.9` Type 2 diabetes mellitus without complications in `http://hl7.org/fhir/sid/icd-10`                                                                                                                                                                                             |
| `diagnosis[].type[].coding[]`                   | `admitting` Admitting Diagnosis in `http://terminology.hl7.org/CodeSystem/ex-diagnosistype`                                                                                                                                                                                            |
| `diagnosis[].onAdmission.coding[]`              | `yes` Yes in `http://terminology.hl7.org/CodeSystem/ex-diagnosis-on-admission`                                                                                                                                                                                                         |
| `procedure[]`                                   | id `Procedure/1`, sequence `1`, date `2026-09-10T00:00:00+05:30`                                                                                                                                                                                                                       |
| `procedure[].type[].coding[]`                   | `conservative` Conservative in `https://nhcx.abdm.gov.in/procedure-type`                                                                                                                                                                                                               |
| `procedure[].procedureReference`                | reference `https://nhcx.abdm.gov.in/procedure/1`, display `Pleural Effusion (Pleural Effusion)`                                                                                                                                                                                        |
| `insurance[]`                                   | sequence `1`, focal `true`, preAuthRef `2026091110000795`                                                                                                                                                                                                                              |
| `insurance[].coverage`                          | reference `https://nhcx.abdm.gov.in/coverage`                                                                                                                                                                                                                                          |
| `item[]`                                        | id `Item/1`, sequence `1`, factor `1`, careTeamSequence `1`, diagnosisSequence `1`, procedureSequence `1`, informationSequence `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27` |
| `item[].productOrService.coding[]`              | `MG0111A` Pleural Effusion (Pleural Effusion) in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-procedure-code`                                                                                                                                                                        |
| `item[].servicedPeriod`                         | start `2026-09-10`, end `2026-09-10`                                                                                                                                                                                                                                                   |
| `item[].quantity`                               | value `1`                                                                                                                                                                                                                                                                              |
| `item[].unitPrice`                              | value `1800`, currency `INR`                                                                                                                                                                                                                                                           |
| `item[].net`                                    | value `1800`, currency `INR`                                                                                                                                                                                                                                                           |
| `item[].category.coding[]`                      | `MG` General Medicine in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-benefit-category`                                                                                                                                                                                              |
| `item[].modifier[].coding[]`                    | `STRAT006a` Routine Ward                                                                                                                                                                                                                                                               |
| `item[].programCode[].coding[]`                 | `AB-PMJAY` Ayushman Bharat Pradhan Mantri Jan Arogya Yojana (AB-PMJAY) in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-program-code`                                                                                                                                                 |
| `total`                                         | value `1800`, currency `INR`                                                                                                                                                                                                                                                           |

###### QuestionnaireResponse

| Element                           | Example                                                            |
| --------------------------------- | ------------------------------------------------------------------ |
| `questionnaire`                   | `https://payer.gov.in/policy/questionnaire/100025`                 |
| `status`                          | `completed`                                                        |
| `subject`                         | reference `https://nhcx.abdm.gov.in/patient`                       |
| `authored`                        | `2026-09-11T00:04:45+05:30`                                        |
| `item[]`                          | linkId `100011`, text `Death Stage`                                |
|                                   | linkId `100098`, text `Death Date`                                 |
|                                   | linkId `100099`, text `Death Certificate`                          |
|                                   | and 2 more                                                         |
| `item[].answer[]`                 | valueString `Before Surgery/Treatment`                             |
|                                   | valueDateTime `2026-09-10T18:34:00+05:30`                          |
| `item[].answer[].valueAttachment` | contentType `application/pdf`, title `Death Certificate`           |
|                                   | contentType `application/pdf`, title `Clinical Note/Death Summary` |
|                                   | contentType `application/pdf`, title `Mortality audit report`      |

###### QuestionnaireResponse

| Element                           | Example                                                                    |
| --------------------------------- | -------------------------------------------------------------------------- |
| `questionnaire`                   | `https://payer.gov.in/policy/questionnaire/100137`                         |
| `status`                          | `completed`                                                                |
| `subject`                         | reference `https://nhcx.abdm.gov.in/patient`                               |
| `authored`                        | `2026-09-11T00:04:45+05:30`                                                |
| `item[]`                          | linkId `103020`, text `DAMA Stage`                                         |
|                                   | linkId `101403`, text `In Treatment Photo with Doctor/PMAM`                |
|                                   | linkId `100012`, text `Discharge Date`                                     |
|                                   | and 3 more                                                                 |
| `item[].answer[]`                 | valueString `Before Surgery/Treatment`                                     |
|                                   | valueDateTime `2026-09-10T18:34:00+05:30`                                  |
| `item[].answer[].valueAttachment` | contentType `application/pdf`, title `In Treatment Photo with Doctor/PMAM` |
|                                   | contentType `application/pdf`, title `Upload Mangalkamana Patra`           |
|                                   | contentType `application/pdf`, title `Feedback Form`                       |

###### QuestionnaireResponse

| Element                           | Example                                                                                           |
| --------------------------------- | ------------------------------------------------------------------------------------------------- |
| `questionnaire`                   | `https://payer.gov.in/policy/questionnaire/100466`                                                |
| `status`                          | `completed`                                                                                       |
| `subject`                         | reference `https://nhcx.abdm.gov.in/patient`                                                      |
| `authored`                        | `2026-09-11T00:04:45+05:30`                                                                       |
| `item[]`                          | linkId `135477`, text `Medical Superintendent Declaration Form (During Discharge)`                |
| `item[].answer[].valueAttachment` | contentType `application/pdf`, title `Medical Superintendent Declaration Form (During Discharge)` |

###### QuestionnaireResponse

| Element                           | Example                                                                      |
| --------------------------------- | ---------------------------------------------------------------------------- |
| `questionnaire`                   | `https://payer.gov.in/policy/questionnaire/100005`                           |
| `status`                          | `completed`                                                                  |
| `subject`                         | reference `https://nhcx.abdm.gov.in/patient`                                 |
| `authored`                        | `2026-09-11T00:04:45+05:30`                                                  |
| `item[]`                          | linkId `100097`, text `Post Treatment Photo with Doctor/PMAM`                |
|                                   | linkId `100096`, text `Discharge Summary`                                    |
|                                   | linkId `101799`, text `Discharge Stage`                                      |
|                                   | and 4 more                                                                   |
| `item[].answer[].valueAttachment` | contentType `application/pdf`, title `Post Treatment Photo with Doctor/PMAM` |
|                                   | contentType `application/pdf`, title `Discharge Summary`                     |
|                                   | contentType `application/pdf`, title `Feedback Form`                         |
| `item[].answer[]`                 | valueString `After Surgery/Treatment`                                        |
|                                   | valueDateTime `2026-09-10T18:34:00+05:30`                                    |
|                                   | valueString `Yes`                                                            |

###### QuestionnaireResponse

| Element                           | Example                                                     |
| --------------------------------- | ----------------------------------------------------------- |
| `questionnaire`                   | `https://payer.gov.in/policy/questionnaire/100022`          |
| `status`                          | `completed`                                                 |
| `subject`                         | reference `https://nhcx.abdm.gov.in/patient`                |
| `authored`                        | `2026-09-11T00:04:45+05:30`                                 |
| `item[]`                          | linkId `100088`, text `Hospital Bill`                       |
|                                   | linkId `15201`, text `Justification Letter`                 |
|                                   | linkId `103013`, text `Bill Date`                           |
|                                   | and 4 more                                                  |
| `item[].answer[].valueAttachment` | contentType `application/pdf`, title `Hospital Bill`        |
|                                   | contentType `application/pdf`, title `Justification Letter` |
|                                   | contentType `application/pdf`, title `Any other document`   |
| `item[].answer[]`                 | valueDateTime `2026-09-10T18:34:00+05:30`                   |
|                                   | valueString `Recorded.`                                     |

###### QuestionnaireResponse

| Element                           | Example                                                                    |
| --------------------------------- | -------------------------------------------------------------------------- |
| `questionnaire`                   | `https://payer.gov.in/policy/questionnaire/100136`                         |
| `status`                          | `completed`                                                                |
| `subject`                         | reference `https://nhcx.abdm.gov.in/patient`                               |
| `authored`                        | `2026-09-11T00:04:45+05:30`                                                |
| `item[]`                          | linkId `100115`, text `LAMA Stage`                                         |
|                                   | linkId `101403`, text `In Treatment Photo with Doctor/PMAM`                |
|                                   | linkId `100101`, text `Surgery/Treatment Date`                             |
|                                   | and 2 more                                                                 |
| `item[].answer[]`                 | valueString `Before Surgery/Treatment`                                     |
|                                   | valueDateTime `2026-09-10T18:34:00+05:30`                                  |
|                                   | valueString `Yes`                                                          |
| `item[].answer[].valueAttachment` | contentType `application/pdf`, title `In Treatment Photo with Doctor/PMAM` |

The `Patient`, `Organization`, `Coverage`, `Practitioner`, `Procedure` entries are shaped as in the chapters that introduce them.

### What PMJAY specifies

- The query is a `ClaimResponse` with `outcome` `partial` and reason `queried` on 27, the question as free text in the item adjudication.
- The answer is a fresh submit of the whole claim, on the same claim number, under 161.

### What PMJAY requires

- Answer on 161. A claim query answered on 151, 19 or 16 is refused with `PAYR-1321`.
- The full bundle, rebuilt from your stored submission, never a delta.

## Use cases, APIs and data elements

### D10 Answer a claim query (pmjay)

As D7, on the claim endpoint: the query is a ClaimResponse on 27, the answer a fresh submit on 161. The sandbox refuses 151, 19 and 16 with PAYR-1321. The final adjudication then arrives with outcome complete and, often, a deductible adjudication naming why the eligible amount is less than the claimed one.

|                       |                                                                                                                            |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **API**               | `/v1/claim/submit` [`apis/05-claim/v1-claim-submit.bru`](/docs/nhcx/v1/api/claim/endpoints/claim-v1-claim-submit)          |
| **Callback**          | `/v1/claim/on_submit` [`apis/05-claim/v1-claim-on-submit.bru`](/docs/nhcx/v1/api/claim/endpoints/claim-v1-claim-on-submit) |
| **Workflow**          | 161                                                                                                                        |
| **Carries JWE**       | yes                                                                                                                        |
| **Focal resource**    | `Claim`                                                                                                                    |
| **Simulator console** | `/builder?family=claim&usecase=query-answer`                                                                               |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `161`               |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |
| `x-hcx-use_case`       | `New`               |

**Workflow codes**

| Code  | Name                     | Authored by       | `x-hcx-status`      | Means |
| ----- | ------------------------ | ----------------- | ------------------- | ----- |
| `161` | Claim Doc Query Response | status sheet only | `response.complete` |       |

**Data elements**

| Element       | Label         | Group  | Type     | Card.  | FHIR path                   | Example         | Notes |
| ------------- | ------------- | ------ | -------- | ------ | --------------------------- | --------------- | ----- |
| `claimNumber` | Claim Number  | Case   | `string` | `1..1` | `Claim.identifier[0].value` | `CL26AA2600001` |       |
| `workflowId`  | Workflow Code | Header | `string` | `1..1` | `Header.x-hcx-workflow_id`  | `161`           |       |

NRCeS profiles: [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html).


---

# Claim request

The request for payment once treatment is done. The same `Claim` as the preauthorisation with `use` set to `claim`, carrying the finalised dates, bill and documents.

Sent on `/v1/claim/submit`, answered on `/v1/claim/on_submit`, workflow 15.

## The bundle

| # | Resource              | Profile                                                                             |
| - | --------------------- | ----------------------------------------------------------------------------------- |
| 1 | `Claim`               | [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html)               |
| 2 | `Patient`             | [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)           |
| 3 | `Organization (prov)` | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html) |
| 4 | `Organization (pay)`  | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html) |
| 5 | `Coverage`            | [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)         |
| 6 | `Practitioner`        | [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html) |
| 7 | `Procedure`           | [Procedure](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Procedure.html)       |

## Elements

### Claim

NRCeS profile: [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html).

| Element                                         | Example                                                                                                                                                                          |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `identifier[]`                                  | system `https://nhcx.abdm.gov.in`, value `NM-26-0SE00002L`                                                                                                                       |
| `identifier[].type.coding[]`                    | `CLN` Claim number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`                                                                                       |
| `status`                                        | `active`                                                                                                                                                                         |
| `type.coding[]`                                 | `737481003` Inpatient care management (procedure) in `http://snomed.info/sct`                                                                                                    |
| `use`                                           | `claim`                                                                                                                                                                          |
| `patient`                                       | reference `https://nhcx.abdm.gov.in/patient`                                                                                                                                     |
| `billablePeriod`                                | start `2026-09-10T00:00:00+05:30`, end `2026-09-10T00:00:00+05:30`                                                                                                               |
| `created`                                       | `2026-09-10T23:53:21+05:30`                                                                                                                                                      |
| `insurer`                                       | reference `https://nhcx.abdm.gov.in/payer`                                                                                                                                       |
| `provider`                                      | reference `https://nhcx.abdm.gov.in/provider`                                                                                                                                    |
| `priority.coding[]`                             | `normal` Normal in `http://terminology.hl7.org/CodeSystem/processpriority`                                                                                                       |
| `careTeam[]`                                    | sequence `1`                                                                                                                                                                     |
| `careTeam[].provider`                           | reference `https://nhcx.abdm.gov.in/practitioner`                                                                                                                                |
| `careTeam[].role.coding[]`                      | `primary` Primary provider in `http://terminology.hl7.org/CodeSystem/claimcareteamrole`                                                                                          |
| `careTeam[].qualification.coding[]`             | `394802001` General medicine in `http://snomed.info/sct`                                                                                                                         |
| `supportingInfo[]`                              | id `SupportingInformation/1`, sequence `1`                                                                                                                                       |
|                                                 | id `SupportingInformation/2`, sequence `2`                                                                                                                                       |
|                                                 | id `SupportingInformation/3`, sequence `3`                                                                                                                                       |
|                                                 | and 7 more                                                                                                                                                                       |
| `supportingInfo[].category.coding[]`            | `INV` Document Type - Investigation in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`                                                                   |
|                                                 | `HDS` Hospital discharge summary in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`                                                                      |
|                                                 | `ONS` Period, start or end dates of aspects of the Condition. (e.g. admission, discha… in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`                |
|                                                 | and 2 more                                                                                                                                                                       |
| `supportingInfo[].code.coding[]`                | `MB` Medical & Pharmacy Bills Itemized in `https://nhcx.abdm.gov.in/document-code`                                                                                               |
|                                                 | `IMP` Medical Implant Invoice & Barcode Sticker in `https://nhcx.abdm.gov.in/document-code`                                                                                      |
|                                                 | `FCF` Filled NHCX Claim Form (Signed) in `https://nhcx.abdm.gov.in/document-code`                                                                                                |
|                                                 | and 7 more                                                                                                                                                                       |
| `supportingInfo[].valueAttachment`              | contentType `application/pdf`, title `Medical & Pharmacy Bills Itemized`                                                                                                         |
|                                                 | contentType `application/pdf`, title `Medical Implant Invoice & Barcode Sticker`                                                                                                 |
|                                                 | contentType `application/pdf`, title `Filled NHCX Claim Form (Signed)`                                                                                                           |
|                                                 | and 2 more                                                                                                                                                                       |
| `diagnosis[]`                                   | sequence `1`                                                                                                                                                                     |
| `diagnosis[].diagnosisCodeableConcept.coding[]` | `E11.9` Type 2 diabetes mellitus without complications in `http://hl7.org/fhir/sid/icd-10`                                                                                       |
| `diagnosis[].type[].coding[]`                   | `admitting` Admitting Diagnosis in `http://terminology.hl7.org/CodeSystem/ex-diagnosistype`                                                                                      |
| `diagnosis[].onAdmission.coding[]`              | `yes` Yes in `http://terminology.hl7.org/CodeSystem/ex-diagnosis-on-admission`                                                                                                   |
| `procedure[]`                                   | id `Procedure/1`, sequence `1`, date `2026-09-10T00:00:00+05:30`                                                                                                                 |
| `procedure[].type[].coding[]`                   | `surgical` Surgical in `https://nhcx.abdm.gov.in/procedure-type`                                                                                                                 |
| `procedure[].procedureReference`                | reference `https://nhcx.abdm.gov.in/procedure/1`, display `Total Knee Replacement (Unilateral)`                                                                                  |
| `insurance[]`                                   | sequence `1`, focal `true`, preAuthRef `CL/26/0SE000107`                                                                                                                         |
| `insurance[].coverage`                          | reference `https://nhcx.abdm.gov.in/coverage`                                                                                                                                    |
| `item[]`                                        | id `Item/1`, sequence `1`, factor `1`, careTeamSequence `1`, diagnosisSequence `1`, procedureSequence `1`, informationSequence `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10` |
| `item[].productOrService.coding[]`              | `PROC-KNEE-01` Total Knee Replacement (Unilateral) in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-procedure-code`                                                             |
| `item[].servicedPeriod`                         | start `2026-09-10`, end `2026-09-10`                                                                                                                                             |
| `item[].quantity`                               | value `1`                                                                                                                                                                        |
| `item[].unitPrice`                              | value `150000`, currency `INR`                                                                                                                                                   |
| `item[].net`                                    | value `150000`, currency `INR`                                                                                                                                                   |
| `item[].category.coding[]`                      | `Surgical` Surgical in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-benefit-category`                                                                                          |
| `total`                                         | value `150000`, currency `INR`                                                                                                                                                   |

### Patient

NRCeS profile: [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html).

| Element                      | Example                                                                                                                      |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `identifier[]`               | value `MRAV1985001`                                                                                                          |
|                              | value `91-1234-1234-1234`                                                                                                    |
| `identifier[].type.coding[]` | `PMJAY` Pradhan Mantri Jan Aarogya Yojana (PMJAY) ID in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code` |
|                              | `ABHA` Ayushman Bharat Health Account (ABHA) ID in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`      |
|                              | `MB` Member Number in `http://terminology.hl7.org/CodeSystem/v2-0203`                                                        |
| `name[]`                     | text `<patient name>`                                                                                                        |
| `telecom[]`                  | system `phone`, value `9876543210`                                                                                           |
| `gender`                     | `male`                                                                                                                       |
| `birthDate`                  | `1985-06-15`                                                                                                                 |

### Organization (prov)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `identifier[]`               | system `https://nhcx.abdm.gov.in`, value `IN1910000151`                                 |
| `identifier[].type.coding[]` | `NPI` National provider identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`   |
| `type[].coding[]`            | `prov` Healthcare Provider in `http://terminology.hl7.org/CodeSystem/organization-type` |
| `name`                       | `XYZ Multispeciality Hospital`                                                          |

### Organization (pay)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                               |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `identifier[]`               | system `https://nhcx.abdm.gov.in`, value `1000004805`                                                 |
| `identifier[].type.coding[]` | `NIIP` National Insurance Payor Identifier (Payor) in `http://terminology.hl7.org/CodeSystem/v2-0203` |
| `type[].coding[]`            | `pay` Payer in `http://terminology.hl7.org/CodeSystem/organization-type`                              |
| `name`                       | `Sandbox Payer`                                                                                       |

### Coverage

NRCeS profile: [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html).

| Element                      | Example                                                                                  |
| ---------------------------- | ---------------------------------------------------------------------------------------- |
| `identifier[]`               | value `POL7UMU001`                                                                       |
| `identifier[].type.coding[]` | `NH` National Health Plan Identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`  |
| `status`                     | `active`                                                                                 |
| `type.coding[]`              | `HIP` health insurance plan policy in `http://terminology.hl7.org/CodeSystem/v3-ActCode` |
| `subscriber`                 | reference `https://nhcx.abdm.gov.in/patient`                                             |
| `subscriberId`               | `MRAV1985001`                                                                            |
| `beneficiary`                | reference `https://nhcx.abdm.gov.in/patient`                                             |
| `relationship.coding[]`      | `self` in `http://terminology.hl7.org/CodeSystem/subscriber-relationship`                |
| `payor[]`                    | reference `https://nhcx.abdm.gov.in/payer`                                               |

### Practitioner

NRCeS profile: [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html).

| Element                         | Example                                                                                                              |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `identifier[]`                  | system `https://nhcx.abdm.gov.in`, value `71-8422-5818-7201`                                                         |
|                                 | system `https://hpr.abdm.gov.in`, value `71-8422-5818-7201`                                                          |
| `identifier[].type.coding[]`    | `HPID` Healthcare Professional ID (HPID) in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`     |
|                                 | `HPIN` Health Practitioner ID issued by NDHM in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code` |
| `name[]`                        | text `Dr. Ananya Rao`                                                                                                |
| `qualification[].code.coding[]` | `MD` Doctor of Medicine in `http://terminology.hl7.org/CodeSystem/v2-0360`                                           |

### Procedure

NRCeS profile: [Procedure](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Procedure.html).

| Element             | Example                                                      |
| ------------------- | ------------------------------------------------------------ |
| `status`            | `completed`                                                  |
| `code`              | text `Total Knee Replacement (Unilateral)`                   |
| `code.coding[]`     | `71388002` Procedure (procedure) in `http://snomed.info/sct` |
| `subject`           | reference `https://nhcx.abdm.gov.in/patient`                 |
| `performedDateTime` | `2026-09-10T00:00:00+05:30`                                  |

## Rules

### What a claim adds

The final bill under `MB` and the discharge summary under `HDS`, with the implant invoice, the operation notes and the signed claim form where the plan asks for them.

### The stay

`billablePeriod` carries the admission and the discharge.

### Sequences may have gaps

Map supporting information by `sequence` and resolve `item.informationSequence` through the map.

### The amount

May not exceed what the preauthorisation approved.

### Cyclic treatment

One supporting-info entry per cycle, with `timingPeriod`, listed in the item's `informationSequence`, its record referenced from `valueReference`.

### Newborn

The parent stays the primary `Patient`; the child is a second `Patient` linked with `link.type` `refer`, with gender and birth date, and a proof of birth under category `DOB`, code `BCF` or `DCB`.

## PMJAY

The generic bundle above is what every payer takes, IRDAI-regulated insurers and TPAs included. PMJAY takes it with the changes and requirements below.

### What changes in the bundle

#### Resources

- PMJAY adds 4 `QuestionnaireResponse`.

##### QuestionnaireResponse

| Element                           | Example                                                            |
| --------------------------------- | ------------------------------------------------------------------ |
| `questionnaire`                   | `https://payer.gov.in/policy/questionnaire/100025`                 |
| `status`                          | `completed`                                                        |
| `subject`                         | reference `https://nhcx.abdm.gov.in/patient`                       |
| `authored`                        | `2026-09-11T00:25:00+05:30`                                        |
| `item[]`                          | linkId `100011`, text `Death Stage`                                |
|                                   | linkId `100098`, text `Death Date`                                 |
|                                   | linkId `100099`, text `Death Certificate`                          |
|                                   | and 2 more                                                         |
| `item[].answer[]`                 | valueString `Before Surgery/Treatment`                             |
|                                   | valueDateTime `2026-09-10T18:54:00+05:30`                          |
| `item[].answer[].valueAttachment` | contentType `application/pdf`, title `Death Certificate`           |
|                                   | contentType `application/pdf`, title `Clinical Note/Death Summary` |
|                                   | contentType `application/pdf`, title `Mortality audit report`      |

#### Elements PMJAY adds

| Element                                 | Example                                                                                                                                |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `Claim.supportingInfo[].valueReference` | reference `https://nhcx.abdm.gov.in/questionnaireresponse/1`, display `Death`                                                          |
|                                         | reference `https://nhcx.abdm.gov.in/questionnaireresponse/2`, display `Discharge Consent`                                              |
|                                         | reference `https://nhcx.abdm.gov.in/questionnaireresponse/3`, display `Discharge Information`                                          |
|                                         | and 1 more                                                                                                                             |
| `Claim.item[].modifier[].coding[]`      | `STRAT006a` Routine Ward                                                                                                               |
| `Claim.item[].programCode[].coding[]`   | `AB-PMJAY` Ayushman Bharat Pradhan Mantri Jan Arogya Yojana (AB-PMJAY) in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-program-code` |

### What PMJAY specifies

- Dates ride as supporting information: the stay under category `ONS`, code `ADDD`, the encounter under `OTH`, code `EDT`, and the surgery under code `PSP`, each as a `valueString` in `+05:30`.
- Discharge types `DTH`, `DTM`, `LAMA` and `DAMA` under category `DIS`, with the stage, before, during or after surgery, as the `valueString`.
- LAMA or DAMA before or during surgery voids the approved packages: one item `LM100`, quantity the days admitted, capped by the package's `LengthOfStay`. After surgery the package stays billable.
- A death records its date under category `ONS`, code `DTM`.
- The discharge consent and the other policy questionnaires ride as `QuestionnaireResponse` resources, each referenced from a `supportingInfo` entry.

### What PMJAY requires

- Send the claim under the preauthorisation's own number. Refused with `ERR-PYR-CLM-007` otherwise.
- The discharge status under `DIS` and the admission and discharge dates. The claim is refused without them.
- Bill the package alone, at the whole amount. Room rent, consultations and investigations are not items.
- A fresh biometric token at discharge, or the plan's Discharge Consent questionnaire answered. Refused with `PAYR-1363` otherwise.
- `LM100` as the single procedure on LAMA or DAMA before or during surgery (`PAYR-1362`), and the death date under `ONS` / `DTM` (`PAYR-1096`).
- Each cycle's `timingPeriod` matches the biometric capture for that cycle.

## Use cases, APIs and data elements

### B5 Submit claim (provider)

Reimbursement after discharge. The amount may not exceed what the pre-authorisation approved. The acknowledgement on 25 brings the payer's case number. PMJAY takes a claim query answer on 161 only; 151, 19 and 16 are refused with PAYR-1321.

|                    |                                                                                                                            |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/claim/submit` [`apis/05-claim/v1-claim-submit.bru`](/docs/nhcx/v1/api/claim/endpoints/claim-v1-claim-submit)          |
| **Callback**       | `/v1/claim/on_submit` [`apis/05-claim/v1-claim-on-submit.bru`](/docs/nhcx/v1/api/claim/endpoints/claim-v1-claim-on-submit) |
| **Workflow**       | 15 claim, 161 query answer under PMJAY, 14 provisional discharge where a payer supports one                                |
| **Carries JWE**    | yes                                                                                                                        |
| **Focal resource** | `Claim`                                                                                                                    |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `15`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |
| `x-hcx-use_case`       | `New`               |

**Workflow codes**

| Code  | Name                           | Authored by       | `x-hcx-status`      | Means                                                                                                                       |
| ----- | ------------------------------ | ----------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `15`  | Claim Request Initiated        | provider          | `request.initiated` | Final claim submission                                                                                                      |
| `161` | Claim Doc Query Response       | status sheet only | `response.complete` |                                                                                                                             |
| `14`  | Discharge Submitted            | provider          | `request.initiated` | Discharge summary submitted                                                                                                 |
| `151` | Claim Query Response Submitted | provider          | `response.complete` | Response to claim query, as published; the PMJAY sandbox refuses it with PAYR-1321 and takes 161 (Claim Doc Query Response) |

**Data elements**

| Element                | Label                          | Group        | Type       | Card.  | FHIR path                                                                       | Example                             | Notes                                                          |
| ---------------------- | ------------------------------ | ------------ | ---------- | ------ | ------------------------------------------------------------------------------- | ----------------------------------- | -------------------------------------------------------------- |
| `claimNumber`          | Final Claim Number             | Case         | `string`   | `1..1` | `Claim.identifier[0].value`                                                     | `CL0000000001`                      | also at `Bundle.id`                                            |
| `use`                  | Claim Use                      | Case         | `code`     | `1..1` | `Claim.use`                                                                     | `claim`                             |                                                                |
| `preAuthRef`           | Approved Pre-auth Reference    | Case         | `string`   | `1..1` | `Claim.insurance[0].preAuthRef[0]`                                              | `APPR-2026-HP-00891`                |                                                                |
| `patientName`          | Patient Full Name              | Beneficiary  | `string`   | `1..1` | `Patient.name[0].text`                                                          | `Ramesh Chandra Sharma`             |                                                                |
| `memberId`             | Scheme / Insurer Member ID     | Beneficiary  | `string`   | `1..1` | `Patient.identifier[type=PMJAY].value`                                          | `PMJAY-HP-2024-998811`              | also at `Coverage.subscriberId`                                |
| `abhaNumber`           | ABHA Number                    | Beneficiary  | `string`   | `0..1` | `Patient.identifier[type=ABHA].value`                                           | `91234567890123`                    |                                                                |
| `gender`               | Gender                         | Beneficiary  | `code`     | `1..1` | `Patient.gender`                                                                | `male`                              | code system `http://hl7.org/fhir/administrative-gender`        |
| `birthDate`            | Date of Birth                  | Beneficiary  | `date`     | `1..1` | `Patient.birthDate`                                                             | `1982-06-15`                        |                                                                |
| `patientPhone`         | Mobile Phone                   | Beneficiary  | `string`   | `0..1` | `Patient.telecom[system=phone].value`                                           | `9876543210`                        |                                                                |
| `policyNumber`         | Policy Number                  | Coverage     | `string`   | `1..1` | `Coverage.identifier[0].value`                                                  | `PMJAY/HP/S/G`                      |                                                                |
| `facilityId`           | Hospital Facility ID (HFR/NPI) | Provider     | `string`   | `1..1` | `Organization[type=prov].identifier[system=https://facility.abdm.gov.in].value` | `IN1910000151`                      |                                                                |
| `providerName`         | Hospital Name                  | Provider     | `string`   | `1..1` | `Organization[type=prov].name`                                                  | `Apex Multispeciality Hospital`     |                                                                |
| `payerId`              | Payer Identifier (NIIP)        | Payer        | `string`   | `1..1` | `Organization[type=pay].identifier[system=https://irdai.gov.in].value`          | `1000003538`                        |                                                                |
| `payerName`            | Payer Name                     | Payer        | `string`   | `1..1` | `Organization[type=pay].name`                                                   | `National Health Authority - PMJAY` |                                                                |
| `practitionerId`       | Practitioner ID (HPID/HPIN)    | Practitioner | `string`   | `1..1` | `Practitioner.identifier[system=https://hpr.abdm.gov.in].value`                 | `21-8899-4455-6677`                 |                                                                |
| `practitionerName`     | Doctor Name                    | Practitioner | `string`   | `1..1` | `Practitioner.name[0].text`                                                     | `Dr. Arvind Kumar`                  |                                                                |
| `admissionDate`        | Admission Date                 | Stay         | `dateTime` | `1..1` | `Claim.billablePeriod.start`                                                    | `2026-02-26T10:00:00+05:30`         |                                                                |
| `dischargeDate`        | Discharge Date                 | Stay         | `dateTime` | `1..1` | `Claim.billablePeriod.end`                                                      | `2026-03-02T14:30:00+05:30`         |                                                                |
| `careSetting`          | Care Setting                   | Stay         | `code`     | `1..1` | `Claim.type.coding[0].code`                                                     | `institutional`                     | code system `http://terminology.hl7.org/CodeSystem/claim-type` |
| `primaryDiagnosisCode` | Primary Diagnosis (ICD-10)     | Clinical     | `string`   | `1..1` | `Claim.diagnosis[0].diagnosisCodeableConcept.coding[0].code`                    | `A97.0`                             | code system `http://hl7.org/fhir/sid/icd-10`                   |
| `procedureCode`        | Package / Procedure Code       | Clinical     | `string`   | `1..1` | `Claim.procedure[0].procedureCodeableConcept.coding[0].code`                    | `MG004A`                            |                                                                |
| `finalBilledAmount`    | Total Claim Amount             | Billing      | `decimal`  | `1..1` | `Claim.total.value`                                                             | `15500.00`                          |                                                                |

NRCeS profiles: [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html), [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html), [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html), [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html), [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html).

### D9 Submit claim (pmjay)

There is no discharge submission: the claim asserts the discharge and carries its details. Four dates, the discharge type under category DIS with the stage as its value, a fresh biometric token, and LM100 as the single procedure in place of the approved items on a LAMA or DAMA discharge before or during surgery. The amount may not exceed what was approved.

|                       |                                                                                                                            |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **API**               | `/v1/claim/submit` [`apis/05-claim/v1-claim-submit.bru`](/docs/nhcx/v1/api/claim/endpoints/claim-v1-claim-submit)          |
| **Callback**          | `/v1/claim/on_submit` [`apis/05-claim/v1-claim-on-submit.bru`](/docs/nhcx/v1/api/claim/endpoints/claim-v1-claim-on-submit) |
| **Workflow**          | 15                                                                                                                         |
| **Carries JWE**       | yes                                                                                                                        |
| **Focal resource**    | `Claim`                                                                                                                    |
| **Simulator console** | `/builder?family=claim&usecase=submit`                                                                                     |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `15`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |
| `x-hcx-use_case`       | `New`               |

**Workflow codes**

| Code | Name                    | Authored by | `x-hcx-status`      | Means                  |
| ---- | ----------------------- | ----------- | ------------------- | ---------------------- |
| `15` | Claim Request Initiated | provider    | `request.initiated` | Final claim submission |

**Data elements**

| Element            | Label                            | Group        | Type           | Card.  | FHIR path                                                                       | Example                             | Notes                                                   |
| ------------------ | -------------------------------- | ------------ | -------------- | ------ | ------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------- |
| `claimNumber`      | PMJAY Claim Number               | Case         | `string`       | `1..1` | `Claim.identifier[0].value`                                                     | `CL26AA2600001`                     |                                                         |
| `dischargeSummary` | Hospital Discharge Summary (HDS) | Documents    | `base64Binary` | `1..1` | `Claim.supportingInfo[category=HDS].valueAttachment.data`                       | `JVBERi0xLjQK...`                   |                                                         |
| `patientName`      | Patient Full Name                | Beneficiary  | `string`       | `1..1` | `Patient.name[0].text`                                                          | `Ramesh Chandra Sharma`             |                                                         |
| `memberId`         | Scheme / Insurer Member ID       | Beneficiary  | `string`       | `1..1` | `Patient.identifier[type=PMJAY].value`                                          | `PMJAY-HP-2024-998811`              | also at `Coverage.subscriberId`                         |
| `abhaNumber`       | ABHA Number                      | Beneficiary  | `string`       | `0..1` | `Patient.identifier[type=ABHA].value`                                           | `91234567890123`                    |                                                         |
| `gender`           | Gender                           | Beneficiary  | `code`         | `1..1` | `Patient.gender`                                                                | `male`                              | code system `http://hl7.org/fhir/administrative-gender` |
| `birthDate`        | Date of Birth                    | Beneficiary  | `date`         | `1..1` | `Patient.birthDate`                                                             | `1982-06-15`                        |                                                         |
| `patientPhone`     | Mobile Phone                     | Beneficiary  | `string`       | `0..1` | `Patient.telecom[system=phone].value`                                           | `9876543210`                        |                                                         |
| `facilityId`       | Hospital Facility ID (HFR/NPI)   | Provider     | `string`       | `1..1` | `Organization[type=prov].identifier[system=https://facility.abdm.gov.in].value` | `IN1910000151`                      |                                                         |
| `providerName`     | Hospital Name                    | Provider     | `string`       | `1..1` | `Organization[type=prov].name`                                                  | `Apex Multispeciality Hospital`     |                                                         |
| `payerId`          | Payer Identifier (NIIP)          | Payer        | `string`       | `1..1` | `Organization[type=pay].identifier[system=https://irdai.gov.in].value`          | `1000003538`                        |                                                         |
| `payerName`        | Payer Name                       | Payer        | `string`       | `1..1` | `Organization[type=pay].name`                                                   | `National Health Authority - PMJAY` |                                                         |
| `practitionerId`   | Practitioner ID (HPID/HPIN)      | Practitioner | `string`       | `1..1` | `Practitioner.identifier[system=https://hpr.abdm.gov.in].value`                 | `21-8899-4455-6677`                 |                                                         |
| `practitionerName` | Doctor Name                      | Practitioner | `string`       | `1..1` | `Practitioner.name[0].text`                                                     | `Dr. Arvind Kumar`                  |                                                         |

NRCeS profiles: [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html), [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html), [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html), [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html).


---

# Claim response

The payer's adjudication of a submitted claim, on `/v1/claim/on_submit`. The same bundle carries an acknowledgement, an approval, a query and a rejection.

Sent on `/v1/claim/on_submit`.

## The bundle

| # | Resource              | Profile                                                                                                    |
| - | --------------------- | ---------------------------------------------------------------------------------------------------------- |
| 1 | `ClaimResponse`       | none declared; NRCeS [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html) |
| 2 | `Patient`             | none declared; NRCeS [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)             |
| 3 | `Organization (pay)`  | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)   |
| 4 | `Organization (prov)` | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)   |
| 5 | `Coverage`            | none declared; NRCeS [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)           |

## Elements

### ClaimResponse

NRCeS profile: [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html).

| Element                                   | Example                                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------------------------------ |
| `identifier[]`                            | system `<participant-defined>`, value `NM-26-0SE00002L`                                    |
| `identifier[].type.coding[]`              | `CLN` Claim number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code` |
| `status`                                  | `active`                                                                                   |
| `use`                                     | `claim`                                                                                    |
| `patient`                                 | reference `<participant-defined>`                                                          |
| `created`                                 | `2026-09-10T23:53:32+05:30`                                                                |
| `insurer`                                 | reference `<participant-defined>`                                                          |
| `requestor`                               | reference `<participant-defined>`                                                          |
| `outcome`                                 | `complete`                                                                                 |
| `disposition`                             | `Reprocessed and approved.`                                                                |
| `payeeType.coding[]`                      | `provider` Provider in `http://terminology.hl7.org/CodeSystem/payeetype`                   |
| `item[]`                                  | id `Item/LI-558aa12a`, itemSequence `1`                                                    |
| `item[].adjudication[].category.coding[]` | `submitted` Submitted Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`       |
|                                           | `eligible` Eligible Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`         |
|                                           | `reason` Reason for Adjudication in `https://hl7.org/fhir/R4/valueset-adjudication.html`   |
|                                           | and 1 more                                                                                 |
| `item[].adjudication[].amount`            | value `150000`                                                                             |
| `item[].adjudication[].reason.coding[]`   | display `Reprocessed and approved.`                                                        |
|                                           | `Approved` Approved                                                                        |
| `adjudication[].category.coding[]`        | `status` Status                                                                            |
| `adjudication[].reason.coding[]`          | `approved` Approved                                                                        |
| `total[].category.coding[]`               | `benefit` Benefit Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`           |
|                                           | `submitted` Submitted Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`       |
|                                           | `eligible` Eligible Amount                                                                 |
| `total[].amount`                          | value `150000`                                                                             |
| `total[]`                                 | id `MRAV1985001/SANDBOX-DEFAULT-01`                                                        |

### Patient

NRCeS profile: [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html).

| Element                      | Example                                                               |
| ---------------------------- | --------------------------------------------------------------------- |
| `identifier[]`               | system `<participant-defined>`, value `MRAV1985001`                   |
| `identifier[].type.coding[]` | `MB` Member Number in `http://terminology.hl7.org/CodeSystem/v2-0203` |
| `name[]`                     | family `Kumar`, given `Ravi`, text `Ravi Kumar`                       |
| `gender`                     | `male`                                                                |
| `birthDate`                  | `1985-06-15`                                                          |

### Organization (pay)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                               |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `active`                     | `true`                                                                                                |
| `identifier[]`               | system `https://facility.abdm.gov.in`, value `1000004805`                                             |
| `identifier[].type.coding[]` | `NIIP` National Insurance Payor Identifier (Payor) in `http://terminology.hl7.org/CodeSystem/v2-0203` |
| `type[].coding[]`            | `pay` Payer in `http://terminology.hl7.org/CodeSystem/organization-type`                              |
| `name`                       | `Sandbox Payer`                                                                                       |

### Organization (prov)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `active`                     | `true`                                                                                  |
| `identifier[]`               | system `https://facility.abdm.gov.in`, value `IN1910000151`                             |
| `identifier[].type.coding[]` | `NPI` National provider identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`   |
| `type[].coding[]`            | `prov` Healthcare Provider in `http://terminology.hl7.org/CodeSystem/organization-type` |
| `name`                       | `XYZ Multispeciality Hospital`                                                          |

### Coverage

NRCeS profile: [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html).

| Element                      | Example                                                                                  |
| ---------------------------- | ---------------------------------------------------------------------------------------- |
| `identifier[]`               | system `<participant-defined>`, value `SANDBOX-DEFAULT-01`                               |
| `identifier[].type.coding[]` | `NH` National Health Plan Identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`  |
| `status`                     | `active`                                                                                 |
| `type.coding[]`              | `HIP` health insurance plan policy in `http://terminology.hl7.org/CodeSystem/v3-ActCode` |
| `beneficiary`                | reference `<participant-defined>`                                                        |
| `period`                     | start `2026-01-01T00:00:00+05:30`, end `2026-12-31T00:00:00+05:30`                       |
| `payor[]`                    | reference `<participant-defined>`                                                        |
| `class[]`                    | id `POL7UMU002`, value `SANDBOX-DEFAULT-01`                                              |
| `class[].type.coding[]`      | `XV` Health Plan Identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`           |

## The answers

The same bundle, told apart by the workflow code, `outcome` and the claim-level adjudication reason.

| Variant      | Workflow | outcome    | reason                |
| ------------ | -------- | ---------- | --------------------- |
| Acknowledged | `25`     | `queued`   | `submitted` Submitted |
| Approved     | `26`     | `complete` | `approved` Approved   |
| Queried      | `27`     | `partial`  | `queried` Queried     |
| Rejected     | `291`    | `error`    | `rejected` Rejected   |

## Rules

### partial is two things

An acknowledgement and a query are both `partial`. Read the claim-level reason, then `disposition`, then the totals.

### Deductions

Item-level `deductible` adjudications carry the amount and the reason. Sum them before reporting an approved figure.

### Joining

Join the response to the claim by `identifier.value`.

### Settlement is separate

An approval closes adjudication, not the money. The claim closes on the payment notice.

### Submitted amounts

Do not reconcile your submitted amount against the payer's `submitted` total; it comes from the payer's own record.

## PMJAY

The generic bundle above is what every payer takes, IRDAI-regulated insurers and TPAs included. PMJAY takes it with the changes and requirements below.

### What changes in the bundle

PMJAY sends this exchange in the generic shape.

### What PMJAY specifies

- `total[]` adds a `tax` line beside `benefit` and `submitted`.
- The adjudication reason carries the desk's audit trail, with mixed date formats. Display it; never parse a timestamp from it.
- A benefit of 0 on a query means undetermined, not refused.

## Use cases, APIs and data elements

### C7 Respond to claim (payer)

The adjudicated claim, item by item, with any deduction and its reason. The acknowledgement on 25 travels as response.partial with the payer's case number. Under PMJAY a query is this ClaimResponse on 27, answered by a fresh submit on 161.

|                    |                                                                                                                            |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/claim/on_submit` [`apis/05-claim/v1-claim-on-submit.bru`](/docs/nhcx/v1/api/claim/endpoints/claim-v1-claim-on-submit) |
| **Callback**       | `/v1/claim/submit` [`apis/05-claim/v1-claim-submit.bru`](/docs/nhcx/v1/api/claim/endpoints/claim-v1-claim-submit)          |
| **Workflow**       | 25 received, 26 approved, 27 queried, 28 in process, 29 forwarded, 291 denied                                              |
| **Carries JWE**    | yes                                                                                                                        |
| **Focal resource** | `ClaimResponse`                                                                                                            |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1518@hcx`          |
| `x-hcx-recipient_code` | `1000004446@hcx`    |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `26`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `response.complete` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |
| `x-hcx-debug_flag`     | `INFO`              |

**Workflow codes**

| Code  | Name                     | Authored by       | `x-hcx-status`                                   | Means                                                                               |
| ----- | ------------------------ | ----------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `25`  | Claim Doc Ack            | payer             | `response.partial`, `response.error`             | The payer acknowledges the claim documents: success or failure                      |
| `26`  | Claim Request Approved   | payer             | `response.complete`                              | Final claim approved                                                                |
| `27`  | Claim Request Queried    | payer             | `request.initiated`, `response.partial/complete` | Final claim queried - payer needs additional documents; under PMJAY answer with 161 |
| `28`  | Claim Request In Process | payer             | `response.partial`                               | Final claim is being processed by payer                                             |
| `29`  | Claim Forwarded          | payer             | `response.partial`                               | Claim forwarded to another processing entity                                        |
| `291` | Claim Doc Deny           | status sheet only | `response.complete`                              |                                                                                     |

**Data elements**

| Element           | Label                   | Group        | Type      | Card.  | FHIR path                                                                        | Example                            | Notes |
| ----------------- | ----------------------- | ------------ | --------- | ------ | -------------------------------------------------------------------------------- | ---------------------------------- | ----- |
| `outcome`         | Claim Outcome           | Adjudication | `code`    | `1..1` | `ClaimResponse.outcome`                                                          | `complete`                         |       |
| `approvedBenefit` | Approved Claim Amount   | Financials   | `decimal` | `1..1` | `ClaimResponse.total[category=benefit].amount.value`                             | `15500.00`                         |       |
| `copayAmount`     | Beneficiary Co-payment  | Financials   | `decimal` | `0..1` | `ClaimResponse.total[category=copay].amount.value`                               | `0.00`                             |       |
| `deductionReason` | Deduction Justification | Adjudication | `string`  | `0..1` | `ClaimResponse.item[].adjudication[category=deduction].reason.coding[0].display` | `Non-medical consumables deducted` |       |

NRCeS profiles: [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html).


---

# Codes and value sets

Every code the bundles carry, grouped by the system it is bound to, then the value sets the specifications define beyond them. The workflow codes are in the Overview's Workflow Codes chapter and are not repeated here.

## Codes in the bundles

### `http://hl7.org/fhir/CodeSystem/task-code`

| Code      | Display                             | Where              | Used by |
| --------- | ----------------------------------- | ------------------ | ------- |
| `approve` | Activate/approve the focal resource | `Task.code.coding` | both    |

### `http://hl7.org/fhir/resource-types`

| Code            | Display | Where                     | Used by |
| --------------- | ------- | ------------------------- | ------- |
| `ClaimResponse` |         | `Task.output.type.coding` | generic |

### `http://hl7.org/fhir/sid/icd-10`

| Code    | Display                                        | Where                                             | Used by |
| ------- | ---------------------------------------------- | ------------------------------------------------- | ------- |
| `A97`   | Dengue                                         | `Claim.diagnosis.diagnosisCodeableConcept.coding` | generic |
| `E11.9` | Type 2 diabetes mellitus without complications | `Claim.diagnosis.diagnosisCodeableConcept.coding` | both    |
| `I46.9` | Cardiac arrest, unspecified                    | `Claim.diagnosis.diagnosisCodeableConcept.coding` | generic |

### `http://hl7.org/fhir/ValueSet/payment-type`

| Code      | Display | Where                                      | Used by |
| --------- | ------- | ------------------------------------------ | ------- |
| `Payment` | Payment | `PaymentReconciliation.detail.type.coding` | both    |
| `RF`      | RF      | `PaymentReconciliation.detail.type.coding` | PMJAY   |
| `TDS`     | TDS     | `PaymentReconciliation.detail.type.coding` | both    |

### `http://hl7.org/fhir/ValueSet/procedure-category`

| Code     | Display                                                                          | Where                                                 | Used by |
| -------- | -------------------------------------------------------------------------------- | ----------------------------------------------------- | ------- |
| `LM100`  | LAMA DAMA Procedure (LAMA DAMA Procedure)                                        | `InsurancePlan.plan.specificCost.benefit.type.coding` | PMJAY   |
| `MG004A` | Dengue fever (Dengue fever)                                                      | `InsurancePlan.plan.specificCost.benefit.type.coding` | PMJAY   |
| `MG005A` | Chikungunya fever (Chikungunya fever)                                            | `InsurancePlan.plan.specificCost.benefit.type.coding` | PMJAY   |
| `MG014A` | Liver abscess (Liver abscess)                                                    | `InsurancePlan.plan.specificCost.benefit.type.coding` | PMJAY   |
| `MG072C` | Acute Haemodialysis (Acute Haemodialysis)                                        | `InsurancePlan.plan.specificCost.benefit.type.coding` | PMJAY   |
| `MO071R` | PemetrexedPemetrexed 500mg/m2 D1 every 21 days (CT for CA Lung)                  | `InsurancePlan.plan.specificCost.benefit.type.coding` | PMJAY   |
| `SB043F` | Hand (Single Stage Amputation)                                                   | `InsurancePlan.plan.specificCost.benefit.type.coding` | PMJAY   |
| `SBU100` | Unspecified Surgical Package (Unspecified Surgical Package)                      | `InsurancePlan.plan.specificCost.benefit.type.coding` | PMJAY   |
| `SE004A` | Lid Tear Repair (Lid Tear Repair)                                                | `InsurancePlan.plan.specificCost.benefit.type.coding` | PMJAY   |
| `SE005A` | Lid Abscess Drainage (Lid Abscess Drainage)                                      | `InsurancePlan.plan.specificCost.benefit.type.coding` | PMJAY   |
| `SEU100` | Unspecified Surgical Package (Unspecified Surgical Package )                     | `InsurancePlan.plan.specificCost.benefit.type.coding` | PMJAY   |
| `SGU100` | Unspecified Surgical Package (Unspecified Surgical Package )                     | `InsurancePlan.plan.specificCost.benefit.type.coding` | PMJAY   |
| `SL026A` | Tracheostomy (Tracheostomy / Tracheotomy)                                        | `InsurancePlan.plan.specificCost.benefit.type.coding` | PMJAY   |
| `SL026B` | Tracheotomy (Tracheostomy / Tracheotomy)                                         | `InsurancePlan.plan.specificCost.benefit.type.coding` | PMJAY   |
| `ST009B` | Nerve and/or tendon injury. A. Wound exploration and closure. B. Nerve graft. C… | `InsurancePlan.plan.specificCost.benefit.type.coding` | PMJAY   |

### `http://snomed.info/sct`

| Code        | Display                                                               | Where                                                                                                    | Used by |
| ----------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------- |
| `105461009` | Organ donor                                                           | `InsurancePlan.coverage.type.coding`, `InsurancePlan.coverage.benefit.type.coding`                       | generic |
| `223366009` | Healthcare professional (occupation)                                  | `Claim.careTeam.role.coding`, `PractitionerRole.code.coding`                                             | generic |
| `224663004` | Single room (environment)                                             | `InsurancePlan.plan.specificCost.category.coding`, `InsurancePlan.plan.specificCost.benefit.type.coding` | generic |
| `24099007`  | Oxygen (substance)                                                    | `InsurancePlan.coverage.benefit.type.coding`                                                             | generic |
| `307988006` | Medical technician                                                    | `PractitionerRole.code.coding`                                                                           | both    |
| `309904001` | Intensive care unit                                                   | `Claim.item.productOrService.coding`, `InsurancePlan.coverage.benefit.type.coding`                       | generic |
| `394658006` | Clinical specialty (qualifier value)                                  | `Claim.careTeam.qualification.coding`                                                                    | generic |
| `394802001` | General medicine                                                      | `Claim.careTeam.qualification.coding`                                                                    | both    |
| `409972000` | Pre-hospital care                                                     | `InsurancePlan.coverage.type.coding`, `InsurancePlan.coverage.benefit.type.coding`                       | generic |
| `414005`    | Percutaneous Transluminal Coronary Angioplasty (PTCA)                 | `InsurancePlan.coverage.benefit.type.coding`, `InsurancePlan.plan.specificCost.benefit.type.coding`      | generic |
| `418285008` | Angioplasty of blood vessel                                           | `Claim.procedure.procedureCodeableConcept.coding`, `Claim.item.productOrService.coding`                  | generic |
| `427189009` | Paediatric Pneumonia, PICU Management                                 | `InsurancePlan.coverage.benefit.type.coding`, `InsurancePlan.plan.specificCost.benefit.type.coding`      | generic |
| `49122002`  | Ambulance, device (physical object)                                   | `InsurancePlan.coverage.type.coding`, `InsurancePlan.coverage.benefit.type.coding`                       | generic |
| `60689008`  | Home care of patient                                                  | `InsurancePlan.plan.specificCost.category.coding`, `InsurancePlan.plan.specificCost.benefit.type.coding` | generic |
| `710967003` | Management of health status after discharge from hospital (procedure) | `InsurancePlan.coverage.type.coding`, `InsurancePlan.coverage.benefit.type.coding`                       | generic |
| `71388002`  | Procedure (procedure)                                                 | `Procedure.code.coding`                                                                                  | both    |
| `737481003` | Inpatient care management (procedure)                                 | `Claim.type.coding`, `CoverageEligibilityResponse.insurance.item.productOrService.coding`                | both    |
| `737850002` | Day care case management (procedure)                                  | `InsurancePlan.coverage.type.coding`, `InsurancePlan.coverage.benefit.type.coding`                       | generic |
| `77343006`  | Angiography                                                           | `Claim.procedure.procedureCodeableConcept.coding`, `Claim.item.productOrService.coding`                  | generic |
| `86077009`  | Operation for glaucoma                                                | `InsurancePlan.extension.extension.valueCodeableConcept.coding`                                          | generic |
| `87612001`  | Blood                                                                 | `InsurancePlan.coverage.benefit.type.coding`                                                             | generic |
| `89100005`  | Final diagnosis (discharge) (contextual qualifier) (qualifier value)  | `Claim.diagnosis.type.coding`                                                                            | generic |

### `http://snomed.info/sct0`

| Code        | Display             | Where                                                                | Used by |
| ----------- | ------------------- | -------------------------------------------------------------------- | ------- |
| `305056002` | Admission procedure | `CoverageEligibilityResponse.insurance.item.productOrService.coding` | PMJAY   |

### `http://terminology.hl7.org/CodeSystem/adjudication`

| Code        | Display          | Where                                                                                    | Used by |
| ----------- | ---------------- | ---------------------------------------------------------------------------------------- | ------- |
| `benefit`   | Benefit Amount   | `ClaimResponse.item.adjudication.category.coding`, `ClaimResponse.total.category.coding` | generic |
| `copay`     | CoPay            | `ClaimResponse.item.adjudication.category.coding`                                        | generic |
| `eligible`  | Eligible Amount  | `ClaimResponse.item.adjudication.category.coding`, `ClaimResponse.total.category.coding` | generic |
| `submitted` | Submitted Amount | `ClaimResponse.item.adjudication.category.coding`, `ClaimResponse.total.category.coding` | generic |

### `http://terminology.hl7.org/CodeSystem/benefit-type`

| Code      | Display | Where                                                            | Used by |
| --------- | ------- | ---------------------------------------------------------------- | ------- |
| `benefit` | Benefit | `CoverageEligibilityResponse.insurance.item.benefit.type.coding` | both    |

### `http://terminology.hl7.org/CodeSystem/claimcareteamrole`

| Code      | Display          | Where                        | Used by |
| --------- | ---------------- | ---------------------------- | ------- |
| `primary` | Primary provider | `Claim.careTeam.role.coding` | both    |

### `http://terminology.hl7.org/CodeSystem/communication-category`

| Code           | Display      | Where                                                                   | Used by |
| -------------- | ------------ | ----------------------------------------------------------------------- | ------- |
| `alert`        |              | `CommunicationRequest.category.coding`                                  | generic |
| `information`  | Information  | `Task.reasonCode.coding`                                                | PMJAY   |
| `notification` | Notification | `Communication.category.coding`, `CommunicationRequest.category.coding` | both    |

### `http://terminology.hl7.org/CodeSystem/coverage-class`

| Code   | Display | Where                        | Used by |
| ------ | ------- | ---------------------------- | ------- |
| `plan` | Plan    | `Coverage.class.type.coding` | generic |

### `http://terminology.hl7.org/CodeSystem/ex-benefitcategory`

| Code | Display                      | Where                                                            | Used by |
| ---- | ---------------------------- | ---------------------------------------------------------------- | ------- |
| `30` | Health Benefit Plan Coverage | `CoverageEligibilityResponse.insurance.item.benefit.type.coding` | PMJAY   |

### `http://terminology.hl7.org/CodeSystem/ex-diagnosis-on-admission`

| Code  | Display | Where                                | Used by |
| ----- | ------- | ------------------------------------ | ------- |
| `yes` | Yes     | `Claim.diagnosis.onAdmission.coding` | both    |

### `http://terminology.hl7.org/CodeSystem/ex-diagnosistype`

| Code        | Display             | Where                         | Used by |
| ----------- | ------------------- | ----------------------------- | ------- |
| `admitting` | Admitting Diagnosis | `Claim.diagnosis.type.coding` | both    |

### `http://terminology.hl7.org/CodeSystem/financialtaskcode`

| Code        | Display | Where              | Used by |
| ----------- | ------- | ------------------ | ------- |
| `cancel`    |         | `Task.code.coding` | both    |
| `poll`      | Poll    | `Task.code.coding` | both    |
| `release`   |         | `Task.code.coding` | generic |
| `reprocess` |         | `Task.code.coding` | both    |
| `status`    |         | `Task.code.coding` | both    |

### `http://terminology.hl7.org/CodeSystem/financialtaskinputtype`

| Code      | Display     | Where                                               | Used by |
| --------- | ----------- | --------------------------------------------------- | ------- |
| `include` | Include     | `Task.input.type.coding`, `Task.output.type.coding` | both    |
| `status`  | Status code | `Task.input.type.coding`                            | both    |

### `http://terminology.hl7.org/CodeSystem/organization-type`

| Code   | Display             | Where                      | Used by |
| ------ | ------------------- | -------------------------- | ------- |
| `ins`  | Insurance Company   | `Organization.type.coding` | generic |
| `pay`  | Payer               | `Organization.type.coding` | both    |
| `prov` | Healthcare Provider | `Organization.type.coding` | both    |

### `http://terminology.hl7.org/CodeSystem/payeetype`

| Code       | Display  | Where                            | Used by |
| ---------- | -------- | -------------------------------- | ------- |
| `provider` | Provider | `ClaimResponse.payeeType.coding` | both    |

### `http://terminology.hl7.org/CodeSystem/paymentstatus`

| Code      | Display | Where                                | Used by |
| --------- | ------- | ------------------------------------ | ------- |
| `cleared` | Cleared | `PaymentNotice.paymentStatus.coding` | generic |
| `paid`    | Paid    | `PaymentNotice.paymentStatus.coding` | PMJAY   |

### `http://terminology.hl7.org/CodeSystem/processpriority`

| Code     | Display | Where                                                                 | Used by |
| -------- | ------- | --------------------------------------------------------------------- | ------- |
| `normal` | Normal  | `CoverageEligibilityRequest.priority.coding`, `Claim.priority.coding` | both    |

### `http://terminology.hl7.org/CodeSystem/subscriber-relationship`

| Code   | Display | Where                          | Used by |
| ------ | ------- | ------------------------------ | ------- |
| `self` | Self    | `Coverage.relationship.coding` | both    |

### `http://terminology.hl7.org/CodeSystem/v2-0203`

| Code   | Display                                     | Where                                                                     | Used by |
| ------ | ------------------------------------------- | ------------------------------------------------------------------------- | ------- |
| `JHN`  | Jurisdictional health number                | `Patient.identifier.type.coding`                                          | PMJAY   |
| `MB`   | Member Number                               | `Patient.identifier.type.coding`, `Task.for.identifier.type.coding`       | both    |
| `MD`   | Medical License number                      | `Practitioner.identifier.type.coding`                                     | generic |
| `NH`   | National Health Plan Identifier             | `Coverage.identifier.type.coding`, `InsurancePlan.identifier.type.coding` | both    |
| `NIIP` | National Insurance Payor Identifier (Payor) | `Organization.identifier.type.coding`                                     | both    |
| `NPI`  | National provider identifier                | `Organization.identifier.type.coding`                                     | both    |
| `PI`   | Patient internal identifier                 | `Patient.identifier.type.coding`                                          | PMJAY   |
| `PRN`  | Provider number                             | `Organization.identifier.type.coding`                                     | generic |
| `XV`   | Health Plan Identifier                      | `Coverage.class.type.coding`, `InsurancePlan.identifier.type.coding`      | both    |

### `http://terminology.hl7.org/CodeSystem/v2-0360`

| Code | Display            | Where                                    | Used by |
| ---- | ------------------ | ---------------------------------------- | ------- |
| `MD` | Doctor of Medicine | `Practitioner.qualification.code.coding` | both    |

### `http://terminology.hl7.org/CodeSystem/v3-ActCode`

| Code  | Display                      | Where                  | Used by |
| ----- | ---------------------------- | ---------------------- | ------- |
| `HIP` | health insurance plan policy | `Coverage.type.coding` | both    |

### `http://www.cms.gov/Medicare/Coding/ICD10`

| Code      | Display                                               | Where                                                                                                              | Used by |
| --------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------- |
| `02703ZZ` | Percutaneous Transluminal Coronary Angioplasty (PTCA) | `InsurancePlan.coverage.benefit.type.coding`, `InsurancePlan.plan.specificCost.benefit.type.coding`                | generic |
| `08RJ3JZ` | Cataract Surgery with Foldable IOL                    | `InsurancePlan.coverage.benefit.type.coding`, `InsurancePlan.plan.specificCost.benefit.type.coding`                | generic |
| `0DTJ4ZZ` | Acute Appendectomy (Laparoscopic)                     | `InsurancePlan.coverage.benefit.type.coding`, `InsurancePlan.plan.specificCost.benefit.type.coding`                | generic |
| `0SRC0JZ` | Total Knee Replacement (Unilateral)                   | `CoverageEligibilityResponse.insurance.item.productOrService.coding`, `InsurancePlan.coverage.benefit.type.coding` | generic |
| `5A09357` | Paediatric Pneumonia, PICU Management                 | `InsurancePlan.coverage.benefit.type.coding`, `InsurancePlan.plan.specificCost.benefit.type.coding`                | generic |

### `https://hl7.org/fhir/R4/codesystem-benefit-type.html`

| Code        | Display   | Where                                                            | Used by |
| ----------- | --------- | ---------------------------------------------------------------- | ------- |
| `Procedure` | Procedure | `CoverageEligibilityResponse.insurance.item.benefit.type.coding` | PMJAY   |

### `https://hl7.org/fhir/R4/v2/0360/2.7/index.html`

| Code          | Display     | Where                                    | Used by |
| ------------- | ----------- | ---------------------------------------- | ------- |
| `BSC NURSING` | BSC NURSING | `Practitioner.qualification.code.coding` | PMJAY   |

### `https://hl7.org/fhir/R4/valueset-adjudication.html`

| Code          | Display                  | Where                                                                                    | Used by |
| ------------- | ------------------------ | ---------------------------------------------------------------------------------------- | ------- |
| `benefit`     | Benefit Amount           | `ClaimResponse.total.category.coding`                                                    | both    |
| `eligible`    | Eligible Amount          | `ClaimResponse.item.adjudication.category.coding`                                        | both    |
| `eligpercent` | Eligible %               | `ClaimResponse.item.adjudication.category.coding`                                        | PMJAY   |
| `eligquant`   | Eligible Quantity        | `ClaimResponse.item.adjudication.category.coding`                                        | PMJAY   |
| `incentive`   | Hospital Incentive       | `ClaimResponse.total.category.coding`                                                    | PMJAY   |
| `reason`      | Reason for Adjudication  | `ClaimResponse.item.adjudication.category.coding`                                        | both    |
| `status`      | Item adjudication status | `ClaimResponse.item.adjudication.category.coding`                                        | both    |
| `submitted`   | Submitted Amount         | `ClaimResponse.total.category.coding`, `ClaimResponse.item.adjudication.category.coding` | both    |
| `tax`         | Tax                      | `ClaimResponse.total.category.coding`                                                    | PMJAY   |

### `https://https://nrces.in/ndhm/fhir/r4/ValueSet-ndhm-identifier-type-code.html`

| Code   | Display           | Where                                                 | Used by |
| ------ | ----------------- | ----------------------------------------------------- | ------- |
| `PLAC` | Placer Identifier | `PaymentReconciliation.detail.identifier.type.coding` | both    |

### `https://nhcx.abdm.gov.in/category-code`

| Code       | Display          | Where                                             | Used by |
| ---------- | ---------------- | ------------------------------------------------- | ------- |
| `MG`       | General Medicine | `CoverageEligibilityRequest.item.category.coding` | both    |
| `Surgical` | Surgical         | `CoverageEligibilityRequest.item.category.coding` | generic |

### `https://nhcx.abdm.gov.in/communication-reason`

| Code             | Display                        | Where                    | Used by |
| ---------------- | ------------------------------ | ------------------------ | ------- |
| `additionalinfo` | Additional information request | `Task.reasonCode.coding` | generic |
| `tatquery`       | Turnaround time query          | `Task.reasonCode.coding` | generic |

### `https://nhcx.abdm.gov.in/document-code`

| Code       | Display                                                                          | Where                              | Used by |
| ---------- | -------------------------------------------------------------------------------- | ---------------------------------- | ------- |
| `CER`      | Medical Certificate / Doctor Referral                                            | `Claim.supportingInfo.code.coding` | generic |
| `DOC001`   | Clinical notes and admission notes                                               | `Claim.supportingInfo.code.coding` | generic |
| `DOC002`   | Diagnostic imaging report                                                        | `Claim.supportingInfo.code.coding` | generic |
| `DOC003`   | Investigations performed                                                         | `Claim.supportingInfo.code.coding` | generic |
| `DOC004`   | Planned line of management                                                       | `Claim.supportingInfo.code.coding` | generic |
| `DOC101`   | Internal case papers                                                             | `Claim.supportingInfo.code.coding` | generic |
| `DOC102`   | Treatment details                                                                | `Claim.supportingInfo.code.coding` | generic |
| `DOC103`   | All investigation reports                                                        | `Claim.supportingInfo.code.coding` | generic |
| `DOC104`   | Discharge summary                                                                | `Claim.supportingInfo.code.coding` | generic |
| `EST`      | Detailed Pre-Auth Cost Estimate                                                  | `Claim.supportingInfo.code.coding` | generic |
| `FCF`      | Filled NHCX Claim Form (Signed)                                                  | `Claim.supportingInfo.code.coding` | generic |
| `HDS`      | Hospital Discharge Summary                                                       | `Claim.supportingInfo.code.coding` | both    |
| `IMP`      | Medical Implant Invoice & Barcode Sticker                                        | `Claim.supportingInfo.code.coding` | generic |
| `MAND0006` | Detailed discharge summary                                                       | `Claim.supportingInfo.code.coding` | generic |
| `MAND0062` | Detailed ICPs                                                                    | `Claim.supportingInfo.code.coding` | generic |
| `MAND0063` | Treatment details                                                                | `Claim.supportingInfo.code.coding` | generic |
| `MAND0064` | All investigations reports                                                       | `Claim.supportingInfo.code.coding` | generic |
| `MAND0408` | Clinical notes detailing history and Admission notes showing vitals and examina… | `Claim.supportingInfo.code.coding` | both    |
| `MAND0409` | Any investigations done                                                          | `Claim.supportingInfo.code.coding` | both    |
| `MAND0455` | CXR PA view or CECT chest abdomen and pelvis                                     | `Claim.supportingInfo.code.coding` | both    |
| `MAND0570` | Planned line of management                                                       | `Claim.supportingInfo.code.coding` | both    |
| `MB`       | Medical & Pharmacy Bills Itemized                                                | `Claim.supportingInfo.code.coding` | generic |
| `ODN`      | Death Certificate                                                                | `Claim.supportingInfo.code.coding` | PMJAY   |
| `OTR`      | Operation Theatre Notes & Surgical Summary                                       | `Claim.supportingInfo.code.coding` | generic |
| `POI`      | Proof of Identity (Aadhaar / Passport / Voter ID)                                | `Claim.supportingInfo.code.coding` | generic |
| `RAD`      | Radiology / X-Ray / CT / MRI Scan Reports                                        | `Claim.supportingInfo.code.coding` | generic |

### `https://nhcx.abdm.gov.in/procedure-type`

| Code           | Display      | Where                                                                           | Used by |
| -------------- | ------------ | ------------------------------------------------------------------------------- | ------- |
| `conservative` | Conservative | `Claim.procedure.type.coding`                                                   | both    |
| `medical`      | Medical      | `Claim.procedure.type.coding`                                                   | PMJAY   |
| `STRAT001`     | HDU          | `CoverageEligibilityRequest.item.modifier.coding`, `Claim.item.modifier.coding` | generic |
| `surgical`     | Surgical     | `Claim.procedure.type.coding`                                                   | generic |

### `https://nhcx.abdm.gov.in/product-code`

| Code           | Display                                   | Where                                                     | Used by |
| -------------- | ----------------------------------------- | --------------------------------------------------------- | ------- |
| `MG004C`       | Dengue shock syndrome (Dengue fever)      | `CoverageEligibilityRequest.item.productOrService.coding` | generic |
| `MG0111A`      | Pleural Effusion (Pleural Effusion)       | `CoverageEligibilityRequest.item.productOrService.coding` | PMJAY   |
| `MG072C`       | Acute Haemodialysis (Acute Haemodialysis) | `CoverageEligibilityRequest.item.productOrService.coding` | PMJAY   |
| `PROC-KNEE-01` | Total Knee Replacement (Unilateral)       | `CoverageEligibilityRequest.item.productOrService.coding` | generic |

### `https://nhcx.abdm.gov.in/task-input-type`

| Code     | Display | Where                    | Used by |
| -------- | ------- | ------------------------ | ------- |
| `amount` | Amount  | `Task.input.type.coding` | generic |

### `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-benefit-category`

| Code       | Display          | Where                                                                           | Used by |
| ---------- | ---------------- | ------------------------------------------------------------------------------- | ------- |
| `MG`       | General Medicine | `Claim.item.category.coding`, `CoverageEligibilityRequest.item.category.coding` | both    |
| `Surgical` | Surgical         | `Claim.item.category.coding`                                                    | generic |

### `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-claim-exclusion`

| Code     | Display                                    | Where                                                           | Used by |
| -------- | ------------------------------------------ | --------------------------------------------------------------- | ------- |
| `Excl01` | Pre-Existing Diseases                      | `InsurancePlan.extension.extension.valueCodeableConcept.coding` | generic |
| `Excl02` | Specified disease/procedure waiting period | `InsurancePlan.extension.extension.valueCodeableConcept.coding` | generic |
| `Excl03` | 30-day waiting period                      | `InsurancePlan.extension.extension.valueCodeableConcept.coding` | generic |
| `Excl08` | Cosmetic or plastic Surgery                | `InsurancePlan.extension.extension.valueCodeableConcept.coding` | generic |

### `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`

| Code          | Display                                                   | Where                                                                 | Used by |
| ------------- | --------------------------------------------------------- | --------------------------------------------------------------------- | ------- |
| `ABHA`        | Ayushman Bharat Health Account (ABHA) ID                  | `Patient.identifier.type.coding`                                      | both    |
| `ADN`         | Adhaar number                                             | `Patient.identifier.type.coding`                                      | both    |
| `ClaimNumber` | Claim Number                                              | `Task.input.type.coding`                                              | generic |
| `CLN`         | Claim number                                              | `Claim.identifier.type.coding`, `Task.basedOn.identifier.type.coding` | both    |
| `HPID`        | Healthcare Professional ID (HPID)                         | `Practitioner.identifier.type.coding`                                 | both    |
| `HPIN`        | Health Practitioner ID issued by NDHM                     | `Practitioner.identifier.type.coding`                                 | both    |
| `PMJAY`       | Pradhan Mantri Jan Aarogya Yojana (PMJAY) ID              | `Patient.identifier.type.coding`, `Task.for.identifier.type.coding`   | both    |
| `ROHINI`      | Registry of Hospitals in Network of Insurance (ROHINI) ID | `Organization.identifier.type.coding`                                 | generic |
| `UTR`         | Unique Transaction Reference                              | `PaymentReconciliation.paymentIdentifier.type.coding`                 | both    |

### `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-insuranceplan-type`

| Code | Display                          | Where                       | Used by |
| ---- | -------------------------------- | --------------------------- | ------- |
| `01` | Hospitalisation Indemnity Policy | `InsurancePlan.type.coding` | generic |
| `07` | Universal Health Policy          | `InsurancePlan.type.coding` | PMJAY   |

### `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-plan-type`

| Code        | Display                                                                    | Where                                                      | Used by |
| ----------- | -------------------------------------------------------------------------- | ---------------------------------------------------------- | ------- |
| `01`        | Individual                                                                 | `InsurancePlan.plan.type.coding`                           | generic |
| `03`        | Group                                                                      | `InsurancePlan.plan.type.coding`                           | PMJAY   |
| `Procedure` | Selected treatment or service or product is a type of procedure or package | `InsurancePlan.plan.specificCost.benefit.cost.type.coding` | generic |

### `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-procedure-code`

| Code           | Display                                   | Where                                                                                                                           | Used by |
| -------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `MG001A`       | Sample package                            | `CoverageEligibilityRequest.item.productOrService.coding`, `CoverageEligibilityResponse.insurance.item.productOrService.coding` | generic |
| `MG004B`       | Dengue hemorrhagic fever                  | `Claim.item.productOrService.coding`                                                                                            | generic |
| `MG0111A`      | Pleural Effusion                          | `Claim.item.productOrService.coding`                                                                                            | both    |
| `MG072C`       | Acute Haemodialysis (Acute Haemodialysis) | `Claim.item.productOrService.coding`                                                                                            | PMJAY   |
| `PROC-APP-02`  | Acute Appendectomy (Laparoscopic)         | `Claim.item.productOrService.coding`                                                                                            | generic |
| `PROC-KNEE-01` | Total Knee Replacement (Unilateral)       | `Claim.item.productOrService.coding`                                                                                            | generic |

### `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-program-code`

| Code       | Display                                                     | Where                           | Used by |
| ---------- | ----------------------------------------------------------- | ------------------------------- | ------- |
| `AB-PMJAY` | Ayushman Bharat Pradhan Mantri Jan Arogya Yojana (AB-PMJAY) | `Claim.item.programCode.coding` | both    |

### `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-reason-code`

| Code                   | Display                                           | Where                                                              | Used by |
| ---------------------- | ------------------------------------------------- | ------------------------------------------------------------------ | ------- |
| `additionalinfo`       | Additional Information Request                    | `Task.reasonCode.coding`, `CommunicationRequest.reasonCode.coding` | generic |
| `administrativeerror`  | Administrative error                              | `Task.reasonCode.coding`                                           | PMJAY   |
| `claimrejected`        | Reprocess request due to claim rejected by payer  | `Task.reasonCode.coding`                                           | both    |
| `partialpayment`       | Reprocess request due to partial payment by payer | `Task.reasonCode.coding`                                           | generic |
| `treatmentplanchanged` | Treatment plan changed during hospitalization.    | `Task.reasonCode.coding`                                           | generic |

### `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`

| Code  | Display                                                                          | Where                                                                                                                                                                       | Used by |
| ----- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `CD`  | Clinical document                                                                | `InsurancePlan.coverage.benefit.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.valueCodeableConcept.coding` | both    |
| `CER` | Medical Certficate                                                               | `InsurancePlan.coverage.benefit.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.valueCodeableConcept.coding` | generic |
| `DIA` | Diagnostic report                                                                | `InsurancePlan.coverage.benefit.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.valueCodeableConcept.coding` | both    |
| `DIS` | Discharge status and discharge to location detail                                | `Claim.supportingInfo.category.coding`                                                                                                                                      | both    |
| `FCF` | Filled claim form                                                                | `InsurancePlan.coverage.benefit.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.valueCodeableConcept.coding` | generic |
| `HDS` | Hospital discharge summary                                                       | `Claim.supportingInfo.category.coding`, `InsurancePlan.coverage.benefit.extension.extension.valueCodeableConcept.coding`                                                    | both    |
| `IMP` | Document Type - Implant                                                          | `InsurancePlan.coverage.benefit.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.valueCodeableConcept.coding` | generic |
| `INF` | Information                                                                      | `Claim.supportingInfo.category.coding`, `InsurancePlan.coverage.benefit.extension.extension.valueCodeableConcept.coding`                                                    | both    |
| `INV` | Document Type - Investigation                                                    | `Claim.supportingInfo.category.coding`                                                                                                                                      | both    |
| `MB`  | Medical bill                                                                     | `InsurancePlan.coverage.benefit.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.valueCodeableConcept.coding` | generic |
| `NMI` | Claim query detail                                                               | `Claim.supportingInfo.category.coding`                                                                                                                                      | both    |
| `ONS` | Period, start or end dates of aspects of the Condition. (e.g. admission, discha… | `Claim.supportingInfo.category.coding`                                                                                                                                      | both    |
| `OTH` | Other                                                                            | `Claim.supportingInfo.category.coding`                                                                                                                                      | both    |
| `POI` | Proof of identity                                                                | `InsurancePlan.coverage.benefit.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.valueCodeableConcept.coding` | both    |
| `STG` | Total Knee Replacement (Unilateral), Standard Treatment Guidelines               | `CoverageEligibilityResponse.insurance.item.authorizationSupporting.coding`, `InsurancePlan.coverage.benefit.extension.extension.valueCodeableConcept.coding`               | both    |

### `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-code`

| Code   | Display                                            | Where                              | Used by |
| ------ | -------------------------------------------------- | ---------------------------------- | ------- |
| `ADDD` | Admission date -Discharge date                     | `Claim.supportingInfo.code.coding` | both    |
| `CQD`  | Claim query detail                                 | `Claim.supportingInfo.code.coding` | both    |
| `DSDE` | Discharge start-discharge end time                 | `Claim.supportingInfo.code.coding` | both    |
| `DTH`  | DischargeToHome (Discharge disposition status)     | `Claim.supportingInfo.code.coding` | both    |
| `DTM`  | DischargetoMortuary                                | `Claim.supportingInfo.code.coding` | PMJAY   |
| `EDT`  | EncounterDateTime                                  | `Claim.supportingInfo.code.coding` | both    |
| `ODN`  | Other document                                     | `Claim.supportingInfo.code.coding` | both    |
| `PSP`  | PatientSurgeryPerformed(startdatetime-enddatetime) | `Claim.supportingInfo.code.coding` | both    |

### `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-codes`

| Code      | Display | Where              | Used by |
| --------- | ------- | ------------------ | ------- |
| `deliver` | deliver | `Task.code.coding` | both    |
| `search`  | Search  | `Task.code.coding` | generic |

### `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-input-type-code`

| Code               | Display           | Where                                               | Used by |
| ------------------ | ----------------- | --------------------------------------------------- | ------- |
| `claimNumber`      | ClaimNumber       | `Task.input.type.coding`, `Task.output.type.coding` | both    |
| `document`         | Document          | `Task.input.type.coding`                            | both    |
| `intimationNumber` | Intimation Number | `Task.input.type.coding`                            | both    |
| `policyNumber`     |                   | `Task.input.type.coding`                            | both    |
| `providerId`       |                   | `Task.input.type.coding`                            | both    |

### `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-output-type`

| Code     | Display | Where                     | Used by |
| -------- | ------- | ------------------------- | ------- |
| `status` | Status  | `Task.output.type.coding` | both    |

### `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-output-value`

| Code         | Display                        | Where                                     | Used by |
| ------------ | ------------------------------ | ----------------------------------------- | ------- |
| `paymentack` | Payment is acknowledged        | `Task.output.valueCodeableConcept.coding` | both    |
| `taskak`     | Requested task is acknowledged | `Task.output.valueCodeableConcept.coding` | generic |

### `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-benefitcategory`

| Code | Display           | Where                                                                                   | Used by |
| ---- | ----------------- | --------------------------------------------------------------------------------------- | ------- |
| `MG` | General Medicine  | `InsurancePlan.coverage.type.coding`, `InsurancePlan.plan.specificCost.category.coding` | PMJAY   |
| `MO` | Medical Oncology  | `InsurancePlan.coverage.type.coding`, `InsurancePlan.plan.specificCost.category.coding` | PMJAY   |
| `SB` | Orthopaedics      | `InsurancePlan.coverage.type.coding`, `InsurancePlan.plan.specificCost.category.coding` | PMJAY   |
| `SC` | Surgical Oncology | `InsurancePlan.coverage.type.coding`                                                    | PMJAY   |
| `SE` | Opthalmology      | `InsurancePlan.coverage.type.coding`, `InsurancePlan.plan.specificCost.category.coding` | PMJAY   |
| `SG` | General Surgery   | `InsurancePlan.coverage.type.coding`, `InsurancePlan.plan.specificCost.category.coding` | PMJAY   |
| `SU` | Urology           | `InsurancePlan.coverage.type.coding`                                                    | PMJAY   |

### `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-claim-type`

| Code        | Display                                | Where                       | Used by |
| ----------- | -------------------------------------- | --------------------------- | ------- |
| `737481003` | Inpatient care management (procedure)  | `ClaimResponse.type.coding` | both    |
| `737492002` | Outpatient care management (procedure) | `ClaimResponse.type.coding` | PMJAY   |

### `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-productorservice`

| Code        | Display                                                                          | Where                                                            | Used by |
| ----------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------- |
| `LM100`     | LAMA DAMA Procedure (LAMA DAMA Procedure)                                        | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `MG004A`    | Dengue fever (Dengue fever)                                                      | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `MG005A`    | Chikungunya fever (Chikungunya fever)                                            | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `MG014A`    | Liver abscess (Liver abscess)                                                    | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `MG072C`    | Acute Haemodialysis (Acute Haemodialysis)                                        | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `MO071R`    | PemetrexedPemetrexed 500mg/m2 D1 every 21 days (CT for CA Lung)                  | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `SB043F`    | Hand (Single Stage Amputation)                                                   | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `SBU100`    | Unspecified Surgical Package (Unspecified Surgical Package)                      | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `SC006A`    | Open-Transthoracic esophagectomy: 2F / 3F (Transthoracic esophagectomy: 2F / 3F) | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `SCU100`    | Unspecified Surgical Package (Unspecified Surgical Package)                      | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `SE004A`    | Lid Tear Repair (Lid Tear Repair)                                                | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `SE005A`    | Lid Abscess Drainage (Lid Abscess Drainage)                                      | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `SEU100`    | Unspecified Surgical Package (Unspecified Surgical Package )                     | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `SGU100`    | Unspecified Surgical Package (Unspecified Surgical Package )                     | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `SL026A`    | Tracheostomy (Tracheostomy / Tracheotomy)                                        | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `SL026B`    | Tracheotomy (Tracheostomy / Tracheotomy)                                         | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `SL032B`    | Translabyrinthine approach (Advanced lateral skull base surgery)                 | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `ST009B`    | Nerve and/or tendon injury. A. Wound exploration and closure. B. Nerve graft. C… | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |
| `STRAT003a` | Local Anesthesia                                                                 | `InsurancePlan.plan.specificCost.benefit.cost.qualifiers.coding` | PMJAY   |
| `STRAT003b` | General Anesthesia                                                               | `InsurancePlan.plan.specificCost.benefit.cost.qualifiers.coding` | PMJAY   |
| `STRAT006a` | Routine Ward                                                                     | `InsurancePlan.plan.specificCost.benefit.cost.qualifiers.coding` | PMJAY   |
| `STRAT006b` | HDU                                                                              | `InsurancePlan.plan.specificCost.benefit.cost.qualifiers.coding` | PMJAY   |
| `STRAT006c` | ICU - Without Ventilator                                                         | `InsurancePlan.plan.specificCost.benefit.cost.qualifiers.coding` | PMJAY   |
| `STRAT006d` | ICU - With Ventilator                                                            | `InsurancePlan.plan.specificCost.benefit.cost.qualifiers.coding` | PMJAY   |
| `SU037A`    | Acute management of upper urinary tract trauma – conservative ( (1-5 days)plus … | `InsurancePlan.coverage.benefit.type.coding`                     | PMJAY   |

### `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`

| Code       | Display                                                                          | Where                                                                                                                                                                                           | Used by |
| ---------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `ADN`      | Aadhaar Number                                                                   | `InsurancePlan.extension.extension.valueCodeableConcept.coding`                                                                                                                                 | PMJAY   |
| `MAND0003` | Clinical notes                                                                   | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0006` | Detailed discharge summary                                                       | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0008` | Detailed Procedure / Operative Notes                                             | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0030` | Procedure / Operative Notes                                                      | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0062` | Detailed ICPs                                                                    | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0063` | Treatment details                                                                | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0064` | All investigations reports                                                       | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0067` | CBC                                                                              | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0074` | LFT                                                                              | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0099` | BAR CODE OF THE DRUGS                                                            | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0100` | REPORTS OF THE TESTS (PATHOLOGY, RADIOLOGY, MICROBIOLOGY, HEMATOLOGY, BIOCHEMIS… | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0101` | DISCHARGE SUMMARY OF INPATIENT DEPARTMENT / DISCHARGE SUMMARY OF DAY CARE DEPAR… | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0102` | CHARTS OF CHEMOTHERAPY REGIMEN                                                   | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0103` | TRANFUSION SLIPS                                                                 | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0112` | Post Procedure clinical photgraph                                                | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0151` | Post Procedure Photographs of surgical site                                      | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`                                                                                                      | PMJAY   |
| `MAND0152` | HPE report                                                                       | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`                                                                                                      | PMJAY   |
| `MAND0159` | Still image of the the procedure with pt. ID and date                            | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0161` | operative notes                                                                  | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0162` | Discharge notes                                                                  | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0163` | microbiology report                                                              | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0164` | Still image of the patient undergoing the procedure with date stamp              | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0189` | Histopathology report                                                            | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0226` | Post Procedure Photograph of affected part                                       | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0300` | Detailed operatives notes                                                        | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0309` | Intra operative still photograph                                                 | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0326` | Reports of all investigations done and consultation paper of treating doctor me… | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`                                                                                                      | PMJAY   |
| `MAND0327` | Detailed discharge summary;                                                      | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`                                                                                                      | PMJAY   |
| `MAND0339` | Clinical notes with planned line of treatment                                    | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`                                                                                                      | PMJAY   |
| `MAND0368` | Procedure / Operative Notes, Detailed Discharge Summary                          | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0384` | MLC/ FIR if traumatic                                                            | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0408` | Clinical notes detailing history and Admission notes showing vitals and examina… | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0409` | any investigations done                                                          | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0447` | RFT                                                                              | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0457` | RBS                                                                              | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0459` | CECT Thorax, abdomen and Pelvis                                                  | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0564` | histopathology (non small cell - adenocarcinoma or adenosquamous carcinoma)      | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0582` | clinical photograph of affected part                                             | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0588` | clinical photograph                                                              | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0592` | X Ray of affected limb                                                           | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0604` | clinical notes justifying the indication                                         | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0621` | FNAC/ BIOPSY                                                                     | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`                                                                                                      | PMJAY   |
| `MAND0622` | CECT                                                                             | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`                                                                                                      | PMJAY   |
| `MAND0647` | FIR/MLC in case of accident                                                      | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0648` | Patient details                                                                  | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0649` | doctors notes                                                                    | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0650` | photo                                                                            | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0730` | USG/CT Abdomen                                                                   | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`                                                                                                      | PMJAY   |
| `MAND0822` | Clinical notes with planned line of treatment justifying indication              | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0831` | Audiogram report justfying surgery                                               | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`                                                                                                      | PMJAY   |
| `MAND0832` | CT- TEMPORAL BONE of affected side /X-RAY BOTH MASTOIDS                          | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`                                                                                                      | PMJAY   |
| `MAND0946` | Clinical notes detailing the injury and need of surgery                          | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND0952` | MLC/ FIR +/- Nerve conduction velocity (NCV) + /- MRI + /- MRA + /- EMG (Electr… | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `MAND1045` | Clinical notes with planned line of treatment (including indication for need of… | `InsurancePlan.coverage.benefit.extension.extension.extension.valueCodeableConcept.coding`, `InsurancePlan.plan.specificCost.benefit.extension.extension.extension.valueCodeableConcept.coding` | PMJAY   |
| `ODN`      | Other document                                                                   | `InsurancePlan.extension.extension.valueCodeableConcept.coding`                                                                                                                                 | PMJAY   |

### `https://payer.pmjay.nha.gov.in`

| Code     | Display                      | Where                                                                       | Used by |
| -------- | ---------------------------- | --------------------------------------------------------------------------- | ------- |
| `A97.0`  | Dengue without warning signs | `CoverageEligibilityRequest.item.diagnosis.diagnosisCodeableConcept.coding` | PMJAY   |
| `MG004A` | Dengue fever                 | `CoverageEligibilityRequest.item.productOrService.coding`                   | PMJAY   |

### `https://terminology.hl7.org/6.5.0/CodeSystem-subscriber-relationship.html`

| Code    | Display | Where                          | Used by |
| ------- | ------- | ------------------------------ | ------- |
| `child` | Child   | `Coverage.relationship.coding` | PMJAY   |

### `https://www.nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-plan-type`

| Code             | Display                                                                    | Where                                                      | Used by |
| ---------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------- | ------- |
| `Procedure`      | Selected treatment or service or proudct is a type of procedure or package | `InsurancePlan.plan.specificCost.benefit.cost.type.coding` | PMJAY   |
| `Stratification` | Selected treatment or service or proudct is a type of stratification       | `InsurancePlan.plan.specificCost.benefit.cost.type.coding` | PMJAY   |

## Value sets

The codes the specifications define beyond those the bundles carry.

### Supporting-info categories

System `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`.

| Code    | Meaning                                    | Notes            |
| ------- | ------------------------------------------ | ---------------- |
| `ONS`   | Period, start or end dates                 | date-time string |
| `OTH`   | Other                                      | date-time string |
| `INV`   | Investigation                              | reference        |
| `ATT`   | Attachment                                 | attachment       |
| `HDS`   | Hospital discharge summary                 | reference        |
| `DGN`   | Diagnosis                                  | reference        |
| `LAB`   | Lab test                                   | reference        |
| `AOB`   | Onset of current symptoms                  | value            |
| `MB`    | Medical bill                               | attachment       |
| `DIA`   | Diagnostic report                          | reference        |
| `CD`    | Clinical document                          | reference        |
| `INF`   | Information                                | reference        |
| `DIS`   | Discharge status                           | string           |
| `NMI`   | Query remarks                              | string           |
| `POI`   | Proof of identity                          | attachment       |
| `POA`   | Proof of address                           | attachment       |
| `DOB`   | Proof of birth                             | attachment       |
| `DEF`   | Declaration                                | attachment       |
| `FIR`   | First information report                   | attachment       |
| `EMP`   | Proof of employment                        | attachment       |
| `STG`   | Standard treatment guideline questionnaire | reference        |
| `ADMD`  | Admission date                             | date-time string |
| `SURD`  | Surgery date                               | date-time string |
| `DSCHD` | Discharge date                             | date-time string |

### Supporting-info codes

System `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`.

| Code    | Meaning                             | Notes                                                                              |
| ------- | ----------------------------------- | ---------------------------------------------------------------------------------- |
| `EDT`   | EncounterDateTime                   |                                                                                    |
| `ADDD`  | Admission date - Discharge date     |                                                                                    |
| `PSP`   | PatientSurgeryPerformed             |                                                                                    |
| `DSDE`  | Discharge Date                      |                                                                                    |
| `DTH`   | DischargeToHome                     |                                                                                    |
| `DTM`   | DischargetoMortuary                 | Also the death date under `ONS`                                                    |
| `LAMA`  | Discharge with LAMA                 |                                                                                    |
| `DAMA`  | Discharge with DAMA                 |                                                                                    |
| `DIS`   | Discharge Summary                   |                                                                                    |
| `AT`    | Questionnaire answers               | Under `INF`                                                                        |
| `ODN`   | Policy-level questionnaire          | Under `INF`                                                                        |
| `CQD`   | Case remarks for a query answer     | Under `NMI`                                                                        |
| `BCF`   | Birth certificate                   |                                                                                    |
| `DCB`   | Discharge card for birth of a child |                                                                                    |
| `MAND…` | Mandatory documents                 | Defined by the plan; the auth-requirements answer returns the ones a package needs |

### Identifier types

| Code    | Meaning                      | Notes       |
| ------- | ---------------------------- | ----------- |
| `PMJAY` | Scheme member id             | NRCeS       |
| `ABHA`  | ABHA number, no hyphens      | NRCeS       |
| `CLN`   | Claim number                 | NRCeS       |
| `UTR`   | Bank transaction reference   | NRCeS       |
| `HPID`  | Healthcare professional id   | NRCeS       |
| `HPIN`  | Health practitioner id       | NRCeS       |
| `NPI`   | Provider's HFR ID            | HL7 v2-0203 |
| `NIIP`  | Payer's registry ID          | HL7 v2-0203 |
| `NH`    | Plan identifier              | HL7 v2-0203 |
| `JHN`   | Jurisdictional health number | HL7 v2-0203 |
| `MD`    | Medical registration number  | HL7 v2-0203 |
| `MR`    | Medical record number        | HL7 v2-0203 |

### Adjudication

| Code          | Meaning                   | Notes              |
| ------------- | ------------------------- | ------------------ |
| `submitted`   | Amount asked              | category           |
| `eligible`    | Amount allowed            | category           |
| `benefit`     | Amount payable            | category           |
| `copay`       | Co-payment                | category           |
| `eligpercent` | Percentage allowed        | category           |
| `eligquant`   | Quantity allowed          | category           |
| `reason`      | Free-text reason          | category           |
| `status`      | Decision                  | category           |
| `deductible`  | Deduction with its reason | category           |
| `tax`         | Tax                       | total              |
| `incentive`   | Hospital incentive        | total              |
| `approved`    | Approved                  | claim-level reason |
| `queried`     | Queried                   | claim-level reason |
| `cancelled`   | Cancelled or rejected     | claim-level reason |
| `rejected`    | Rejected                  | claim-level reason |

### Task codes

| Code        | Meaning                                                                            | Notes             |
| ----------- | ---------------------------------------------------------------------------------- | ----------------- |
| `poll`      | Poll                                                                               | financialtaskcode |
| `cancel`    | Cancel                                                                             | financialtaskcode |
| `reprocess` | Reprocess                                                                          | financialtaskcode |
| `release`   | Release                                                                            | financialtaskcode |
| `status`    | Status                                                                             | financialtaskcode |
| `nullify`   | Close a claim the provider submitted                                               | financialtaskcode |
| `suspend`   | Suspend a preauthorisation or claim the provider submitted; no exchange carries it | financialtaskcode |
| `search`    | Search                                                                             | NHCX value set    |
| `deliver`   | Deliver                                                                            | ndhm-task-codes   |
| `approve`   | Approve                                                                            | task-code         |

### Task reasons

| Code                    | Meaning                | Notes              |
| ----------------------- | ---------------------- | ------------------ |
| `treatmentplanchanged`  | Treatment plan changed | cancel             |
| `patientrequest`        | Patient request        | cancel             |
| `financialconstraints`  | Financial constraints  | cancel             |
| `alternativetreatment`  | Alternative treatment  | cancel             |
| `duplicateclaim`        | Duplicate claim        | cancel             |
| `administrativeerror`   | Administrative error   | cancel             |
| `other`                 | Other                  | cancel             |
| `claimrejected`         | Claim rejected         | reprocess          |
| `partialpayment`        | Partial payment        | reprocess, release |
| `erroneousclaim`        | Erroneous claim        | reprocess          |
| `referred`              | Referred               | reprocess          |
| `erroneousregistration` | Erroneous registration | reprocess          |
| `wrongdiagnosis`        | Wrong diagnosis        | reprocess          |
| `tatquery`              | Turnaround alert       | communication      |
| `grievance`             | Grievance              | communication      |
| `walletupdate`          | Wallet update          | communication      |
| `policychange`          | Policy change          | communication      |
| `additionalinfo`        | Additional information | communication      |
| `claimArbitration`      | Claim arbitration      | communication      |

### Task input types and output values

System `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-input-type-code`.

| Code               | Meaning              | Notes  |
| ------------------ | -------------------- | ------ |
| `PayerId`          | Payer                | input  |
| `ProviderId`       | Provider             | input  |
| `PolicyNumber`     | Policy               | input  |
| `ProductNumber`    | Product              | input  |
| `ClaimNumber`      | Case number          | input  |
| `IntimationNumber` | Intimation number    | input  |
| `FromDate`         | Search window start  | input  |
| `ToDate`           | Search window end    | input  |
| `FinanceYear`      | Financial year       | input  |
| `ServiceCode`      | Benefit or service   | input  |
| `paymentack`       | Payment acknowledged | output |
| `claimcancelled`   | Claim cancelled      | output |
| `claimreinitiated` | Claim reinitiated    | output |
| `claimsuspended`   | Claim suspended      | output |
| `taskak`           | Task acknowledged    | output |
| `taskdelivered`    | Task delivered       | output |

### Money types on a reconciliation

| Code             | Meaning                | Notes |
| ---------------- | ---------------------- | ----- |
| `approvedamount` | Approved amount        |       |
| `claimedamount`  | Claimed amount         |       |
| `tds`            | Tax deducted at source |       |
| `servicetax`     | Service tax            |       |
| `advance`        | Advance                |       |
| `recovered`      | Recovered              |       |
| `penality`       | Penalty, spelled so    |       |
| `Payment`        | The net line           |       |

### Deduction reasons

| Code                       | Meaning                  | Notes |
| -------------------------- | ------------------------ | ----- |
| `Non-CoveredService`       | Service not covered      |       |
| `ExceededCoverageLimit`    | Coverage limit exceeded  |       |
| `DuplicateClaim`           | Duplicate claim          |       |
| `Coordination-of-Benefits` | Coordination of benefits |       |
| `IncompleteDocumentation`  | Incomplete documentation |       |
| `PolicyDeductible`         | Policy deductible        |       |
| `Co-Payment`               | Co-payment               |       |
| `FraudulentClaim`          | Fraudulent claim         |       |
| `MedicalNecessity`         | Medical necessity        |       |
| `BenefitLimitReached`      | Benefit limit reached    |       |
| `MissedFilingDeadline`     | Missed filing deadline   |       |
| `PaymentAlreadyMade`       | Payment already made     |       |

### Claim error codes

Adjudication reasons a payer gives on a claim, from the value-set sheet of the requests-and-responses workbook. Meanings are as that sheet gives them, spelling included. `ClaimError-1` is a deduction and sits among the deduction reasons there. `ClaimError-16` to `ClaimError-27` repeat earlier texts, as noted.

| Code            | Meaning                                                                                                                     | Notes                   |
| --------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `ClaimError-1`  | There is an error in the claim submission, leading to a deduction until the correct information is provided.                |                         |
| `ClaimError-2`  | Claim has been rejected due to less than 24 hours of hospitalization                                                        |                         |
| `ClaimError-3`  | Claim has been rejected as the Package is Reserved to Public Hospital                                                       |                         |
| `ClaimError-4`  | Claim has been closed due to Incomplete submission of documents by hospital after multiple queries                          |                         |
| `ClaimError-5`  | Claim has been rejected as there was misrepresentation of bed category booked                                               |                         |
| `ClaimError-6`  | Claim has been rejected due to Outside Scope of cover (Exclusions as per scheme)                                            |                         |
| `ClaimError-7`  | Claim has been rejected as the claim was found be False/Fraudulent                                                          |                         |
| `ClaimError-8`  | Claim has been rejected due to Mismatch of package and disease/diagnosis/treatment                                          |                         |
| `ClaimError-9`  | Claim has been rejected due to Hospital not empanelled for this speciality                                                  |                         |
| `ClaimError-10` | Claim has been closed due to non submission of the documents                                                                |                         |
| `ClaimError-11` | Claim rejected as the treatment provided does not support the blocked package, request you to book a fresh relevant package |                         |
| `ClaimError-12` | Claim has been closed as the photo of the operative site is not available                                                   |                         |
| `ClaimError-13` | Claim has been rejected due to apparent manipulation in medical record                                                      |                         |
| `ClaimError-14` | Claim has been rejected as the hospital expenses have been paid by patient                                                  |                         |
| `ClaimError-15` | Claim has been closed due Missing Pre-Auth patient photo/post operative photo/After discharge photo                         |                         |
| `ClaimError-16` | Claim has been rejected due to less tha 24 hours of hospitalization                                                         | Same as `ClaimError-2`  |
| `ClaimError-17` | Claim has been closed as Referral Letter Mandatory for Package Selected has not been provided                               |                         |
| `ClaimError-18` | Claim has been rejected as the need for hospitalization was not justified based on the availabe documents                   |                         |
| `ClaimError-19` | Claim has been rejected as the Package is Reserved to Public Hospital                                                       | Same as `ClaimError-3`  |
| `ClaimError-20` | Claim has been closed due to Incomplete submission of documents by hospital after multiple queries                          | Same as `ClaimError-4`  |
| `ClaimError-21` | Claim has been rejected as there was misrepresentation of bed category booked                                               | Same as `ClaimError-5`  |
| `ClaimError-22` | Claim has been rejected due to Outside Scope of cover (Exclusions as per scheme)                                            | Same as `ClaimError-6`  |
| `ClaimError-23` | Claim has been rejected as the claim was found be False/Fraudulent                                                          | Same as `ClaimError-7`  |
| `ClaimError-24` | Claim has been rejected due to Mismatch of package and disease/diagnosis/treatment                                          | Same as `ClaimError-8`  |
| `ClaimError-25` | Claim has been rejected due to Hospital not empanelled for this speciality                                                  | Same as `ClaimError-9`  |
| `ClaimError-26` | Claim has been closed due to non submission of the documents                                                                | Same as `ClaimError-10` |
| `ClaimError-27` | Claim rejected as the treatment provided does not support the blocked package, request you to book a fresh relevant package | Same as `ClaimError-11` |
| `ClaimError-28` | Others                                                                                                                      |                         |

### Preauthorisation error codes

Adjudication reasons a payer gives on a preauthorisation, from the same sheet, meanings as it gives them. No `PreauthError-14` is defined: the list runs to 13, then 15.

| Code              | Meaning                                                                                          | Notes                    |
| ----------------- | ------------------------------------------------------------------------------------------------ | ------------------------ |
| `PreauthError-1`  | Pre-Auth has been rejected as the diagnosis is outside Scope of cover (Exclusions as per scheme) |                          |
| `PreauthError-2`  | Pre-auth has been rejected due to delay in raising enhancement requests                          |                          |
| `PreauthError-3`  | Pre-Auth has been rejected as it was found to be False/Fraudulent                                |                          |
| `PreauthError-4`  | Pre-Auth has been closed due to delay in preauth Intimation (as per state guidelines)            |                          |
| `PreauthError-5`  | Pre-Auth has been rejected as the Hospital is not empanelled for this speciality                 |                          |
| `PreauthError-6`  | Pre- Auth has been rejected due to mismatch in dialysis records                                  |                          |
| `PreauthError-7`  | Enhancement request rejected as the medical necessity of enhancement request not met             |                          |
| `PreauthError-8`  | Pre-Auth rejected as the Medical necessity of ICU bed category not met                           |                          |
| `PreauthError-9`  | Pre-Auth has been rejected as the package selected is reserved for public hospital               |                          |
| `PreauthError-10` | Pre-Auth has been closed due to non submision of mandatory document as per STG                   |                          |
| `PreauthError-11` | Pre-Auth has been rejected as the Surgery was Done Before Pre auth Approval                      |                          |
| `PreauthError-12` | Pre-auth enhancement rejected due to missing patient photo to depict bed category                |                          |
| `PreauthError-13` | Pre-Auth has been rejected as the diagnosis is outside Scope of cover (Exclusions as per scheme) | Same as `PreauthError-1` |
| `PreauthError-15` | Others                                                                                           |                          |

## Where the systems are wrong

The code is usually right. The system it is bound to often is not. Match on the code, and take the system from the exchange you are building.

| What                     | The problem                                                                                                                             |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| Package codes            | The same code appears under a payer host, under SNOMED and under two ValueSet URLs, depending on the exchange. None is a SNOMED concept |
| Supporting-info category | Document entries bind `category` to the supporting-info code system rather than the category system; the plan does the reverse          |
| Claim.type               | Binds to a ValueSet URL where a CodeSystem URL belongs                                                                                  |
| Adjudication categories  | Some senders bind them to an HTML documentation page, `https://hl7.org/fhir/R4/valueset-adjudication.html`                              |
| Plan cost types          | Bind to the plan-type system under a `www.` host, with values that are not plan types                                                   |
| Missing systems          | `deductible`, the claim-level status and some package codings carry no `system` at all                                                  |


---

# Communication

The payer's asynchronous channel to the provider: a turnaround alert, a grievance, a policy or wallet change, or a request for documents. The provider acknowledges within thirty seconds, whether or not the issue is resolved.

## The request

Sent on `/v1/communication/request`.

### The bundle

| # | Resource               | Profile                                                                                             |
| - | ---------------------- | --------------------------------------------------------------------------------------------------- |
| 1 | `Task`                 | [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)                                 |
| 2 | `CommunicationRequest` | [CommunicationRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CommunicationRequest.html) |
| 3 | `Claim`                | [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html)                               |
| 4 | `Patient`              | [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)                           |
| 5 | `Organization (ins)`   | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                 |
| 6 | `Organization (prov)`  | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                 |
| 7 | `Practitioner`         | [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html)                 |
| 8 | `Coverage`             | [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)                         |

### Elements

#### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                  | Example                                                                                                        |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `status`                 | `requested`                                                                                                    |
| `intent`                 | `order`                                                                                                        |
| `reasonCode.coding[]`    | `additionalinfo` Additional Information Request in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-reason-code` |
| `code.coding[]`          | `poll` in `http://terminology.hl7.org/CodeSystem/financialtaskcode`                                            |
| `description`            | `Share the pre-operative X-ray and the clinical notes.`                                                        |
| `authoredOn`             | `2026-09-10T23:51:47+05:30`                                                                                    |
| `requester`              | reference `urn:uuid:39cd4b51-bddd-5cc1-a65a-6fa4a2a83cb5`, display `Organization`                              |
| `owner`                  | reference `urn:uuid:84d112ec-041c-57f8-986c-6619ccd8245e`, display `Organization`                              |
| `input[].type.coding[]`  | `include` in `http://terminology.hl7.org/CodeSystem/financialtaskinputtype`                                    |
| `input[].valueReference` | reference `urn:uuid:4b35a6eb-3f99-5d0c-b0c8-5b2f049fdbde`, display `CommunicationRequest`                      |

#### CommunicationRequest

NRCeS profile: [CommunicationRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CommunicationRequest.html).

| Element                 | Example                                                                                                        |
| ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `identifier[]`          | value `NM-26-0SE00002I`                                                                                        |
| `basedOn[]`             | reference `urn:uuid:c1a17d6e-c718-58de-8d3d-fd4c0607d729`, display `Claim-preauth`                             |
| `status`                | `active`                                                                                                       |
| `category[].coding[]`   | `alert` in `http://terminology.hl7.org/CodeSystem/communication-category`                                      |
| `priority`              | `routine`                                                                                                      |
| `payload[]`             | contentString `Share the pre-operative X-ray and the clinical notes.`                                          |
| `authoredOn`            | `2026-09-10T23:51:47+05:30`                                                                                    |
| `requester`             | reference `urn:uuid:39cd4b51-bddd-5cc1-a65a-6fa4a2a83cb5`, display `Organization`                              |
| `recipient[]`           | reference `urn:uuid:84d112ec-041c-57f8-986c-6619ccd8245e`, display `Organization`                              |
| `sender`                | reference `urn:uuid:39cd4b51-bddd-5cc1-a65a-6fa4a2a83cb5`, display `Organization`                              |
| `reasonCode[]`          | text `Share the pre-operative X-ray and the clinical notes.`                                                   |
| `reasonCode[].coding[]` | `additionalinfo` Additional Information Request in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-reason-code` |

The `Claim`, `Patient`, `Organization`, `Practitioner`, `Coverage` entries are shaped as in the chapters that introduce them.

## A notification

Sent on `/v1/communication/request`, workflow N02.

### The bundle

| # | Resource               | Profile                                                                                                                  |
| - | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| 1 | `Task`                 | none declared; NRCeS [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)                                 |
| 2 | `CommunicationRequest` | none declared; NRCeS [CommunicationRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CommunicationRequest.html) |
| 3 | `Organization (pay)`   | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                 |
| 4 | `Organization (prov)`  | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                 |

### Elements

#### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                  | Example                                                                                                               |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `status`                 | `completed`                                                                                                           |
| `intent`                 | `proposal`                                                                                                            |
| `code.coding[]`          | `poll` Poll in `http://terminology.hl7.org/CodeSystem/financialtaskcode`                                              |
| `reasonCode.coding[]`    | `information` Information in `http://terminology.hl7.org/CodeSystem/communication-category`                           |
| `input[].type.coding[]`  | `include` Include in `http://terminology.hl7.org/CodeSystem/financialtaskinputtype`                                   |
| `input[].valueReference` | reference `https://payer.pmajy.nha.gov.in/CommunicationRequest/1a857700-c6f3-49e1-b5d1-049…`, display `Communication` |

#### CommunicationRequest

NRCeS profile: [CommunicationRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CommunicationRequest.html).

| Element               | Example                                                                                       |
| --------------------- | --------------------------------------------------------------------------------------------- |
| `status`              | `completed`                                                                                   |
| `category[].coding[]` | `notification` Notification in `http://terminology.hl7.org/CodeSystem/communication-category` |
| `payload[]`           | contentString `Required Message for the provider`                                             |
| `recipient[]`         | reference `https://payer.nha.gov.in/v1/communication/request/organization/provider/1000003…`  |
| `sender`              | reference `https://payer.nha.gov.in/v1/communication/request/organization/payer/1518@hcx`     |

The `Organization` entries are shaped as in the chapters that introduce them.

## The acknowledgement

Sent on `/v1/communication/on_request`.

### The bundle

| # | Resource               | Profile                                                                                             |
| - | ---------------------- | --------------------------------------------------------------------------------------------------- |
| 1 | `Task`                 | [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)                                 |
| 2 | `Communication`        | [Communication](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Communication.html)               |
| 3 | `CommunicationRequest` | [CommunicationRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CommunicationRequest.html) |
| 4 | `Claim`                | [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html)                               |
| 5 | `Patient`              | [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)                           |
| 6 | `Organization (prov)`  | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                 |
| 7 | `Organization (pay)`   | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                 |
| 8 | `Practitioner`         | [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html)                 |
| 9 | `Coverage`             | [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)                         |

### Elements

#### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                  | Example                                                                                            |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| `authoredOn`             | `2026-03-08T11:01:00+05:30`                                                                        |
| `code.coding[]`          | `deliver` in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-codes`                            |
| `input[].type.coding[]`  | `include` in `http://terminology.hl7.org/CodeSystem/financialtaskinputtype`                        |
| `input[].valueReference` | display `Communication`, reference `urn:uuid:7d9e2a64-3b1f-4f0c-8a5e-6c4b2d9f1e37`                 |
| `intent`                 | `order`                                                                                            |
| `owner`                  | display `Organization`, reference `https://nhcx.abdm.gov.in/payer`                                 |
| `reasonCode.coding[]`    | `additionalinfo` Additional information request in `https://nhcx.abdm.gov.in/communication-reason` |
| `requester`              | display `Organization`, reference `https://nhcx.abdm.gov.in/provider`                              |
| `status`                 | `completed`                                                                                        |

#### Communication

NRCeS profile: [Communication](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Communication.html).

| Element                       | Example                                                                                   |
| ----------------------------- | ----------------------------------------------------------------------------------------- |
| `about[]`                     | display `Claim VB26AA2600001`, reference `https://nhcx.abdm.gov.in/preauth/request`       |
| `basedOn[]`                   | display `CommunicationRequest`, reference `urn:uuid:08f1bb6f-c3f5-4578-b5e8-c042764e2477` |
| `category[].coding[]`         | `notification` in `http://terminology.hl7.org/CodeSystem/communication-category`          |
| `identifier[]`                | value `4524657454`                                                                        |
| `payload[]`                   | contentString `The angiography report is attached.`                                       |
| `payload[].contentAttachment` | contentType `application/pdf`, title `Angiography report`                                 |
| `payload[].extension[]`       | url `<participant-defined>`, valueString `DIA`                                            |
| `priority`                    | `routine`                                                                                 |
| `recipient[]`                 | display `Organization`, reference `https://nhcx.abdm.gov.in/payer`                        |
| `sender`                      | display `Organization`, reference `https://nhcx.abdm.gov.in/provider`                     |
| `status`                      | `completed`                                                                               |

The `CommunicationRequest`, `Claim`, `Patient`, `Organization`, `Practitioner`, `Coverage` entries are shaped as in the chapters that introduce them.

## Rules

### The push pattern

`Task.code` `poll` with an input of type `include` referencing the resource being delivered, a `CommunicationRequest` from the payer. `intent` is `order` on a request and `proposal` on a notification. Resolve the reference and read its type.

### Switch on the reason

`Task.reasonCode` from `ndhm-reason-code`: `tatquery`, `grievance`, `walletupdate`, `policychange`, `additionalinfo`, `claimArbitration`. Accept the misspelling `claimArbitartion` on receipt.

### Notifications

A notification carries its reason under the communication-category system, such as `information`, and a `CommunicationRequest` with category `notification` and the message in `payload`.

### Category, priority, topic

`category` `alert`, `reminder`, `notification`, `instruction` or `questionnaire`; `priority` `routine`, `urgent`, `asap` or `stat`; `topic` `progress-update` for anything about a live case.

### completed is the event

`Task.status` and `Communication.status` read `completed` when the message is delivered. Do not close a case on them.

### The acknowledgement

A `Task` coded `deliver`, `completed`, whose `include` input references a `Communication` with `basedOn` naming the request. Same correlation id. Take each organisation's role from `Organization.type`, not from the identifier type.

## PMJAY

The generic bundle above is what every payer takes, IRDAI-regulated insurers and TPAs included. PMJAY takes it with the changes and requirements below.

### What changes in the bundle

PMJAY sends this exchange in the generic shape.

### What PMJAY specifies

- PMJAY does not use this channel for queries. A PMJAY `CommunicationRequest` is a notification: a turnaround alert, a grievance, a wallet or policy change, or an arbitration intimation.

### What PMJAY requires

- Acknowledge within thirty seconds with the same Task bundle and `Task.status` `completed`, and leave the case's status alone.

## Use cases, APIs and data elements

### C6 Raise a communication (payer)

A message about a case, typed by its reason code: additionalinfo, tatquery for a turnaround breach, grievance, walletupdate, policychange, claimArbitration. A generic or IRDAI payer raises its document queries here, as a CommunicationRequest task bundle carrying 24, 241 or 27, and takes the answer as a Communication task bundle on on\_request echoing the correlation id and workflow id. PMJAY does not use it for queries; its query is the ClaimResponse on the case's own thread.

|                    |                                                                                                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/communication/request` [`apis/07-communication/v1-communication-request.bru`](/docs/nhcx/v1/api/communication/endpoints/communication-v1-communication-request)          |
| **Callback**       | `/v1/communication/on_request` [`apis/07-communication/v1-communication-on-request.bru`](/docs/nhcx/v1/api/communication/endpoints/communication-v1-communication-on-request) |
| **Workflow**       | 24, 241, 27 for a generic payer's queries; N02 and the intimation codes for the rest                                                                                          |
| **Carries JWE**    | yes                                                                                                                                                                           |
| **Focal resource** | `CommunicationRequest / Task`                                                                                                                                                 |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1518@hcx`          |
| `x-hcx-recipient_code` | `1000004446@hcx`    |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `15`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |

**Workflow codes**

| Code  | Name                               | Authored by       | `x-hcx-status`                                   | Means                                                                               |
| ----- | ---------------------------------- | ----------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `24`  | Preauth Request Queried            | payer             | `request.initiated`                              | Payer needs more information - respond using workflow 19                            |
| `241` | Enhancement Request Queried        | payer             | `request.initiated`                              | Enhancement request queried by payer                                                |
| `27`  | Claim Request Queried              | payer             | `request.initiated`, `response.partial/complete` | Final claim queried - payer needs additional documents; under PMJAY answer with 161 |
| `N02` | Notifications Intended To Provider | status sheet only | `request.initiated`                              |                                                                                     |

**Data elements**

| Element      | Label           | Group | Type     | Card.  | FHIR path                                       | Example                                        | Notes |
| ------------ | --------------- | ----- | -------- | ------ | ----------------------------------------------- | ---------------------------------------------- | ----- |
| `taskReason` | Query Reason    | Query | `code`   | `1..1` | `Task.reasonCode.coding[0].code`                | `additionalinfo`                               |       |
| `queryText`  | Query Questions | Query | `string` | `1..1` | `CommunicationRequest.payload[0].contentString` | `Please attach pre-operative ultrasound scan.` |       |

NRCeS profiles: [CommunicationRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CommunicationRequest.html), [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

### B4 Respond to a communication (provider)

Acknowledge or answer a message the payer sent about a case. A generic or IRDAI payer raises its query here, as a CommunicationRequest task bundle carrying 24, 241 or 27; the answer is a Communication task bundle on on\_request that echoes the request's correlation id and workflow id. The payer's reason code says what kind of message it was.

|                    |                                                                                                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/communication/on_request` [`apis/07-communication/v1-communication-on-request.bru`](/docs/nhcx/v1/api/communication/endpoints/communication-v1-communication-on-request) |
| **Callback**       | `/v1/communication/request` [`apis/07-communication/v1-communication-request.bru`](/docs/nhcx/v1/api/communication/endpoints/communication-v1-communication-request)          |
| **Workflow**       | 24, 241 or 27, echoed from the payer's request                                                                                                                                |
| **Carries JWE**    | yes                                                                                                                                                                           |
| **Focal resource** | `Communication / Task`                                                                                                                                                        |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `15`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `response.complete` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |

**Workflow codes**

| Code  | Name                        | Authored by | `x-hcx-status`                                   | Means                                                                               |
| ----- | --------------------------- | ----------- | ------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `24`  | Preauth Request Queried     | payer       | `request.initiated`                              | Payer needs more information - respond using workflow 19                            |
| `241` | Enhancement Request Queried | payer       | `request.initiated`                              | Enhancement request queried by payer                                                |
| `27`  | Claim Request Queried       | payer       | `request.initiated`, `response.partial/complete` | Final claim queried - payer needs additional documents; under PMJAY answer with 161 |

**Data elements**

| Element           | Label                    | Group   | Type           | Card.  | FHIR path                                         | Example                                 | Notes |
| ----------------- | ------------------------ | ------- | -------------- | ------ | ------------------------------------------------- | --------------------------------------- | ----- |
| `communicationId` | Communication Identifier | Case    | `string`       | `1..1` | `Communication.identifier[0].value`               | `COMM-RESP-001`                         |       |
| `queryRequestId`  | Original Query Reference | Case    | `reference`    | `1..1` | `Communication.basedOn[0].reference`              | `Task/task-comm-req-1`                  |       |
| `replyText`       | Clarification Text       | Payload | `string`       | `0..1` | `Communication.payload[0].contentString`          | `Platelet count attached as requested.` |       |
| `attachmentData`  | Attached Document Base64 | Payload | `base64Binary` | `0..*` | `Communication.payload[0].contentAttachment.data` | `JVBERi0xLjQK...`                       |       |

NRCeS profiles: [Communication](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Communication.html).


---

# Coverage eligibility request

The provider asks the payer whether a policy is live, what it covers, and what a package will need. One `CoverageEligibilityRequest` carries all of that, and `purpose` decides which question is asked. It is the first exchange in a case, sent at registration or before treatment planning.

Sent on `/v1/coverageeligibility/check`, answered on `/v1/coverageeligibility/on_check`.

## The four purposes

One builder, with `purpose` switched. The purposes differ in what they send and what the payer must return.

| Variant           | What it asks                                                                       | purpose             | item                                                                                     |
| ----------------- | ---------------------------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------- |
| Discovery         | Which policies does this person hold? Searches by ABHA or demographic identifiers. | `discovery`         | none                                                                                     |
| Validation        | Is the policy in force, and what is left in the wallet?                            | `validation`        | none                                                                                     |
| Benefits          | Is this package covered for this beneficiary?                                      | `benefits`          | `MG004C` Dengue shock syndrome (Dengue fever) in `https://nhcx.abdm.gov.in/product-code` |
| Auth-requirements | What must a preauthorisation carry for this package?                               | `auth-requirements` | `MG004C` Dengue shock syndrome (Dengue fever) in `https://nhcx.abdm.gov.in/product-code` |

## The bundle

| # | Resource                     | Profile                                                                                                         |
| - | ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
| 1 | `CoverageEligibilityRequest` | [CoverageEligibilityRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CoverageEligibilityRequest.html) |
| 2 | `Patient`                    | [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)                                       |
| 3 | `Organization (prov)`        | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                             |
| 4 | `Organization (pay)`         | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                             |
| 5 | `Location`                   | none declared; NRCeS [Location](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Location.html)                |
| 6 | `Coverage`                   | [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)                                     |
| 7 | `PractitionerRole`           | [PractitionerRole](https://nrces.in/ndhm/fhir/r4/StructureDefinition-PractitionerRole.html)                     |

## Elements

### CoverageEligibilityRequest

NRCeS profile: [CoverageEligibilityRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CoverageEligibilityRequest.html).

| Element                            | Example                                                                                       |
| ---------------------------------- | --------------------------------------------------------------------------------------------- |
| `identifier[]`                     | system `https://nhcx.abdm.gov.in`                                                             |
| `status`                           | `active`                                                                                      |
| `priority.coding[]`                | `normal` Normal in `http://terminology.hl7.org/CodeSystem/processpriority`                    |
| `purpose`                          | `auth-requirements`                                                                           |
| `patient`                          | reference `https://nhcx.abdm.gov.in/patient`                                                  |
| `created`                          | `2026-09-10T23:53:57+05:30`                                                                   |
| `enterer`                          | reference `https://nhcx.abdm.gov.in/practitioner-role`                                        |
| `provider`                         | reference `https://nhcx.abdm.gov.in/provider`                                                 |
| `insurer`                          | reference `https://nhcx.abdm.gov.in/payer`                                                    |
| `facility`                         | reference `https://nhcx.abdm.gov.in/location`                                                 |
| `insurance[]`                      | focal `true`                                                                                  |
| `insurance[].coverage`             | reference `https://nhcx.abdm.gov.in/coverage`                                                 |
| `item[].category.coding[]`         | `Surgical` Surgical in `https://nhcx.abdm.gov.in/category-code`                               |
| `item[].productOrService.coding[]` | `PROC-KNEE-01` Total Knee Replacement (Unilateral) in `https://nhcx.abdm.gov.in/product-code` |
| `item[].quantity`                  | value `1`                                                                                     |

### Patient

NRCeS profile: [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html).

| Element                      | Example                                                                                                                      |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `identifier[]`               | value `MRAV1985001`                                                                                                          |
| `identifier[].type.coding[]` | `PMJAY` Pradhan Mantri Jan Aarogya Yojana (PMJAY) ID in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code` |
|                              | `MB` Member Number in `http://terminology.hl7.org/CodeSystem/v2-0203`                                                        |

### Organization (prov)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `identifier[]`               | system `https://nhcx.abdm.gov.in`, value `IN1910000151`                                 |
| `identifier[].type.coding[]` | `NPI` National provider identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`   |
| `type[].coding[]`            | `prov` Healthcare Provider in `http://terminology.hl7.org/CodeSystem/organization-type` |
| `name`                       | `XYZ Multispeciality Hospital`                                                          |

### Organization (pay)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                               |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `identifier[]`               | system `https://nhcx.abdm.gov.in`, value `1000004805`                                                 |
| `identifier[].type.coding[]` | `NIIP` National Insurance Payor Identifier (Payor) in `http://terminology.hl7.org/CodeSystem/v2-0203` |
| `type[].coding[]`            | `pay` Payer in `http://terminology.hl7.org/CodeSystem/organization-type`                              |
| `name`                       | `Sandbox Payer`                                                                                       |

### Location

NRCeS profile: [Location](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Location.html).

| Element                | Example                                       |
| ---------------------- | --------------------------------------------- |
| `name`                 | `XYZ Multispeciality Hospital`                |
| `managingOrganization` | reference `https://nhcx.abdm.gov.in/provider` |

### Coverage

NRCeS profile: [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html).

| Element                      | Example                                                                                  |
| ---------------------------- | ---------------------------------------------------------------------------------------- |
| `status`                     | `active`                                                                                 |
| `type.coding[]`              | `HIP` health insurance plan policy in `http://terminology.hl7.org/CodeSystem/v3-ActCode` |
| `identifier[]`               | value `POL7UMU001`                                                                       |
| `identifier[].type.coding[]` | `NH` National Health Plan Identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`  |
| `subscriber`                 | reference `https://nhcx.abdm.gov.in/patient`                                             |
| `subscriberId`               | `MRAV1985001`                                                                            |
| `beneficiary`                | reference `https://nhcx.abdm.gov.in/patient`                                             |
| `relationship.coding[]`      | `self` in `http://terminology.hl7.org/CodeSystem/subscriber-relationship`                |
| `payor[]`                    | reference `https://nhcx.abdm.gov.in/payer`                                               |

### PractitionerRole

NRCeS profile: [PractitionerRole](https://nrces.in/ndhm/fhir/r4/StructureDefinition-PractitionerRole.html).

| Element           | Example                                                    |
| ----------------- | ---------------------------------------------------------- |
| `code[].coding[]` | `307988006` Medical technician in `http://snomed.info/sct` |

## Rules

### One purpose per request

`purpose[]` carries one of `discovery`, `validation`, `benefits`, `auth-requirements`.

### Items make a question answerable

`item[]` is what makes `benefits` and `auth-requirements` answerable. `validation` does not need it. `discovery` omits `item[]` and `Coverage`.

### Date of service

`servicedDate` is the date of service, not the date of asking.

### The Coverage you send is a stub

It names the policy you mean, not its terms. Take the term and the class from the payer's `Coverage` in the response.

### Parties by reference

`provider` and `insurer` reference `Organization` entries typed `prov` and `pay`, identified by `NPI` and `NIIP`. `facility` references a `Location` the provider manages, and `enterer` a `PractitionerRole`.

## PMJAY

The generic bundle above is what every payer takes, IRDAI-regulated insurers and TPAs included. PMJAY takes it with the changes and requirements below.

### What changes in the bundle

#### Elements PMJAY adds

| Element                                                 | Example                  |
| ------------------------------------------------------- | ------------------------ |
| `CoverageEligibilityRequest.item[].modifier[].coding[]` | `STRAT006a` Routine Ward |

### What PMJAY specifies

- `item.category` is the package master's specialty code, such as `MG`, and `item.productOrService` the master's package code and display.
- The `Coverage` carries the scheme policy code typed `NH`, of the form `PMJAY/<state>/S/G`, from the policy lookup.
- Validation after registration returns the wallet; benefits and auth-requirements before a preauthorisation return what the package needs attached, including the consent questionnaire when there is no biometric token.

### What PMJAY requires

- The ward tier rides as `item.modifier` when the package allows one.
- Register the patient only after coverage is validated, and validate again every time treatment is added.

## Use cases, APIs and data elements

### B1 Check coverage eligibility (provider)

Is the policy in force, what is left in the wallet, and what must be attached. One endpoint, four purposes: discovery, validation, benefits, auth-requirements.

|                    |                                                                                                                                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/coverageeligibility/check` [`apis/02-eligibility/v1-coverageeligibility-check.bru`](/docs/nhcx/v1/api/eligibility/endpoints/eligibility-v1-coverageeligibility-check)          |
| **Callback**       | `/v1/coverageeligibility/on_check` [`apis/02-eligibility/v1-coverageeligibility-on-check.bru`](/docs/nhcx/v1/api/eligibility/endpoints/eligibility-v1-coverageeligibility-on-check) |
| **Workflow**       | none; sits beside registration 10 and admission 11                                                                                                                                  |
| **Carries JWE**    | yes                                                                                                                                                                                 |
| **Focal resource** | `CoverageEligibilityRequest`                                                                                                                                                        |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `11`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |

**Workflow codes**

| Code | Name               | Authored by | `x-hcx-status`      | Means                        |
| ---- | ------------------ | ----------- | ------------------- | ---------------------------- |
| `10` | Patient Registered | provider    | `request.initiated` | Patient registered in system |
| `11` | Patient Admitted   | provider    | `request.initiated` | Patient admitted to hospital |

**Data elements**

| Element            | Label                          | Group       | Type     | Card.  | FHIR path                                                                       | Example                             | Notes                                                        |
| ------------------ | ------------------------------ | ----------- | -------- | ------ | ------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------ |
| `purpose`          | Eligibility Purpose            | Case        | `code`   | `1..1` | `CoverageEligibilityRequest.purpose[0]`                                         | `auth-requirements`                 | code system `http://hl7.org/fhir/eligibilityrequest-purpose` |
| `caseNumber`       | Provider Reference             | Case        | `string` | `1..1` | `CoverageEligibilityRequest.identifier[0].value`                                | `PA0000000001`                      | also at `Bundle.id`                                          |
| `servicedDate`     | Date of Service                | Case        | `date`   | `1..1` | `CoverageEligibilityRequest.servicedDate`                                       | `2026-02-26`                        |                                                              |
| `patientName`      | Patient Full Name              | Beneficiary | `string` | `1..1` | `Patient.name[0].text`                                                          | `Ramesh Chandra Sharma`             |                                                              |
| `memberId`         | Scheme / Insurer Member ID     | Beneficiary | `string` | `1..1` | `Patient.identifier[type=PMJAY].value`                                          | `PMJAY-HP-2024-998811`              | also at `Coverage.subscriberId`                              |
| `abhaNumber`       | ABHA Number                    | Beneficiary | `string` | `0..1` | `Patient.identifier[type=ABHA].value`                                           | `91234567890123`                    |                                                              |
| `gender`           | Gender                         | Beneficiary | `code`   | `1..1` | `Patient.gender`                                                                | `male`                              | code system `http://hl7.org/fhir/administrative-gender`      |
| `birthDate`        | Date of Birth                  | Beneficiary | `date`   | `1..1` | `Patient.birthDate`                                                             | `1982-06-15`                        |                                                              |
| `patientPhone`     | Mobile Phone                   | Beneficiary | `string` | `0..1` | `Patient.telecom[system=phone].value`                                           | `9876543210`                        |                                                              |
| `policyNumber`     | Policy Number                  | Coverage    | `string` | `1..1` | `Coverage.identifier[0].value`                                                  | `PMJAY/HP/S/G`                      |                                                              |
| `facilityId`       | Hospital Facility ID (HFR/NPI) | Provider    | `string` | `1..1` | `Organization[type=prov].identifier[system=https://facility.abdm.gov.in].value` | `IN1910000151`                      |                                                              |
| `providerName`     | Hospital Name                  | Provider    | `string` | `1..1` | `Organization[type=prov].name`                                                  | `Apex Multispeciality Hospital`     |                                                              |
| `payerId`          | Payer Identifier (NIIP)        | Payer       | `string` | `1..1` | `Organization[type=pay].identifier[system=https://irdai.gov.in].value`          | `1000003538`                        |                                                              |
| `payerName`        | Payer Name                     | Payer       | `string` | `1..1` | `Organization[type=pay].name`                                                   | `National Health Authority - PMJAY` |                                                              |
| `productOrService` | Package Code                   | Item        | `string` | `0..*` | `CoverageEligibilityRequest.item[].productOrService.coding[0].code`             | `MG004A`                            |                                                              |

NRCeS profiles: [CoverageEligibilityRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CoverageEligibilityRequest.html), [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html), [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html), [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

### D3 Check coverage eligibility (pmjay)

Validation after registration returns the wallet, one benefit entry per wallet with allowed and used. Benefits and auth-requirements before a pre-authorisation return what the package needs attached. Register only after coverage is validated, and validate again every time treatment is added.

|                    |                                                                                                                                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/coverageeligibility/check` [`apis/02-eligibility/v1-coverageeligibility-check.bru`](/docs/nhcx/v1/api/eligibility/endpoints/eligibility-v1-coverageeligibility-check)          |
| **Callback**       | `/v1/coverageeligibility/on_check` [`apis/02-eligibility/v1-coverageeligibility-on-check.bru`](/docs/nhcx/v1/api/eligibility/endpoints/eligibility-v1-coverageeligibility-on-check) |
| **Workflow**       | none (or 5 under PMJAY)                                                                                                                                                             |
| **Carries JWE**    | yes                                                                                                                                                                                 |
| **Focal resource** | `CoverageEligibilityRequest`                                                                                                                                                        |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `11`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |

**Data elements**

| Element    | Label           | Group       | Type     | Card.  | FHIR path                               | Example                | Notes |
| ---------- | --------------- | ----------- | -------- | ------ | --------------------------------------- | ---------------------- | ----- |
| `memberId` | PMJAY Family ID | Beneficiary | `string` | `1..1` | `Patient.identifier[type=PMJAY].value`  | `PMJAY-HP-2024-998811` |       |
| `purpose`  | Purpose         | Case        | `code`   | `1..1` | `CoverageEligibilityRequest.purpose[0]` | `validation`           |       |

NRCeS profiles: [CoverageEligibilityRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CoverageEligibilityRequest.html), [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html).


---

# Coverage eligibility response

The payer's answer on `on_check`. It says whether the coverage is in force, what is left in the wallet, and which items need authorisation and which documents.

Sent on `/v1/coverageeligibility/on_check`.

## The bundle

| # | Resource                      | Profile                                                                                                           |
| - | ----------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| 1 | `CoverageEligibilityResponse` | [CoverageEligibilityResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CoverageEligibilityResponse.html) |
| 2 | `Patient`                     | [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)                                         |
| 3 | `Coverage`                    | [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)                                       |
| 4 | `CoverageEligibilityRequest`  | [CoverageEligibilityRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CoverageEligibilityRequest.html)   |
| 5 | `Organization (ins)`          | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                               |

## Elements

### CoverageEligibilityResponse

NRCeS profile: [CoverageEligibilityResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CoverageEligibilityResponse.html).

| Element                                                 | Example                                                                                         |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `identifier[]`                                          | system `<participant-defined>`, value `SUB-00001`                                               |
| `status`                                                | `active`                                                                                        |
| `purpose`                                               | `auth-requirements`                                                                             |
| `patient`                                               | reference `urn:uuid:89aac2db-25ae-5b55-90a7-886c6be48ca7`, display `Ravi Kumar`                 |
| `created`                                               | `2026-09-10`                                                                                    |
| `request`                                               | reference `urn:uuid:4955a87f-deb4-59e6-b795-100a2d705c98`, display `CoverageEligibilityRequest` |
| `outcome`                                               | `complete`                                                                                      |
| `disposition`                                           | `Policy is in force until 2026-12-31. INR 5000 of cover remains. All 1 requested…`              |
| `insurer`                                               | reference `urn:uuid:39cd4b51-bddd-5cc1-a65a-6fa4a2a83cb5`, display `Sandbox Payer`              |
| `insurance[]`                                           | inforce `true`                                                                                  |
| `insurance[].coverage`                                  | reference `urn:uuid:966d4b2b-591b-50b6-bbbb-d504d3c6897f`, display `Sandbox Default Policy`     |
| `insurance[].benefitPeriod`                             | start `2026-01-01`, end `2026-12-31`                                                            |
| `insurance[].item[]`                                    | authorizationRequired `true`                                                                    |
| `insurance[].item[].productOrService`                   | text `Total Knee Replacement (Unilateral)`                                                      |
| `insurance[].item[].productOrService.coding[]`          | `PROC-KNEE-01` Total Knee Replacement (Unilateral) in `<participant-defined>`                   |
|                                                         | `737481003` Total Knee Replacement (Unilateral) in `http://snomed.info/sct`                     |
|                                                         | `0SRC0JZ` Total Knee Replacement (Unilateral) in `http://www.cms.gov/Medicare/Coding/ICD10`     |
| `insurance[].item[].benefit[].type.coding[]`            | `benefit` Benefit in `http://terminology.hl7.org/CodeSystem/benefit-type`                       |
| `insurance[].item[].benefit[].allowedMoney`             | value `150000`, currency `INR`                                                                  |
| `insurance[].item[].authorizationSupporting[]`          | text \`Type: pre                                                                                |
| Procedure Code: PROC-KNEE-01\`                          |                                                                                                 |
|                                                         | text \`Type: post                                                                               |
| Procedure Code: PROC-KNEE-01\`                          |                                                                                                 |
|                                                         | text `fullUrl: <participant-defined>`                                                           |
| `insurance[].item[].authorizationSupporting[].coding[]` | `POI` Proof of Identity (Aadhaar / Passport / Voter ID) in `<participant-defined>`              |
|                                                         | `CER` Medical Certificate / Doctor Referral in `<participant-defined>`                          |
|                                                         | `RAD` Radiology / X-Ray / CT / MRI Scan Reports in `<participant-defined>`                      |
|                                                         | and 7 more                                                                                      |

### Patient

NRCeS profile: [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html).

| Element                      | Example                                                                                                                 |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `identifier[]`               | system `<participant-defined>`, value `MRAV1985001`                                                                     |
|                              | system `https://healthid.ndhm.gov.in`, value `91-1234-1234-1234`                                                        |
| `identifier[].type.coding[]` | `ABHA` Ayushman Bharat Health Account (ABHA) ID in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code` |
| `name[]`                     | text `Ravi Kumar`                                                                                                       |
| `telecom[]`                  | system `phone`, value `9876543210`, use `mobile`                                                                        |
| `gender`                     | `male`                                                                                                                  |
| `birthDate`                  | `1985-06-15`                                                                                                            |

### Coverage

NRCeS profile: [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html).

| Element                 | Example                                                                                  |
| ----------------------- | ---------------------------------------------------------------------------------------- |
| `identifier[]`          | system `<participant-defined>`, value `SUB-00001`                                        |
| `status`                | `active`                                                                                 |
| `type.coding[]`         | `HIP` health insurance plan policy in `http://terminology.hl7.org/CodeSystem/v3-ActCode` |
| `subscriber`            | reference `urn:uuid:89aac2db-25ae-5b55-90a7-886c6be48ca7`, display `Ravi Kumar`          |
| `subscriberId`          | `MRAV1985001`                                                                            |
| `beneficiary`           | reference `urn:uuid:89aac2db-25ae-5b55-90a7-886c6be48ca7`, display `Ravi Kumar`          |
| `relationship.coding[]` | `self` Self in `http://terminology.hl7.org/CodeSystem/subscriber-relationship`           |
| `period`                | start `2026-01-01`, end `2026-12-31`                                                     |
| `payor[]`               | reference `urn:uuid:39cd4b51-bddd-5cc1-a65a-6fa4a2a83cb5`, display `Sandbox Payer`       |
| `class[]`               | value `POL7UMU002`, name `Sandbox Default Policy`                                        |
| `class[].type.coding[]` | `plan` Plan in `http://terminology.hl7.org/CodeSystem/coverage-class`                    |

### CoverageEligibilityRequest

NRCeS profile: [CoverageEligibilityRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CoverageEligibilityRequest.html).

| Element                | Example                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------- |
| `identifier[]`         | system `<participant-defined>`, value `4955a87f-deb4-59e6-b795-100a2d705c98`                |
| `status`               | `active`                                                                                    |
| `priority.coding[]`    | `normal` Normal in `http://terminology.hl7.org/CodeSystem/processpriority`                  |
| `purpose`              | `auth-requirements`                                                                         |
| `patient`              | reference `urn:uuid:89aac2db-25ae-5b55-90a7-886c6be48ca7`, display `Ravi Kumar`             |
| `created`              | `2026-09-10T23:53:59+05:30`                                                                 |
| `insurer`              | reference `urn:uuid:39cd4b51-bddd-5cc1-a65a-6fa4a2a83cb5`, display `Sandbox Payer`          |
| `insurance[]`          | focal `true`                                                                                |
| `insurance[].coverage` | reference `urn:uuid:966d4b2b-591b-50b6-bbbb-d504d3c6897f`, display `Sandbox Default Policy` |

### Organization (ins)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element           | Example                                                                              |
| ----------------- | ------------------------------------------------------------------------------------ |
| `type[].coding[]` | `ins` Insurance Company in `http://terminology.hl7.org/CodeSystem/organization-type` |
| `name`            | `Sandbox Payer`                                                                      |
| `address[]`       | city `Bengaluru`, state `Karnataka`, country `India`                                 |

## Rules

### Read the answer in three places

`outcome`, `insurance[].inforce` and `insurance[].item[]`. `disposition` is prose for a human.

### Match to the request by reference

Use `CoverageEligibilityResponse.request.reference`, never a resource id, to join the answer to what you sent.

### Items come back in your own codes

`insurance[].item[].productOrService` carries the package code you sent, for example `MG004A`, as NHA's published PMJAY bundles show. Match items by that code. The numbers in the handbook's response table (100005, 100478, 100063, 100012) are not item codes; in the published bundles they are questionnaire, document-requirement and question identifiers.

### Index entries by fullUrl

A response can carry more than one `Patient` or `Organization`. Index by `fullUrl`, not by resource type.

### Money

`allowedMoney` is the balance remaining and `usedMoney` the amount used, not the sum insured. There is one benefit per wallet; read them all.

### Build for the fuller form

`benefit[]` with `Procedure`, `Investigation` and `Stratification` types for benefits, and `authorizationSupporting[]` with the mandatory document codes for auth-requirements. Tolerate a leaner answer.

### Documents by stage

`authorizationSupporting[]` lists the documents the next request must carry. Its `text` names the stage: pre for the preauthorisation, post for the claim.

### The identifier is not a correlation key

`CoverageEligibilityResponse.identifier` identifies the beneficiary at the hospital. Correlate on the protocol headers.

## PMJAY

The generic bundle above is what every payer takes, IRDAI-regulated insurers and TPAs included. PMJAY takes it with the changes and requirements below.

### What changes in the bundle

PMJAY uses a different bundle for this step, headed by `CoverageEligibilityRequest` rather than `CoverageEligibilityResponse`.

| #  | Resource                      | Profile                                                                                                         |
| -- | ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
| 1  | `CoverageEligibilityRequest`  | [CoverageEligibilityRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CoverageEligibilityRequest.html) |
| 2  | `Patient`                     | [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)                                       |
| 3  | `Organization (prov)`         | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                             |
| 4  | `Organization (pay)`          | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                             |
| 5  | `Location`                    | none declared; NRCeS [Location](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Location.html)                |
| 6  | `Coverage`                    | [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)                                     |
| 7  | `PractitionerRole`            | [PractitionerRole](https://nrces.in/ndhm/fhir/r4/StructureDefinition-PractitionerRole.html)                     |
| 8  | `CoverageEligibilityResponse` | [CoverageEligibilityResponse](https://hl7.org/fhir/R4/coverageeligibilityresponse.html)                         |
| 9  | `Patient`                     | none declared; NRCeS [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)                  |
| 10 | `Coverage`                    | none declared; NRCeS [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)                |
| 11 | `Organization (pay)`          | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)        |
| 12 | `Organization (prov)`         | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)        |

##### CoverageEligibilityResponse

NRCeS profile: [CoverageEligibilityResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CoverageEligibilityResponse.html).

| Element                                                 | Example                                                                                         |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `identifier[]`                                          | system `https://hcx.pmjay.gov.in/v1/coverageeligibility/check`, value `PMJAY0000X-IN1910000151` |
| `status`                                                | `active`                                                                                        |
| `purpose`                                               | `auth-requirements`                                                                             |
| `patient`                                               | reference `https://payer.nha.gov.in/coverageeligibility/v1/coverageeligibility/on_check/co…`    |
| `created`                                               | `2026-09-11T00:32:42+05:30`                                                                     |
| `requestor`                                             | reference `https://payer.nha.gov.in/coverageeligibility/v1/coverageeligibility/on_check/co…`    |
| `request`                                               | reference `https://nhcx.abdm.gov.in/coverage-eligibility/request`                               |
| `outcome`                                               | `complete`                                                                                      |
| `disposition`                                           | `Policy is currently in-force`                                                                  |
| `insurer`                                               | reference `https://payer.nha.gov.in/coverageeligibility/v1/coverageeligibility/on_check/co…`    |
| `insurance[]`                                           | inforce `true`                                                                                  |
| `insurance[].coverage`                                  | reference `https://payer.nha.gov.in/coverageeligibility/v1/coverageeligibility/on_check/co…`    |
| `insurance[].item[]`                                    | excluded `false`, authorizationRequired `true`                                                  |
| `insurance[].item[].category.coding[]`                  | `MG` General Medicine                                                                           |
| `insurance[].item[].productOrService.coding[]`          | `MG0111A` Pleural Effusion (Pleural Effusion)                                                   |
|                                                         | `MG072C` Acute Haemodialysis (Acute Haemodialysis)                                              |
| `insurance[].item[].benefit[].type.coding[]`            | `Procedure` Procedure in `https://hl7.org/fhir/R4/codesystem-benefit-type.html`                 |
| `insurance[].item[].benefit[].allowedMoney`             | value `2070`, currency `INR`                                                                    |
|                                                         | value `1725`, currency `INR`                                                                    |
| `insurance[].item[].authorizationSupporting[]`          | text \`Type: pre                                                                                |
| Procedure Code:MG0111A\`                                |                                                                                                 |
|                                                         | text `fullUrl: https://payer.gov.in/policy/questionnaire/100003`                                |
|                                                         | text `fullUrl: https://payer.gov.in/policy/questionnaire/100008`                                |
|                                                         | and 7 more                                                                                      |
| `insurance[].item[].authorizationSupporting[].coding[]` | `MAND0409` any investigations done                                                              |
|                                                         | `MAND0408` Clinical notes detailing history and Admission notes showing vitals and examina…     |
|                                                         | `MAND0455` CXR PA view or CECT chest abdomen and pelvis                                         |
|                                                         | and 9 more                                                                                      |

The `CoverageEligibilityRequest`, `Patient`, `Organization`, `Location`, `Coverage`, `PractitionerRole` entries are shaped as in the chapters that introduce them.

### What PMJAY specifies

- The bundle echoes the whole request first and then gives the answer, with the payer's own `Patient`, `Coverage` and both `Organization` entries.
- A PMJAY answer can carry only `item.excluded` and `item.authorizationRequired`, without `benefitPeriod`, `benefit[]` or `authorizationSupporting[]`. The documents then come from the plan.
- The payer's `Patient` can differ from yours in name, gender and birth date. Do not overwrite your record from it.

## Use cases, APIs and data elements

### C3 Respond to coverage eligibility (payer)

The eligibility and plan details for the beneficiary asked about. A payer may instead answer with a forward instruction, asking the exchange to pass the request to another payer.

|                    |                                                                                                                                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/coverageeligibility/on_check` [`apis/02-eligibility/v1-coverageeligibility-on-check.bru`](/docs/nhcx/v1/api/eligibility/endpoints/eligibility-v1-coverageeligibility-on-check) |
| **Callback**       | `/v1/coverageeligibility/check` [`apis/02-eligibility/v1-coverageeligibility-check.bru`](/docs/nhcx/v1/api/eligibility/endpoints/eligibility-v1-coverageeligibility-check)          |
| **Workflow**       | none (or 5 under PMJAY)                                                                                                                                                             |
| **Carries JWE**    | yes                                                                                                                                                                                 |
| **Focal resource** | `CoverageEligibilityResponse`                                                                                                                                                       |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1518@hcx`          |
| `x-hcx-recipient_code` | `1000004446@hcx`    |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `11`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `response.complete` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |
| `x-hcx-debug_flag`     | `INFO`              |

**Data elements**

| Element        | Label                    | Group    | Type      | Card.  | FHIR path                                                                                  | Example     | Notes |
| -------------- | ------------------------ | -------- | --------- | ------ | ------------------------------------------------------------------------------------------ | ----------- | ----- |
| `outcome`      | Verdict Outcome          | Verdict  | `code`    | `1..1` | `CoverageEligibilityResponse.outcome`                                                      | `complete`  |       |
| `inforce`      | Policy In Force          | Coverage | `boolean` | `1..1` | `CoverageEligibilityResponse.insurance[0].inforce`                                         | `true`      |       |
| `allowedMoney` | Remaining Balance Amount | Benefit  | `decimal` | `0..1` | `CoverageEligibilityResponse.insurance[0].item[].benefit[type=benefit].allowedMoney.value` | `485000.00` |       |

NRCeS profiles: [CoverageEligibilityResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CoverageEligibilityResponse.html).


---

# Bundles and conventions

Everything that crosses the exchange is one FHIR R4 Bundle of type `collection`, built to the NRCeS profiles for NHCX. The bundles in this reference are generic: any payer on the exchange takes them, private insurers and TPAs regulated by IRDAI as well as government schemes. Each chapter shows the generic bundle for one exchange in one direction, then what PMJAY changes and what PMJAY requires on top. The package's sample collection is read the same way: a provider's bundles are either examples written to this specification or captures from the sandbox run against the PMJAY payer, and a payer's are either the generic payer's or PMJAY's own. This chapter holds the rules every bundle obeys before any exchange is considered.

## Rules

### Bundle type

`collection`, not `document` and not `transaction`. Entries are resources placed directly, with no request or response elements. The open-protocol page describes claim objects as `document` bundles with a root `Composition`; the exchange accepts `collection`, and a `Composition` appears only at the head of an embedded clinical record.

### Profiles

Declare the NRCeS profile in `meta.profile` on every resource you send, for example `https://nrces.in/ndhm/fhir/r4/StructureDefinition/Claim`. Declare only profiles NRCeS publishes: there is no NRCeS `QuestionnaireResponse` profile, so a `QuestionnaireResponse` takes the base FHIR definition. Do not require a profile on what you receive: payer-generated resources often carry none.

### References

Resources in one bundle reference each other by `urn:uuid:`, with the same UUID as the entry's `fullUrl`. Absolute URLs are also accepted. Parse both.

### Timestamps

ISO 8601 with the Indian offset, `+05:30`. UTC fails validation. Read `Bundle.timestamp` for the send time; `meta.lastUpdated` can be stale.

### Identifier types come from two systems

`PMJAY`, `ABHA`, `CLN`, `UTR`, `HPID` and `HPIN` from NRCeS at `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`. `NPI` for a hospital's HFR ID, `NIIP` for a payer's registry ID, `NH` for a plan, `MB` for a member number, and `JHN`, `MD` and `MR` from HL7 at `http://terminology.hl7.org/CodeSystem/v2-0203`. Take the system from the exchange you are building, not from the code.

### The HFR ID inside the bundle

Must equal the registry ID on the sender's participant record, whichever element carries it.

### Sequences link things

A `Claim.item` points at its diagnosis, procedure, care team and supporting information by sequence number, not by reference. Resolve through the `sequence` field, never by array position.

### Documents arrive two ways

A supporting-info entry carries the file inline in `valueAttachment`, or points with `valueReference` at a resource in the same bundle: a `DocumentReference`, or the `Composition` heading an embedded ABDM record. One document per entry, 2 MB each, 20 MB per claim or preauthorisation bundle. Plan responses run past 20 MB; size clients and proxies for 25 MB.

### Category decides structured or not

Supporting-info categories `DIA`, `HDS`, `CD` and `INF` take a reference to a structured record. `POI`, `POA`, `DOB`, `DEF`, `FIR`, `ATT` and `MB` take an attachment.

### Encode attachments once

Base64 the file once. On receipt, check the decoded bytes for a file signature before trusting them, because double-encoded attachments are in circulation and render as a blank page.

### One Claim, three uses

`Claim.use` is `preauthorization`, `claim` or `predetermination`, and nothing else changes. `pre-auth` and `pre-det` are not codes.

### Codes and displays match the plan

Character for character, including the plan's own misspellings. A payer rejects a package whose display differs from the plan's.

### Match on the code, not the system

The same package code appears under different systems in different exchanges. Match incoming codes on the code, and emit the system the exchange you are building expects.

## Resources by exchange

Each resource the bundles carry, its NRCeS profile, and the exchanges that use it.

### Claim

NRCeS profile: [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html).

- [Preauthorisation request](/docs/nhcx/v1/reference/fhir/preauthorisation-request)
- [Preauthorisation enhancement](/docs/nhcx/v1/reference/fhir/preauthorisation-enhancement)
- [Preauthorisation query and answer](/docs/nhcx/v1/reference/fhir/preauthorisation-query-and-answer)
- [Claim request](/docs/nhcx/v1/reference/fhir/claim-request)
- [Claim query and answer](/docs/nhcx/v1/reference/fhir/claim-query-and-answer)
- [Communication](/docs/nhcx/v1/reference/fhir/communication)
- [Status and search](/docs/nhcx/v1/reference/fhir/status-and-search)

### ClaimResponse

NRCeS profile: [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html).

- [Preauthorisation response](/docs/nhcx/v1/reference/fhir/preauthorisation-response)
- [Preauthorisation query and answer](/docs/nhcx/v1/reference/fhir/preauthorisation-query-and-answer)
- [Claim response](/docs/nhcx/v1/reference/fhir/claim-response)
- [Claim query and answer](/docs/nhcx/v1/reference/fhir/claim-query-and-answer)
- [Cancel, reprocess and shortfall](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall)
- [Status and search](/docs/nhcx/v1/reference/fhir/status-and-search)

### Communication

NRCeS profile: [Communication](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Communication.html).

- [Preauthorisation query and answer](/docs/nhcx/v1/reference/fhir/preauthorisation-query-and-answer)
- [Claim query and answer](/docs/nhcx/v1/reference/fhir/claim-query-and-answer)
- [Communication](/docs/nhcx/v1/reference/fhir/communication)

### CommunicationRequest

NRCeS profile: [CommunicationRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CommunicationRequest.html).

- [Preauthorisation query and answer](/docs/nhcx/v1/reference/fhir/preauthorisation-query-and-answer)
- [Claim query and answer](/docs/nhcx/v1/reference/fhir/claim-query-and-answer)
- [Communication](/docs/nhcx/v1/reference/fhir/communication)

### Coverage

NRCeS profile: [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html).

- [Coverage eligibility request](/docs/nhcx/v1/reference/fhir/coverage-eligibility-request)
- [Coverage eligibility response](/docs/nhcx/v1/reference/fhir/coverage-eligibility-response)
- [Preauthorisation request](/docs/nhcx/v1/reference/fhir/preauthorisation-request)
- [Preauthorisation response](/docs/nhcx/v1/reference/fhir/preauthorisation-response)
- [Preauthorisation enhancement](/docs/nhcx/v1/reference/fhir/preauthorisation-enhancement)
- [Preauthorisation query and answer](/docs/nhcx/v1/reference/fhir/preauthorisation-query-and-answer)
- [Claim request](/docs/nhcx/v1/reference/fhir/claim-request)
- [Claim response](/docs/nhcx/v1/reference/fhir/claim-response)
- [Claim query and answer](/docs/nhcx/v1/reference/fhir/claim-query-and-answer)
- [Cancel, reprocess and shortfall](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall)
- [Communication](/docs/nhcx/v1/reference/fhir/communication)
- [Status and search](/docs/nhcx/v1/reference/fhir/status-and-search)

### CoverageEligibilityRequest

NRCeS profile: [CoverageEligibilityRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CoverageEligibilityRequest.html).

- [Coverage eligibility request](/docs/nhcx/v1/reference/fhir/coverage-eligibility-request)
- [Coverage eligibility response](/docs/nhcx/v1/reference/fhir/coverage-eligibility-response)

### CoverageEligibilityResponse

NRCeS profile: [CoverageEligibilityResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CoverageEligibilityResponse.html).

- [Coverage eligibility response](/docs/nhcx/v1/reference/fhir/coverage-eligibility-response)

### InsurancePlan

NRCeS profile: [InsurancePlan](https://nrces.in/ndhm/fhir/r4/StructureDefinition-InsurancePlan.html).

- [Insurance plan response](/docs/nhcx/v1/reference/fhir/insurance-plan-response-overview)
- [Insurance plan response, package-based](/docs/nhcx/v1/reference/fhir/insurance-plan-response-package-based)
- [Insurance plan response, coverage-based](/docs/nhcx/v1/reference/fhir/insurance-plan-response-coverage-based)

### Location

NRCeS profile: [Location](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Location.html).

- [Coverage eligibility request](/docs/nhcx/v1/reference/fhir/coverage-eligibility-request)
- [Coverage eligibility response](/docs/nhcx/v1/reference/fhir/coverage-eligibility-response)

### Organization

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

- [Coverage eligibility request](/docs/nhcx/v1/reference/fhir/coverage-eligibility-request)
- [Coverage eligibility response](/docs/nhcx/v1/reference/fhir/coverage-eligibility-response)
- [Insurance plan response](/docs/nhcx/v1/reference/fhir/insurance-plan-response-overview)
- [Insurance plan response, package-based](/docs/nhcx/v1/reference/fhir/insurance-plan-response-package-based)
- [Insurance plan response, coverage-based](/docs/nhcx/v1/reference/fhir/insurance-plan-response-coverage-based)
- [Preauthorisation request](/docs/nhcx/v1/reference/fhir/preauthorisation-request)
- [Preauthorisation response](/docs/nhcx/v1/reference/fhir/preauthorisation-response)
- [Preauthorisation enhancement](/docs/nhcx/v1/reference/fhir/preauthorisation-enhancement)
- [Preauthorisation query and answer](/docs/nhcx/v1/reference/fhir/preauthorisation-query-and-answer)
- [Claim request](/docs/nhcx/v1/reference/fhir/claim-request)
- [Claim response](/docs/nhcx/v1/reference/fhir/claim-response)
- [Claim query and answer](/docs/nhcx/v1/reference/fhir/claim-query-and-answer)
- [Cancel, reprocess and shortfall](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall)
- [Payment notice and acknowledgement](/docs/nhcx/v1/reference/fhir/payment-notice-and-acknowledgement)
- [Communication](/docs/nhcx/v1/reference/fhir/communication)
- [Status and search](/docs/nhcx/v1/reference/fhir/status-and-search)

### Patient

NRCeS profile: [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html).

- [Coverage eligibility request](/docs/nhcx/v1/reference/fhir/coverage-eligibility-request)
- [Coverage eligibility response](/docs/nhcx/v1/reference/fhir/coverage-eligibility-response)
- [Preauthorisation request](/docs/nhcx/v1/reference/fhir/preauthorisation-request)
- [Preauthorisation response](/docs/nhcx/v1/reference/fhir/preauthorisation-response)
- [Preauthorisation enhancement](/docs/nhcx/v1/reference/fhir/preauthorisation-enhancement)
- [Preauthorisation query and answer](/docs/nhcx/v1/reference/fhir/preauthorisation-query-and-answer)
- [Claim request](/docs/nhcx/v1/reference/fhir/claim-request)
- [Claim response](/docs/nhcx/v1/reference/fhir/claim-response)
- [Claim query and answer](/docs/nhcx/v1/reference/fhir/claim-query-and-answer)
- [Cancel, reprocess and shortfall](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall)
- [Communication](/docs/nhcx/v1/reference/fhir/communication)
- [Status and search](/docs/nhcx/v1/reference/fhir/status-and-search)

### PaymentNotice

NRCeS profile: [PaymentNotice](https://nrces.in/ndhm/fhir/r4/StructureDefinition-PaymentNotice.html).

- [Payment notice and acknowledgement](/docs/nhcx/v1/reference/fhir/payment-notice-and-acknowledgement)

### PaymentReconciliation

NRCeS profile: [PaymentReconciliation](https://nrces.in/ndhm/fhir/r4/StructureDefinition-PaymentReconciliation.html).

- [Payment notice and acknowledgement](/docs/nhcx/v1/reference/fhir/payment-notice-and-acknowledgement)

### Practitioner

NRCeS profile: [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html).

- [Preauthorisation request](/docs/nhcx/v1/reference/fhir/preauthorisation-request)
- [Preauthorisation enhancement](/docs/nhcx/v1/reference/fhir/preauthorisation-enhancement)
- [Preauthorisation query and answer](/docs/nhcx/v1/reference/fhir/preauthorisation-query-and-answer)
- [Claim request](/docs/nhcx/v1/reference/fhir/claim-request)
- [Claim query and answer](/docs/nhcx/v1/reference/fhir/claim-query-and-answer)
- [Communication](/docs/nhcx/v1/reference/fhir/communication)
- [Status and search](/docs/nhcx/v1/reference/fhir/status-and-search)

### PractitionerRole

NRCeS profile: [PractitionerRole](https://nrces.in/ndhm/fhir/r4/StructureDefinition-PractitionerRole.html).

- [Coverage eligibility request](/docs/nhcx/v1/reference/fhir/coverage-eligibility-request)
- [Coverage eligibility response](/docs/nhcx/v1/reference/fhir/coverage-eligibility-response)

### Procedure

NRCeS profile: [Procedure](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Procedure.html).

- [Preauthorisation request](/docs/nhcx/v1/reference/fhir/preauthorisation-request)
- [Preauthorisation enhancement](/docs/nhcx/v1/reference/fhir/preauthorisation-enhancement)
- [Preauthorisation query and answer](/docs/nhcx/v1/reference/fhir/preauthorisation-query-and-answer)
- [Claim request](/docs/nhcx/v1/reference/fhir/claim-request)
- [Claim query and answer](/docs/nhcx/v1/reference/fhir/claim-query-and-answer)
- [Status and search](/docs/nhcx/v1/reference/fhir/status-and-search)

### Questionnaire

- [Insurance plan response](/docs/nhcx/v1/reference/fhir/insurance-plan-response-overview)
- [Insurance plan response, package-based](/docs/nhcx/v1/reference/fhir/insurance-plan-response-package-based)
- [Insurance plan response, coverage-based](/docs/nhcx/v1/reference/fhir/insurance-plan-response-coverage-based)

### QuestionnaireResponse

- [Preauthorisation request](/docs/nhcx/v1/reference/fhir/preauthorisation-request)
- [Preauthorisation enhancement](/docs/nhcx/v1/reference/fhir/preauthorisation-enhancement)
- [Preauthorisation query and answer](/docs/nhcx/v1/reference/fhir/preauthorisation-query-and-answer)
- [Claim request](/docs/nhcx/v1/reference/fhir/claim-request)
- [Claim query and answer](/docs/nhcx/v1/reference/fhir/claim-query-and-answer)

### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

- [Insurance plan request](/docs/nhcx/v1/reference/fhir/insurance-plan-request)
- [Preauthorisation query and answer](/docs/nhcx/v1/reference/fhir/preauthorisation-query-and-answer)
- [Claim query and answer](/docs/nhcx/v1/reference/fhir/claim-query-and-answer)
- [Cancel, reprocess and shortfall](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall)
- [Payment notice and acknowledgement](/docs/nhcx/v1/reference/fhir/payment-notice-and-acknowledgement)
- [Communication](/docs/nhcx/v1/reference/fhir/communication)
- [Status and search](/docs/nhcx/v1/reference/fhir/status-and-search)

## Profiles in use

The profiles the bundles declare in `meta.profile`, each linked to its published definition.

- [`http://hl7.org/fhir/StructureDefinition/CoverageEligibilityResponse`](https://hl7.org/fhir/R4/coverageeligibilityresponse.html)
- [`https://nrces.in/ndhm/fhir/r4/StructureDefinition/Claim`](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html)
- [`https://nrces.in/ndhm/fhir/r4/StructureDefinition/ClaimResponse`](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html)
- [`https://nrces.in/ndhm/fhir/r4/StructureDefinition/Communication`](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Communication.html)
- [`https://nrces.in/ndhm/fhir/r4/StructureDefinition/CommunicationRequest`](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CommunicationRequest.html)
- [`https://nrces.in/ndhm/fhir/r4/StructureDefinition/Coverage`](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)
- [`https://nrces.in/ndhm/fhir/r4/StructureDefinition/CoverageEligibilityRequest`](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CoverageEligibilityRequest.html)
- [`https://nrces.in/ndhm/fhir/r4/StructureDefinition/CoverageEligibilityResponse`](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CoverageEligibilityResponse.html)
- [`https://nrces.in/ndhm/fhir/r4/StructureDefinition/InsurancePlan`](https://nrces.in/ndhm/fhir/r4/StructureDefinition-InsurancePlan.html)
- [`https://nrces.in/ndhm/fhir/r4/StructureDefinition/Location`](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Location.html)
- [`https://nrces.in/ndhm/fhir/r4/StructureDefinition/Organization`](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)
- [`https://nrces.in/ndhm/fhir/r4/StructureDefinition/Patient`](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)
- [`https://nrces.in/ndhm/fhir/r4/StructureDefinition/Practitioner`](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html)
- [`https://nrces.in/ndhm/fhir/r4/StructureDefinition/PractitionerRole`](https://nrces.in/ndhm/fhir/r4/StructureDefinition-PractitionerRole.html)
- [`https://nrces.in/ndhm/fhir/r4/StructureDefinition/Procedure`](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Procedure.html)
- `https://nrces.in/ndhm/fhir/r4/StructureDefinition/QuestionnaireResponse`, which NRCeS does not publish; base FHIR [QuestionnaireResponse](https://hl7.org/fhir/R4/questionnaireresponse.html)
- [`https://nrces.in/ndhm/fhir/r4/StructureDefinition/Task`](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)

## PMJAY

The generic bundle above is what every payer takes, IRDAI-regulated insurers and TPAs included. PMJAY takes it with the changes and requirements below.

### What PMJAY specifies

- Payer-generated bundles carry the case number as `Bundle.identifier`, under the payer's own host. The host arrives spelled both `payer.pmjay.nha.gov.in` and `payer.pmajy.nha.gov.in`; echo the spelling that arrived.
- Payer-generated bundles tag every resource `SUBSETTED` from `http://terminology.hl7.org/CodeSystem/v3-ObservationValue`, "Resource encoded in summary mode". It marks a projection of the payer's record, not an error.
- Identifier systems on the payer's side are NHA hosts such as `https://hcx.pmjay.gov.in/v1/preauthorization` and `https://payer.nha.gov.in`.
- A preauthorisation with its embedded clinical records runs to around 30 entries, a claim to over 40, a query answer to nearly a hundred.

### What PMJAY requires

- Element ids on every Claim bundle: the `Claim` its claim number, each `item` `Item/n`, each `procedure` `Procedure/n`, each `supportingInfo` `SupportingInformation/n`; `1` for `Patient`, `Coverage` and the provider `Organization`, `2` for the payer `Organization`. Refused with `PAYR-1027` otherwise.
- The `Practitioner` carries the HPR id typed `HPIN` under `https://hpr.abdm.gov.in`, beside `HPID` and the registration number typed `MD`. Refused with `PAYR-1083` otherwise.
- Items coded from the package master: `item.category` is the master's specialty code, and the ward tier rides as `item.modifier` with the master's stratification code.
- Every `supportingInfo` carries a `sequence`, numbered from 1 with no gaps. Refused with `PAYR-1019` otherwise.
- Attachments as `application/pdf`, `application/jpg`, `application/jpeg`, `application/png` or `application/fhir+json`. Anything else is refused with `PAYR-1008`.


---

# Insurance plan request

One `Task` asking a payer for the plan behind a policy. There is no patient and no clinical content, because the plan belongs to the policy and the hospital, not to an admission. Sent once per policy and cached.

Sent on `/v1/insuranceplan/request`, answered on `/v1/insuranceplan/on_request`.

## The bundle

| # | Resource | Profile                                                             |
| - | -------- | ------------------------------------------------------------------- |
| 1 | `Task`   | [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html) |

## Elements

### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                 | Example                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------- |
| `status`                | `requested`                                                                            |
| `intent`                | `order`                                                                                |
| `code.coding[]`         | `poll` in `http://terminology.hl7.org/CodeSystem/financialtaskcode`                    |
| `input[]`               | valueString `POL7UMU001`                                                               |
|                         | valueString `IN1910000151`                                                             |
| `input[].type.coding[]` | `policyNumber` in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-input-type-code` |
|                         | `providerId` in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-input-type-code`   |

## Rules

### The Task code system

`poll` under `http://terminology.hl7.org/CodeSystem/financialtaskcode`, not the older `https://nhcx.abdm.gov.in/api`.

### Intent

`order`. Some element tables say `original-order`; the bundle sends `order`.

### Inputs

`valueString`, typed `policyNumber` and `providerId` under `ndhm-task-input-type-code`. Both are required, one of each: the policy number and the hospital's HFR ID (`facilityId` in the data elements below). Together they narrow the answer to the packages this hospital is empanelled for.

### No case yet

No case exists, so the bundle carries no case number. The callback is the only link between request and answer.

### Task codes differ by system across the exchange

`poll`, `cancel`, `reprocess`, `release` and `status` in `financialtaskcode`; `deliver` in `ndhm-task-codes`; `approve` in `http://hl7.org/fhir/CodeSystem/task-code`. Switch on system and code together.

### When to send it

Once per policy, not per patient. Refresh on a `policychange` communication and on your own schedule.

## PMJAY

The generic bundle above is what every payer takes, IRDAI-regulated insurers and TPAs included. PMJAY takes it with the changes and requirements below.

### What changes in the bundle

The PMJAY bundle has the same resources, elements and systems as the generic one.

### What PMJAY specifies

- `policyNumber` is the beneficiary's own policy code from the policy lookup, of the form `PMJAY/<state>/S/G`.
- `providerId` is the hospital's HFR ID, the same value as on its participant record.

### What PMJAY requires

- A policy the hospital is not empanelled under is refused with `PAYR-1401`.
- Refresh weekly per the FRD, or every fifteen days per the scenario sheet, and at once on renewal, amendment or a `policychange` communication.

## Use cases, APIs and data elements

### B2 Request insurance plan (provider)

A Task with code poll, keyed on policy number and provider id. The answer is the policy as a benefit structure: packages, rates, documents, questionnaires.

|                    |                                                                                                                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/insuranceplan/request` [`apis/09-insurance-plan/v1-insuranceplan-request.bru`](/docs/nhcx/v1/api/insurance-plan/endpoints/insurance-plan-v1-insuranceplan-request)          |
| **Callback**       | `/v1/insuranceplan/on_request` [`apis/09-insurance-plan/v1-insuranceplan-on-request.bru`](/docs/nhcx/v1/api/insurance-plan/endpoints/insurance-plan-v1-insuranceplan-on-request) |
| **Carries JWE**    | yes                                                                                                                                                                              |
| **Focal resource** | `Task`                                                                                                                                                                           |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | empty               |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | empty               |

**Data elements**

| Element        | Label           | Group      | Type     | Card.  | FHIR path                                   | Example        | Notes |
| -------------- | --------------- | ---------- | -------- | ------ | ------------------------------------------- | -------------- | ----- |
| `taskCode`     | Task Code       | Task       | `code`   | `1..1` | `Task.code.coding[0].code`                  | `poll`         |       |
| `policyNumber` | Policy Number   | Task Input | `string` | `1..1` | `Task.input[type=PolicyNumber].valueString` | `PMJAY/HP/S/G` |       |
| `facilityId`   | Provider HFR ID | Task Input | `string` | `1..1` | `Task.input[type=ProviderId].valueString`   | `IN1910000151` |       |

NRCeS profiles: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

### D1 Fetch the insurance plan (pmjay)

Keyed on provider id, policy code and participant id. The answer is the scheme configuration for this hospital: specialities, packages, rates, Claim-Condition flags, mandatory documents and questionnaires. Over twenty megabytes; store it queryable, version it, refresh weekly and on any policychange communication.

|                    |                                                                                                                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/insuranceplan/request` [`apis/09-insurance-plan/v1-insuranceplan-request.bru`](/docs/nhcx/v1/api/insurance-plan/endpoints/insurance-plan-v1-insuranceplan-request)          |
| **Callback**       | `/v1/insuranceplan/on_request` [`apis/09-insurance-plan/v1-insuranceplan-on-request.bru`](/docs/nhcx/v1/api/insurance-plan/endpoints/insurance-plan-v1-insuranceplan-on-request) |
| **Carries JWE**    | yes                                                                                                                                                                              |
| **Focal resource** | `Task`                                                                                                                                                                           |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | empty               |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | empty               |

**Data elements**

| Element    | Label                    | Group      | Type     | Card.  | FHIR path                                   | Example        | Notes |
| ---------- | ------------------------ | ---------- | -------- | ------ | ------------------------------------------- | -------------- | ----- |
| `taskCode` | Task Code                | Task       | `code`   | `1..1` | `Task.code.coding[0].code`                  | `poll`         |       |
| `schemeId` | Scheme Policy Identifier | Task Input | `string` | `1..1` | `Task.input[type=PolicyNumber].valueString` | `PMJAY/HP/S/G` |       |

NRCeS profiles: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).


---

# Insurance plan response, coverage-based

The shape a private insurer or its TPA sends, and the generic shape on the exchange. An indemnity policy lists benefits with money limits, and the hospital bills against those limits rather than against a package price.

## The bundle

| # | Resource             | Profile                                                                               |
| - | -------------------- | ------------------------------------------------------------------------------------- |
| 1 | `InsurancePlan`      | [InsurancePlan](https://nrces.in/ndhm/fhir/r4/StructureDefinition-InsurancePlan.html) |
| 2 | `Organization (ins)` | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)   |
| 3 | `Questionnaire`      | none                                                                                  |
| 4 | `Questionnaire`      | none                                                                                  |
| 5 | `Questionnaire`      | none                                                                                  |
| 6 | `Questionnaire`      | none                                                                                  |
| 7 | `Questionnaire`      | none                                                                                  |

## Elements

NRCeS profile: [InsurancePlan](https://nrces.in/ndhm/fhir/r4/StructureDefinition-InsurancePlan.html).

| Element                                                | Example                                                                                                                                             |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `coverage[].type.coding[]`                             | `737481003` Inpatient care management (procedure) in `http://snomed.info/sct`                                                                       |
|                                                        | `710967003` Management of health status after discharge from hospital (procedure) in `http://snomed.info/sct`                                       |
|                                                        | `409972000` Pre-hospital care in `http://snomed.info/sct`                                                                                           |
|                                                        | and 6 more                                                                                                                                          |
| `coverage[].benefit[].type.coding[]`                   | `309904001` Intensive care unit (environment) in `http://snomed.info/sct`                                                                           |
|                                                        | `87612001` Blood in `http://snomed.info/sct`                                                                                                        |
|                                                        | `24099007` Oxygen (substance) in `http://snomed.info/sct`                                                                                           |
|                                                        | and 20 more                                                                                                                                         |
| `coverage[].benefit[].limit[].value`                   | value `90`, comparator `<=`, unit `day`                                                                                                             |
|                                                        | value `60`, comparator `<=`, unit `day`                                                                                                             |
| `coverage[].benefit[]`                                 | id `PROC-PED-05`                                                                                                                                    |
|                                                        | id `PROC-CARD-04`                                                                                                                                   |
|                                                        | id `PROC-CAT-03`                                                                                                                                    |
|                                                        | and 2 more                                                                                                                                          |
| `coverage[].benefit[].type`                            | text `Paediatric Pneumonia, PICU Management`                                                                                                        |
|                                                        | text `Percutaneous Transluminal Coronary Angioplasty (PTCA)`                                                                                        |
|                                                        | text `Cataract Surgery with Foldable IOL`                                                                                                           |
|                                                        | and 2 more                                                                                                                                          |
| `plan[].identifier[]`                                  | use `official`, value `Sandbox Default Policy`                                                                                                      |
| `plan[].type.coding[]`                                 | `01` Individual in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-plan-type`                                                                        |
| `plan[].generalCost[].cost`                            | value `500000`, currency `INR`                                                                                                                      |
| `plan[].specificCost[].category.coding[]`              | `49122002` Ambulance, device (physical object) in `http://snomed.info/sct`                                                                          |
|                                                        | `224663004` Single room (environment) in `http://snomed.info/sct`                                                                                   |
|                                                        | `309904001` Intensive care unit (environment) in `http://snomed.info/sct`                                                                           |
|                                                        | and 4 more                                                                                                                                          |
| `plan[].specificCost[].benefit[].type.coding[]`        | `49122002` Ambulance, device (physical object) in `http://snomed.info/sct`                                                                          |
|                                                        | `224663004` Single room (environment) in `http://snomed.info/sct`                                                                                   |
|                                                        | `309904001` Intensive care unit (environment) in `http://snomed.info/sct`                                                                           |
|                                                        | and 16 more                                                                                                                                         |
| `plan[].specificCost[].benefit[].cost[].type.coding[]` | `fullcoverage`                                                                                                                                      |
|                                                        | `Procedure` Selected treatment or service or product is a type of procedure or package in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-plan-type` |
| `plan[].specificCost[].benefit[].cost[].value`         | value `5000`, unit `INR`                                                                                                                            |
|                                                        | value `10000`, unit `INR`                                                                                                                           |
|                                                        | value `20000`, unit `INR`                                                                                                                           |
|                                                        | and 6 more                                                                                                                                          |
| `plan[].specificCost[].benefit[]`                      | id `PROC-PED-05`                                                                                                                                    |
|                                                        | id `PROC-CARD-04`                                                                                                                                   |
|                                                        | id `PROC-CAT-03`                                                                                                                                    |
|                                                        | and 2 more                                                                                                                                          |
| `plan[].specificCost[].benefit[].type`                 | text `Paediatric Pneumonia, PICU Management`                                                                                                        |
|                                                        | text `Percutaneous Transluminal Coronary Angioplasty (PTCA)`                                                                                        |
|                                                        | text `Cataract Surgery with Foldable IOL`                                                                                                           |
|                                                        | and 2 more                                                                                                                                          |

## Claim-Condition flags

| Flag                | Values in the plan                      | What it governs                                                                  |
| ------------------- | --------------------------------------- | -------------------------------------------------------------------------------- |
| `ProcedureType`     | `Critical Care`, `Day Care`, `Surgical` | The kind of care the benefit covers, such as surgical, day care or critical care |
| `IsDayCare`         | `N`, `Y`                                | Day-care treatment, no overnight stay                                            |
| `ImplantApplicable` | `N`, `Y`                                | Whether an implant may be billed under the benefit                               |

## Supporting-information requirements

| Code       | Display                                    | Stage     | System                                                                  |
| ---------- | ------------------------------------------ | --------- | ----------------------------------------------------------------------- |
| `POI`      | Proof of identity                          | preauth   | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `DIA`      | Diagnostic report                          | preauth   | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `RAD`      | Radiology / X-Ray / CT / MRI Scan Reports  | preauth   | `<participant-defined>`                                                 |
| `HDS`      | Hospital discharge summary                 | discharge | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `CD`       | Clinical document                          | discharge | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `ICU`      | ICU Flow Chart & Vital Monitoring Log      | discharge | `<participant-defined>`                                                 |
| `HDS`      | Hospital discharge summary                 | claim     | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `MB`       | Medical bill                               | claim     | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `FCF`      | Filled claim form                          | claim     | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `INF`      | Additional info related to claim           | any       | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `STG`      | Standard Treatment Guidelines              | any       | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `ANG`      | Coronary Angiography Film & CD Report      | preauth   | `<participant-defined>`                                                 |
| `ECG`      | 12-Lead Electrocardiogram (ECG) Strip      | preauth   | `<participant-defined>`                                                 |
| `MB`       | Medical bill                               | preauth   | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `EST`      | Detailed Pre-Auth Cost Estimate            | preauth   | `<participant-defined>`                                                 |
| `IMP`      | Document Type - Implant                    | discharge | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `IMP`      | Document Type - Implant                    | claim     | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `CER`      | Medical Certficate                         | preauth   | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `MB`       | Medical bill                               | discharge | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `DIA`      | Diagnostic report                          | claim     | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `HIS_PATH` | Histopathology / Biopsy Report             | claim     | `<participant-defined>`                                                 |
| `CD`       | Clinical document                          | claim     | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `OTR`      | Operation Theatre Notes & Surgical Summary | claim     | `<participant-defined>`                                                 |

10 of the requirements link a questionnaire through `documentationUrl`.

## Exclusions

| category | statement                                                                        | item     |
| -------- | -------------------------------------------------------------------------------- | -------- |
| Excl01   | Expenses related to the treatment of a pre-existing Disease (PED) and its direc… |          |
| Excl02   | Expenses related to the treatment of the listed conditions, surgeries and treat… | 86077009 |
| Excl03   | Expenses related to the treatment of any illness within 30 days from the first … |          |
| Excl08   | Expenses for cosmetic or plastic surgery are excluded unless required as part o… |          |

## Questionnaires

| Title                                                                            | Items | Item types | Question in |
| -------------------------------------------------------------------------------- | ----- | ---------- | ----------- |
| Paediatric Pneumonia, PICU Management, Standard Treatment Guidelines             | 4     | `string`   | `text`      |
| Percutaneous Transluminal Coronary Angioplasty (PTCA), Standard Treatment Guide… | 5     | `string`   | `text`      |
| Cataract Surgery with Foldable IOL, Standard Treatment Guidelines                | 4     | `string`   | `text`      |
| Acute Appendectomy (Laparoscopic), Standard Treatment Guidelines                 | 4     | `string`   | `text`      |
| Total Knee Replacement (Unilateral), Standard Treatment Guidelines               | 5     | `string`   | `text`      |

## Rules

### One structure per benefit

Everything about a benefit, its conditions and required documents, hangs off `coverage[].benefit[]`, with its money cap in `limit[]`. `plan[].specificCost[]` carries the cost per benefit category.

### Conditions are prose

The `Claim-Condition` extension on a benefit carries a sentence, such as a window after discharge, with the number in `limit[]` as a value, a comparator and a unit.

### Benefit types are the insurer's vocabulary

No closed value set is published for indemnity benefit types. Ask the insurer for its list before building a picker.

### Requirements by stage

Supporting-info requirements name the stage they apply to, preauthorisation, discharge or claim, in the extension url.

### Exclusions

Waiting periods, pre-existing-condition rules and excluded procedures are `Claim-Exclusion` extensions on the plan, each with a category and a statement.

### What the screen caps

The amount, against the benefit's limit. Submission is blocked by an amount over the limit or a missing mandatory document.

## PMJAY

PMJAY does not send this shape. Its plan is package-based; see the previous chapter.


---

# Insurance plan response

The payer's answer to the poll, and the largest message on NHCX. It is the policy as data: what the hospital may bill, at what rate, under what rules, with which documents and on which forms. Everything on a treatment-planning screen comes from here.

Sent on `/v1/insuranceplan/on_request`.

## The bundle

| # | Resource             | Profile                                                                               |
| - | -------------------- | ------------------------------------------------------------------------------------- |
| 1 | `InsurancePlan`      | [InsurancePlan](https://nrces.in/ndhm/fhir/r4/StructureDefinition-InsurancePlan.html) |
| 2 | `Organization (ins)` | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)   |
| 3 | `Questionnaire`      | none                                                                                  |
| 4 | `Questionnaire`      | none                                                                                  |
| 5 | `Questionnaire`      | none                                                                                  |
| 6 | `Questionnaire`      | none                                                                                  |
| 7 | `Questionnaire`      | none                                                                                  |

## Elements

### InsurancePlan

NRCeS profile: [InsurancePlan](https://nrces.in/ndhm/fhir/r4/StructureDefinition-InsurancePlan.html).

| Element                     | Example                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `identifier[]`              | system `https://irdai.gov.in`, value `SANDBOX-DEFAULT-01`                                                   |
| `status`                    | `active`                                                                                                    |
| `type[].coding[]`           | `01` Hospitalisation Indemnity Policy in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-insuranceplan-type` |
| `name`                      | `Sandbox Default Policy`                                                                                    |
| `alias`                     | `Sandbox Default`, `Default`                                                                                |
| `period`                    | start `2026-01-01`, end `2026-12-31`                                                                        |
| `ownedBy`                   | reference `urn:uuid:39cd4b51-bddd-5cc1-a65a-6fa4a2a83cb5`, display `Sandbox Payer`                          |
| `administeredBy`            | reference `urn:uuid:39cd4b51-bddd-5cc1-a65a-6fa4a2a83cb5`, display `Sandbox Payer`                          |
| `plan[].identifier[]`       | use `official`, value `Sandbox Default Policy`                                                              |
| `plan[].type.coding[]`      | `01` Individual in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-plan-type`                                |
| `plan[].generalCost[].cost` | value `500000`, currency `INR`                                                                              |

### Organization (ins)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element           | Example                                                                              |
| ----------------- | ------------------------------------------------------------------------------------ |
| `type[].coding[]` | `ins` Insurance Company in `http://terminology.hl7.org/CodeSystem/organization-type` |
| `name`            | `Sandbox Payer`                                                                      |
| `address[]`       | city `Bengaluru`, state `Karnataka`, country `India`                                 |

### Questionnaire

| Element  | Example                                                                |
| -------- | ---------------------------------------------------------------------- |
| `url`    | `<participant-defined>`                                                |
| `name`   | `STG Questionnaire`                                                    |
| `title`  | `Paediatric Pneumonia, PICU Management, Standard Treatment Guidelines` |
| `status` | `active`                                                               |

### Questionnaire

| Element  | Example                                                                            |
| -------- | ---------------------------------------------------------------------------------- |
| `url`    | `<participant-defined>`                                                            |
| `name`   | `STG Questionnaire`                                                                |
| `title`  | `Percutaneous Transluminal Coronary Angioplasty (PTCA), Standard Treatment Guide…` |
| `status` | `active`                                                                           |

### Questionnaire

| Element  | Example                                                             |
| -------- | ------------------------------------------------------------------- |
| `url`    | `<participant-defined>`                                             |
| `name`   | `STG Questionnaire`                                                 |
| `title`  | `Cataract Surgery with Foldable IOL, Standard Treatment Guidelines` |
| `status` | `active`                                                            |

### Questionnaire

| Element  | Example                                                            |
| -------- | ------------------------------------------------------------------ |
| `url`    | `<participant-defined>`                                            |
| `name`   | `STG Questionnaire`                                                |
| `title`  | `Acute Appendectomy (Laparoscopic), Standard Treatment Guidelines` |
| `status` | `active`                                                           |

### Questionnaire

| Element  | Example                                                              |
| -------- | -------------------------------------------------------------------- |
| `url`    | `<participant-defined>`                                              |
| `name`   | `STG Questionnaire`                                                  |
| `title`  | `Total Knee Replacement (Unilateral), Standard Treatment Guidelines` |
| `status` | `active`                                                             |

## Questionnaires

| Title                                                                            | Items | Item types | Question in |
| -------------------------------------------------------------------------------- | ----- | ---------- | ----------- |
| Paediatric Pneumonia, PICU Management, Standard Treatment Guidelines             | 4     | `string`   | `text`      |
| Percutaneous Transluminal Coronary Angioplasty (PTCA), Standard Treatment Guide… | 5     | `string`   | `text`      |
| Cataract Surgery with Foldable IOL, Standard Treatment Guidelines                | 4     | `string`   | `text`      |
| Acute Appendectomy (Laparoscopic), Standard Treatment Guidelines                 | 4     | `string`   | `text`      |
| Total Knee Replacement (Unilateral), Standard Treatment Guidelines               | 5     | `string`   | `text`      |

## Rules

### Two shapes

Coverage-based, sent by private insurers and TPAs: benefits with money limits, rules as prose. Package-based, sent by government schemes: named packages at fixed rates, rules as flags. The next two chapters take each shape.

### Two type codes

`InsurancePlan.type` says what kind of insurance this is. `plan.type` says how it is sold, individual or group.

### Identifier

A private insurer's plan is identified under `https://irdai.gov.in`. A scheme plan is identified under NHA hosts, with the policy code and the revision.

### The wallet

`plan.generalCost` is the sum insured, or the family wallet under a scheme.

### Cache per policy

Stamp the cache with the plan's revision identifier, and record on every preauthorisation and claim which revision it was built against.

### The first line of validation

Codes and displays, amounts, quantities and mandatory documents are checked against the cached plan on the server before anything is sent.

### The forms

The `Questionnaire` resources are the payer's forms. Render them from the plan, never hard-code them, because they change with the plan.

## PMJAY

The generic bundle above is what every payer takes, IRDAI-regulated insurers and TPAs included. PMJAY takes it with the changes and requirements below.

### What changes in the bundle

#### Elements PMJAY adds

| Element                                    | Example                                                                                               |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `InsurancePlan.identifier[].type.coding[]` | `NH` National Health Plan Identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`               |
|                                            | `XV` Health Plan Identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`                        |
| `Organization.identifier[]`                | system `https://facility.abdm.gov.in`, value `1518`                                                   |
| `Organization.identifier[].type.coding[]`  | `NIIP` National Insurance Payor Identifier (Payor) in `http://terminology.hl7.org/CodeSystem/v2-0203` |
| `Organization.active`                      | `true`                                                                                                |
| `Organization.contact[].telecom[]`         | system `phone`, value `9000000003`                                                                    |

#### Elements PMJAY leaves out

| Element                             | Example                                              |
| ----------------------------------- | ---------------------------------------------------- |
| `InsurancePlan.alias`               | `Sandbox Default`, `Default`                         |
| `InsurancePlan.plan[].identifier[]` | use `official`, value `Sandbox Default Policy`       |
| `Organization.address[]`            | city `Bengaluru`, state `Karnataka`, country `India` |

#### Systems PMJAY binds differently

| Element                      | Generic                | PMJAY                                                                   |
| ---------------------------- | ---------------------- | ----------------------------------------------------------------------- |
| `InsurancePlan.identifier[]` | `https://irdai.gov.in` | `https://hcx.pmjay.gov.in/v1/InsurancePlan`, `https://payer.nha.gov.in` |

### What PMJAY specifies

- Package-based throughout: `InsurancePlan.type` `07` Universal Health Policy, `plan.type` `03` Group.
- `identifier` carries the policy code typed `NH` and the scheme revision typed `XV`; the revision is what the cache is stamped with.
- A full scheme plan carries thousands of `Questionnaire` entries, many of them repeated. Deduplicate on `fullUrl`.

### What PMJAY requires

- Keep the revision on every submission. An outdated tariff causes a rate mismatch and a rejection on suspicion of tampering.

## Use cases, APIs and data elements

### C4 Respond to insurance plan request (payer)

The plan as a benefit structure. Under PMJAY this is the scheme configuration for one hospital and can exceed twenty megabytes.

|                    |                                                                                                                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/insuranceplan/on_request` [`apis/09-insurance-plan/v1-insuranceplan-on-request.bru`](/docs/nhcx/v1/api/insurance-plan/endpoints/insurance-plan-v1-insuranceplan-on-request) |
| **Callback**       | `/v1/insuranceplan/request` [`apis/09-insurance-plan/v1-insuranceplan-request.bru`](/docs/nhcx/v1/api/insurance-plan/endpoints/insurance-plan-v1-insuranceplan-request)          |
| **Workflow**       | none (or 5 under PMJAY)                                                                                                                                                          |
| **Carries JWE**    | yes                                                                                                                                                                              |
| **Focal resource** | `InsurancePlan`                                                                                                                                                                  |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1518@hcx`          |
| `x-hcx-recipient_code` | `1000004446@hcx`    |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | empty               |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `response.complete` |
| `x-hcx-ben-abha-id`    | empty               |

**Data elements**

| Element       | Label                | Group     | Type      | Card.  | FHIR path                                                           | Example                 | Notes |
| ------------- | -------------------- | --------- | --------- | ------ | ------------------------------------------------------------------- | ----------------------- | ----- |
| `planName`    | Insurance Plan Name  | Plan      | `string`  | `1..1` | `InsurancePlan.name`                                                | `PMJAY Ayushman Bharat` |       |
| `packageCode` | Benefit Package Code | Plan Cost | `string`  | `1..*` | `InsurancePlan.plan[].specificCost[].benefit[].type.coding[0].code` | `MG004A`                |       |
| `packageRate` | Agreed Tariff Rate   | Plan Cost | `decimal` | `1..*` | `InsurancePlan.plan[].specificCost[].benefit[].cost[0].value.value` | `15500.00`              |       |

NRCeS profiles: [InsurancePlan](https://nrces.in/ndhm/fhir/r4/StructureDefinition-InsurancePlan.html).


---

# Insurance plan response, package-based

The shape government schemes send, and PMJAY sends throughout. A package is a named procedure at a fixed, all-inclusive rate. The plan carries every package the hospital may bill and the rules that govern each one. Everything in this chapter is what PMJAY specifies.

## The bundle

| # | Resource             | Profile                                                                                                    |
| - | -------------------- | ---------------------------------------------------------------------------------------------------------- |
| 1 | `InsurancePlan`      | none declared; NRCeS [InsurancePlan](https://nrces.in/ndhm/fhir/r4/StructureDefinition-InsurancePlan.html) |
| 2 | `Organization (pay)` | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)   |
| 3 | `Questionnaire`      | none                                                                                                       |
| 4 | `Questionnaire`      | none                                                                                                       |
| 5 | `Questionnaire`      | none                                                                                                       |
| 6 | `Questionnaire`      | none                                                                                                       |
| 7 | `Questionnaire`      | none                                                                                                       |

## Elements

NRCeS profile: [InsurancePlan](https://nrces.in/ndhm/fhir/r4/StructureDefinition-InsurancePlan.html).

| Element                                                        | Example                                                                                                                                                 |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `coverage[].type.coding[]`                                     | `MG` General Medicine in `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-benefitcategory`                                                                  |
|                                                                | `SG` General Surgery in `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-benefitcategory`                                                                   |
|                                                                | `MO` Medical Oncology in `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-benefitcategory`                                                                  |
|                                                                | and 4 more                                                                                                                                              |
| `coverage[].benefit[]`                                         | id `MG004A`                                                                                                                                             |
|                                                                | id `MG005A`                                                                                                                                             |
|                                                                | id `MG072C`                                                                                                                                             |
|                                                                | and 16 more                                                                                                                                             |
| `coverage[].benefit[].type.coding[]`                           | `MG004A` Dengue fever (Dengue fever) in `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-productorservice`                                                  |
|                                                                | `MG005A` Chikungunya fever (Chikungunya fever) in `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-productorservice`                                        |
|                                                                | `MG072C` Acute Haemodialysis (Acute Haemodialysis) in `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-productorservice`                                    |
|                                                                | and 16 more                                                                                                                                             |
| `coverage[].benefit[].limit[]`                                 | id `MGMG004A`                                                                                                                                           |
|                                                                | id `MGMG004ASTRAT006a`                                                                                                                                  |
|                                                                | id `MGMG004ASTRAT006b`                                                                                                                                  |
|                                                                | and 77 more                                                                                                                                             |
| `coverage[].benefit[].limit[].value`                           | value `0`, unit `INR`                                                                                                                                   |
|                                                                | value `1800`, unit `INR`                                                                                                                                |
|                                                                | value `2700`, unit `INR`                                                                                                                                |
|                                                                | and 14 more                                                                                                                                             |
| `coverage[].benefit[].limit[].code.coding[]`                   | `MG004A` Dengue fever (Dengue fever)                                                                                                                    |
|                                                                | `STRAT006a` Routine Ward                                                                                                                                |
|                                                                | `STRAT006b` HDU                                                                                                                                         |
|                                                                | and 23 more                                                                                                                                             |
| `plan[].type.coding[]`                                         | `03` Group in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-plan-type`                                                                                 |
| `plan[].generalCost[].cost`                                    | value `500000`, currency `INR`                                                                                                                          |
| `plan[].specificCost[]`                                        | id `MG`                                                                                                                                                 |
|                                                                | id `SG`                                                                                                                                                 |
|                                                                | id `MO`                                                                                                                                                 |
|                                                                | and 2 more                                                                                                                                              |
| `plan[].specificCost[].category.coding[]`                      | `MG` General Medicine in `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-benefitcategory`                                                                  |
|                                                                | `SG` General Surgery in `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-benefitcategory`                                                                   |
|                                                                | `MO` Medical Oncology in `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-benefitcategory`                                                                  |
|                                                                | and 2 more                                                                                                                                              |
| `plan[].specificCost[].benefit[]`                              | id `PlanBenefit/MG004A`                                                                                                                                 |
|                                                                | id `PlanBenefit/MG005A`                                                                                                                                 |
|                                                                | id `PlanBenefit/MG072C`                                                                                                                                 |
|                                                                | and 12 more                                                                                                                                             |
| `plan[].specificCost[].benefit[].type.coding[]`                | `MG004A` Dengue fever (Dengue fever) in `http://hl7.org/fhir/ValueSet/procedure-category`                                                               |
|                                                                | `MG005A` Chikungunya fever (Chikungunya fever) in `http://hl7.org/fhir/ValueSet/procedure-category`                                                     |
|                                                                | `MG072C` Acute Haemodialysis (Acute Haemodialysis) in `http://hl7.org/fhir/ValueSet/procedure-category`                                                 |
|                                                                | and 12 more                                                                                                                                             |
| `plan[].specificCost[].benefit[].cost[].type.coding[]`         | `Procedure` Selected treatment or service or proudct is a type of procedure or package in `https://www.nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-plan-type` |
|                                                                | `Stratification` Selected treatment or service or proudct is a type of stratification in `https://www.nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-plan-type`  |
| `plan[].specificCost[].benefit[].cost[].value`                 | value `0`, unit `INR`                                                                                                                                   |
|                                                                | value `1800`, unit `INR`                                                                                                                                |
|                                                                | value `2700`, unit `INR`                                                                                                                                |
|                                                                | and 11 more                                                                                                                                             |
| `plan[].specificCost[].benefit[].cost[].qualifiers[].coding[]` | `STRAT006a` Routine Ward in `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-productorservice`                                                              |
|                                                                | `STRAT006b` HDU in `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-productorservice`                                                                       |
|                                                                | `STRAT006c` ICU - Without Ventilator in `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-productorservice`                                                  |
|                                                                | and 3 more                                                                                                                                              |

## Claim-Condition flags

| Flag                               | Values in the plan                                                                                                                                                           | What it governs                                                                                                                       |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `ProcedureType`                    | `Conservative`, `Medical`, `Surgical`                                                                                                                                        | Surgical, Medical or Conservative. Decides the clinical pathway, the document set, and the one-conservative-package-per-case rule     |
| `GovtReserved`                     | `N`                                                                                                                                                                          | `Y` means only a government hospital may bill it. Hide it in a private facility                                                       |
| `ApprovalNotRequired`              | `Y`, `N`                                                                                                                                                                     | `Y` means treatment need not wait for a decision. The case auto-approves if it is the first preauthorisation and every package has it |
| `EnhancementAllowed`               | `Y`, `N`                                                                                                                                                                     | `Y` means the package may be added on an enhancement                                                                                  |
| `ScheduledTATApproval`             | `Y`, `N`                                                                                                                                                                     | `Y` means the payer's silence within the turnaround window is approval                                                                |
| `QuantityAllowed`                  | `1`, `6`                                                                                                                                                                     | Maximum quantity per approval                                                                                                         |
| `IsDayCare`                        | `Y`, `N`                                                                                                                                                                     | Day-care procedure, no overnight stay                                                                                                 |
| `ImplantApplicable`                | `N`, `Y`                                                                                                                                                                     | Whether an implant line may be added                                                                                                  |
| `StratificationAllowed`            | `Y`, `N`                                                                                                                                                                     | Whether a ward tier may ride as `item.modifier`                                                                                       |
| `MultipleImplantsAllowed`          | `N`                                                                                                                                                                          | Whether more than one implant may be added                                                                                            |
| `MultipleStratificationAllowed`    | `Y`, `N`                                                                                                                                                                     | Whether more than one ward tier may be added                                                                                          |
| `MaximumImplantsAllowed`           | `1`, `0`                                                                                                                                                                     | Cap on the number of implants                                                                                                         |
| `MaximumStratificationAllowed`     | `1`, `0`                                                                                                                                                                     | Cap on the number of ward tiers                                                                                                       |
| `CyclicProcedure`                  | `N`, `Y`                                                                                                                                                                     | Repeatable under one approval, one supporting-info entry per cycle                                                                    |
| `MaximumCyclesAllowed`             | `0`, `6`                                                                                                                                                                     | Cap on the number of cycles                                                                                                           |
| `Standalone`                       | `N`                                                                                                                                                                          | Refuse any other package alongside it                                                                                                 |
| `ParentProcedure`                  | `NA`, `IN015A,SB003C,SB015C,SB072A,SB088MLA,SB103MLC,SB106MLA,SL038MLA,SM001MLA,SM003B…`, `IN058A,IN071A,MC023MLA,SB095MLB,SB100MLB,SB108MLA,SE012MLA,SM007B,SM027MLA,SN05…` | On an implant, the package it may accompany                                                                                           |
| `Unspecified`                      | `N`, `Y`                                                                                                                                                                     | Free-text name and free-entry amount, validated against the wallet                                                                    |
| `LamaDamaProcedure`                | `Y`                                                                                                                                                                          | Offer only on a LAMA or DAMA discharge                                                                                                |
| `DischargeStagesLamaDamaProcedure` | `Before Surgery, During Surgery`                                                                                                                                             | The discharge stages at which a LAMA or DAMA package may be billed, before or during surgery                                          |
| `LengthOfStay`                     | not carried                                                                                                                                                                  | Maximum length of stay; bounds the days claimed, the `LM100` count included                                                           |

## Supporting-information requirements

| Code       | Display                                                                          | Stage | System                                                                  |
| ---------- | -------------------------------------------------------------------------------- | ----- | ----------------------------------------------------------------------- |
| `POI`      | Proof of identity                                                                | any   | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `ADN`      | Aadhaar Number                                                                   | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `INF`      | Additional info related to claim ( conveying additional situation and condition… | any   | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `ODN`      | Other document                                                                   | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `DIA`      | Diagnostic report                                                                | any   | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `MAND0409` | any investigations done                                                          | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0064` | All investigations reports                                                       | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0006` | Detailed discharge summary                                                       | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0062` | Detailed ICPs                                                                    | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0063` | Treatment details                                                                | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `CD`       |                                                                                  | any   | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `MAND0408` | Clinical notes detailing history and Admission notes showing vitals and examina… | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `STG`      | Standard Treatment Guidelines                                                    | any   | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `MAND0952` | MLC/ FIR +/- Nerve conduction velocity (NCV) + /- MRI + /- MRA + /- EMG (Electr… | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0300` | Detailed operatives notes                                                        | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0309` | Intra operative still photograph                                                 | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0946` | Clinical notes detailing the injury and need of surgery                          | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `HDS`      |                                                                                  | any   | `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category` |
| `MAND0368` | Procedure / Operative Notes, Detailed Discharge Summary                          | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND1045` | Clinical notes with planned line of treatment (including indication for need of… | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0384` | MLC/ FIR if traumatic                                                            | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0592` | X Ray of affected limb                                                           | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0008` | Detailed Procedure / Operative Notes                                             | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0112` | Post Procedure clinical photgraph                                                | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0582` | clinical photograph of affected part                                             | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0604` | clinical notes justifying the indication                                         | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0067` | CBC                                                                              | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0459` | CECT Thorax, abdomen and Pelvis                                                  | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0564` | histopathology (non small cell - adenocarcinoma or adenosquamous carcinoma)      | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0074` | LFT                                                                              | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0457` | RBS                                                                              | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0447` | RFT                                                                              | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0099` | BAR CODE OF THE DRUGS                                                            | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0102` | CHARTS OF CHEMOTHERAPY REGIMEN                                                   | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0101` | DISCHARGE SUMMARY OF INPATIENT DEPARTMENT / DISCHARGE SUMMARY OF DAY CARE DEPAR… | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0100` | REPORTS OF THE TESTS (PATHOLOGY, RADIOLOGY, MICROBIOLOGY, HEMATOLOGY, BIOCHEMIS… | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0103` | TRANFUSION SLIPS                                                                 | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0189` | Histopathology report                                                            | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0226` | Post Procedure Photograph of affected part                                       | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0030` | Procedure / Operative Notes                                                      | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0822` | Clinical notes with planned line of treatment justifying indication              | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0647` | FIR/MLC in case of accident                                                      | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0161` | operative notes                                                                  | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0159` | Still image of the the procedure with pt. ID and date                            | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0003` | Clinical notes                                                                   | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0588` | clinical photograph                                                              | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0649` | doctors notes                                                                    | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0648` | Patient details                                                                  | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0650` | photo                                                                            | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0162` | Discharge notes                                                                  | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0163` | microbiology report                                                              | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0164` | Still image of the patient undergoing the procedure with date stamp              | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0622` | CECT                                                                             | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0621` | FNAC/ BIOPSY                                                                     | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0152` | HPE report                                                                       | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0151` | Post Procedure Photographs of surgical site                                      | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0339` | Clinical notes with planned line of treatment                                    | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0831` | Audiogram report justfying surgery                                               | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0832` | CT- TEMPORAL BONE of affected side /X-RAY BOTH MASTOIDS                          | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0730` | USG/CT Abdomen                                                                   | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0327` | Detailed discharge summary;                                                      | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |
| `MAND0326` | Reports of all investigations done and consultation paper of treating doctor me… | any   | `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-supportinginfo-code`       |

5 of the requirements link a questionnaire through `documentationUrl`.

## Questionnaires

| Title                 | Items | Item types                         | Question in |
| --------------------- | ----- | ---------------------------------- | ----------- |
| Discharge Information | 7     | `attachment`, `choice`, `dateTime` | `text`      |
| General Findings      | 9     | `string`, `choice`                 | `text`      |
| Personal History      | 6     | `choice`                           | `text`      |
| Family History        | 7     | `choice`                           | `text`      |
| Admission Details     | 4     | `dateTime`, `choice`               | `text`      |

## Rules

### Two parallel structures

`coverage[]` carries the rules: flags, document requirements, questionnaire links and `limit[]` rates. `plan[].specificCost[]` carries the money: `cost[]` lines by type. Both hold the same package codes. Index both by package code and join; neither is complete alone.

### Categories

`coverage[].type` and `specificCost[].category` bind to `https://nrces.in/ndhm/fhir/r4/ValueSet/ndhm-benefitcategory`. Codes beginning `S` are surgical, `M` medical.

### Flags are strings

Every flag except `ParentProcedure` is a `valueString`. `"N"` is truthy in most languages; compare against the literal `"Y"`.

### Cost lines

`Procedure` is the base package rate. `Stratification` is the rate for a ward tier, named in `cost.qualifiers[]`. `Implant` is added over the package rate.

### A zero base rate

A base limit of 0 means the payable amount is set entirely by the ward tier chosen. It is not missing data. Never submit a zero-value item.

### Document requirements come in two shapes

Nested, one sub-extension per document, and flat, with `category`, `code` and `documentationUrl` directly under the extension. Recurse, or one shape is silently dropped.

### Where the question is

Policy-level questionnaires put the question in `item.text`, STG questionnaires in `item.prefix`. Read `text` and fall back to `prefix`.

### Implant codes repeat

Once per parent procedure they may accompany. Key on the package code with its parent, or on the element `id`.

### Extension urls change form

The absolute `https://nrces.in/ndhm/fhir/r4/StructureDefinition/Claim-Condition` and the relative `claim-condition` both occur. Match on the last segment.

## PMJAY

This is the PMJAY shape; the rules above are PMJAY's.


---

# Payment notice and acknowledgement

The payer's notice that money has moved against an approved claim, and the provider's acknowledgement. The only exchange that carries actual money rather than an adjudicated figure.

## The notice

Sent on `/v1/paymentnotice/request`, workflow 30 initiated, 31 processed, 33 settled.

### The bundle

| # | Resource                | Profile                                                                                                                    |
| - | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| 1 | `Task`                  | none declared; NRCeS [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)                                   |
| 2 | `PaymentNotice`         | none declared; NRCeS [PaymentNotice](https://nrces.in/ndhm/fhir/r4/StructureDefinition-PaymentNotice.html)                 |
| 3 | `PaymentReconciliation` | none declared; NRCeS [PaymentReconciliation](https://nrces.in/ndhm/fhir/r4/StructureDefinition-PaymentReconciliation.html) |
| 4 | `Organization (prov)`   | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                   |
| 5 | `Organization (pay)`    | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                   |

### Elements

#### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                  | Example                                                                                |
| ------------------------ | -------------------------------------------------------------------------------------- |
| `status`                 | `requested`                                                                            |
| `intent`                 | `order`                                                                                |
| `code.coding[]`          | `deliver` deliver in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-codes`        |
| `description`            | `Settled in full: INR 135000 paid against INR 150000 approved.`                        |
| `authoredOn`             | `2026-09-10T23:53:39+05:30`                                                            |
| `requester`              | reference `<participant-defined>`                                                      |
| `owner`                  | reference `<participant-defined>`                                                      |
| `input[].type.coding[]`  | `status` Status code in `http://terminology.hl7.org/CodeSystem/financialtaskinputtype` |
| `input[].valueReference` | reference `<participant-defined>`                                                      |

#### PaymentNotice

NRCeS profile: [PaymentNotice](https://nrces.in/ndhm/fhir/r4/StructureDefinition-PaymentNotice.html).

| Element                      | Example                                                                                    |
| ---------------------------- | ------------------------------------------------------------------------------------------ |
| `identifier[]`               | system `<participant-defined>`, value `NM-26-0SE00002L`                                    |
| `identifier[].type.coding[]` | `CLN` Claim number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code` |
| `status`                     | `active`                                                                                   |
| `created`                    | `2026-09-10T23:53:39+05:30`                                                                |
| `payment`                    | reference `<participant-defined>`                                                          |
| `recipient`                  | reference `<participant-defined>`                                                          |
| `amount`                     | value `135000`, currency `INR`                                                             |
| `paymentStatus.coding[]`     | `cleared` Cleared in `http://terminology.hl7.org/CodeSystem/paymentstatus`                 |

#### PaymentReconciliation

NRCeS profile: [PaymentReconciliation](https://nrces.in/ndhm/fhir/r4/StructureDefinition-PaymentReconciliation.html).

| Element                             | Example                                                                                                     |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `identifier[]`                      | system `<participant-defined>`, value `NM-26-0SE00002L`                                                     |
| `identifier[].type.coding[]`        | `CLN` Claim number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`                  |
| `status`                            | `active`                                                                                                    |
| `created`                           | `2026-09-10T23:53:39+05:30`                                                                                 |
| `disposition`                       | `Settled in full: INR 135000 paid against INR 150000 approved.`                                             |
| `paymentDate`                       | `2026-09-10`                                                                                                |
| `paymentAmount`                     | value `135000`, currency `INR`                                                                              |
| `paymentIdentifier`                 | system `<participant-defined>`, value `UTR1789064619092`                                                    |
| `paymentIdentifier.type.coding[]`   | `UTR` Unique Transaction Reference in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`  |
| `detail[]`                          | id `PAY-2026-0009/TDS`, date `2026-09-10`                                                                   |
|                                     | id `PAY-2026-0009/Payment`, date `2026-09-10`                                                               |
| `detail[].identifier`               | system `<participant-defined>`, value `PAY-2026-0009/TDS`                                                   |
|                                     | system `<participant-defined>`, value `PAY-2026-0009/Payment`                                               |
| `detail[].identifier.type.coding[]` | `PLAC` Placer Identifier in `https://https://nrces.in/ndhm/fhir/r4/ValueSet-ndhm-identifier-type-code.html` |
| `detail[].type.coding[]`            | `TDS` TDS in `http://hl7.org/fhir/ValueSet/payment-type`                                                    |
|                                     | `Payment` Payment in `http://hl7.org/fhir/ValueSet/payment-type`                                            |
| `detail[].amount`                   | value `15000`                                                                                               |
|                                     | value `135000`                                                                                              |

The `Organization` entries are shaped as in the chapters that introduce them.

## The acknowledgement

Sent on `/v1/paymentnotice/on_request`, workflow 30 echoed; 17 under PMJAY.

### The bundle

| # | Resource              | Profile                                                                             |
| - | --------------------- | ----------------------------------------------------------------------------------- |
| 1 | `Task`                | [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)                 |
| 2 | `Organization (prov)` | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html) |
| 3 | `Organization (pay)`  | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html) |

### Elements

#### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                                  | Example                                                                                                   |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `status`                                 | `completed`                                                                                               |
| `intent`                                 | `order`                                                                                                   |
| `code.coding[]`                          | `status` in `http://terminology.hl7.org/CodeSystem/financialtaskcode`                                     |
| `authoredOn`                             | `2026-09-10T23:53:40+05:30`                                                                               |
| `requester`                              | reference `https://nhcx.abdm.gov.in/provider`                                                             |
| `owner`                                  | reference `https://nhcx.abdm.gov.in/payer`                                                                |
| `description`                            | `Received the payment for claim NM-26-0SE00002L`                                                          |
| `output[].type.coding[]`                 | `status` Status in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-output-type`                       |
|                                          | `claimNumber` ClaimNumber in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-input-type-code`         |
| `output[].valueCodeableConcept.coding[]` | `paymentack` Payment is acknowledged in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-output-value` |
| `output[]`                               | valueString `NM-26-0SE00002L`                                                                             |

The `Organization` entries are shaped as in the chapters that introduce them.

## Rules

### The notice

A `Task` coded `deliver` in `ndhm-task-codes` whose input references the `PaymentNotice`. `PaymentNotice.amount` is the net that reaches the account. `PaymentReconciliation` carries the payment date, the `UTR` and one `detail[]` line per money type.

### The arithmetic

Net plus the deductions equals the adjudicated benefit, not the submitted amount. Run the check on every notice and flag a case that fails it.

### The acknowledgement

A `Task` coded `status` in `financialtaskcode`, `completed`, with an output `paymentack` and the claim number as a second output. It confirms receipt, not agreement.

### Three notices

30, 31 and 33, each with its own correlation id. The bank reference arrives on 33. Keep the path for the acknowledgement configurable per payer.

## PMJAY

The generic bundle above is what every payer takes, IRDAI-regulated insurers and TPAs included. PMJAY takes it with the changes and requirements below.

### What changes in the bundle

#### The notice

##### Systems PMJAY binds differently

| Element                                     | Generic                 | PMJAY                                          |
| ------------------------------------------- | ----------------------- | ---------------------------------------------- |
| `PaymentNotice.identifier[]`                | `<participant-defined>` | `https://hcx.pmjay.gov.in/v1/preauthorization` |
| `PaymentReconciliation.identifier[]`        | `<participant-defined>` | `https://hcx.pmjay.gov.in/v1/preauthorization` |
| `PaymentReconciliation.paymentIdentifier`   | `<participant-defined>` | `https://payer.gov.in`                         |
| `PaymentReconciliation.detail[].identifier` | `<participant-defined>` | `https://hcx.pmjay.gov.in/v1/claim`            |

#### The acknowledgement

The PMJAY bundle has the same resources, elements and systems as the generic one.

### What PMJAY specifies

- Deduction lines use the scheme's own codes, such as `RF`, beside the `Payment` line.
- The notice names the claim under `https://hcx.pmjay.gov.in/v1/preauthorization`.
- Before 33 the `UTR` field can carry a scheme reference rather than a bank reference. Store it; reconcile against the bank only on 33.

### What PMJAY requires

- Acknowledge each notice on 17.
- Keep the UTR from 33; the shortfall window opens only once 33 is acknowledged.

## Use cases, APIs and data elements

### C9 Send payment notice (payer)

The money, on a new thread of its own, with the reconciliation itemised by type: approved, claimed, tds, servicetax, advance, recovered, penality. The bank's UTR rides on the settled notice.

|                    |                                                                                                                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/paymentnotice/request` [`apis/06-payment-notice/v1-paymentnotice-request.bru`](/docs/nhcx/v1/api/payment-notice/endpoints/payment-notice-v1-paymentnotice-request)          |
| **Callback**       | `/v1/paymentnotice/on_request` [`apis/06-payment-notice/v1-paymentnotice-on-request.bru`](/docs/nhcx/v1/api/payment-notice/endpoints/payment-notice-v1-paymentnotice-on-request) |
| **Workflow**       | 30 initiated, 31 processed, 33 settled                                                                                                                                           |
| **Carries JWE**    | yes                                                                                                                                                                              |
| **Focal resource** | `PaymentReconciliation`                                                                                                                                                          |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1518@hcx`          |
| `x-hcx-recipient_code` | `1000004446@hcx`    |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `30`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |

**Workflow codes**

| Code | Name              | Authored by | `x-hcx-status`                                            | Means                                       |
| ---- | ----------------- | ----------- | --------------------------------------------------------- | ------------------------------------------- |
| `30` | Payment Initiated | payer       | `request.initiated`, `response.partial`, `response.error` | Payment initiated by payer, on a new thread |
| `31` | Payment Processed | payer       | `request.initiated`                                       | Payment has been processed                  |
| `33` | Payment Settled   | payer       | `request.initiated`                                       | Payment has been fully settled              |

**Data elements**

| Element         | Label                        | Group          | Type      | Card.  | FHIR path                                             | Example            | Notes |
| --------------- | ---------------------------- | -------------- | --------- | ------ | ----------------------------------------------------- | ------------------ | ----- |
| `utrNumber`     | Bank UTR Number              | Payment        | `string`  | `1..1` | `PaymentReconciliation.paymentIdentifier.value`       | `CMS2602260081728` |       |
| `paymentDate`   | Remittance Date              | Payment        | `date`    | `1..1` | `PaymentReconciliation.paymentDate`                   | `2026-03-05`       |       |
| `settledAmount` | Net Bank Remittance Amount   | Payment        | `decimal` | `1..1` | `PaymentReconciliation.paymentAmount.value`           | `14850.00`         |       |
| `tdsDeduction`  | Tax Deducted at Source (TDS) | Payment Detail | `decimal` | `0..1` | `PaymentReconciliation.detail[type=tds].amount.value` | `650.00`           |       |

NRCeS profiles: [PaymentReconciliation](https://nrces.in/ndhm/fhir/r4/StructureDefinition-PaymentReconciliation.html).

### B7 Acknowledge payment notice (provider)

The receipt for a payment notice, as a Task on this endpoint. The notice arrives on a new thread of its own; a generic payer takes the acknowledgement with the notice's 30 echoed, PMJAY with 17.

|                    |                                                                                                                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/paymentnotice/on_request` [`apis/06-payment-notice/v1-paymentnotice-on-request.bru`](/docs/nhcx/v1/api/payment-notice/endpoints/payment-notice-v1-paymentnotice-on-request) |
| **Callback**       | `/v1/paymentnotice/request` [`apis/06-payment-notice/v1-paymentnotice-request.bru`](/docs/nhcx/v1/api/payment-notice/endpoints/payment-notice-v1-paymentnotice-request)          |
| **Workflow**       | 30 echoed from the notice on the generic network; 17 under PMJAY                                                                                                                 |
| **Carries JWE**    | yes                                                                                                                                                                              |
| **Focal resource** | `PaymentReconciliation / Task`                                                                                                                                                   |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `17`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `response.complete` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |
| `x-hcx-debug_flag`     | `INFO`              |

**Workflow codes**

| Code | Name              | Authored by | `x-hcx-status`                                            | Means                                                                                             |
| ---- | ----------------- | ----------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `30` | Payment Initiated | payer       | `request.initiated`, `response.partial`, `response.error` | Payment initiated by payer, on a new thread                                                       |
| `17` | Payment Received  | provider    | `response.complete`                                       | Payment received acknowledgment under PMJAY; a generic payer takes it with the notice's 30 echoed |

**Data elements**

| Element            | Label                 | Group      | Type     | Card.  | FHIR path                                   | Example           | Notes |
| ------------------ | --------------------- | ---------- | -------- | ------ | ------------------------------------------- | ----------------- | ----- |
| `settlementNumber` | Payment Reference     | Settlement | `string` | `1..1` | `PaymentReconciliation.identifier[0].value` | `SETTLE-2026-001` |       |
| `status`           | Acknowledgment Status | Settlement | `code`   | `1..1` | `PaymentReconciliation.status`              | `active`          |       |

NRCeS profiles: [PaymentReconciliation](https://nrces.in/ndhm/fhir/r4/StructureDefinition-PaymentReconciliation.html).

### D13 Acknowledge the payment notice (pmjay)

Three notices may arrive: 30 when the transfer is initiated, 31 when the bank processes it, 33 when it settles with the UTR. The reconciliation splits the amount into what was paid and what was deducted as tax. Keep the UTR; it is the reference for any dispute.

|                       |                                                                                                                                                                                  |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API**               | `/v1/paymentnotice/on_request` [`apis/06-payment-notice/v1-paymentnotice-on-request.bru`](/docs/nhcx/v1/api/payment-notice/endpoints/payment-notice-v1-paymentnotice-on-request) |
| **Callback**          | `/v1/paymentnotice/request` [`apis/06-payment-notice/v1-paymentnotice-request.bru`](/docs/nhcx/v1/api/payment-notice/endpoints/payment-notice-v1-paymentnotice-request)          |
| **Workflow**          | 17                                                                                                                                                                               |
| **Carries JWE**       | yes                                                                                                                                                                              |
| **Focal resource**    | `PaymentReconciliation / Task`                                                                                                                                                   |
| **Simulator console** | `/builder?family=paymentnotice&usecase=acknowledge`                                                                                                                              |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `17`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `response.complete` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |
| `x-hcx-debug_flag`     | `INFO`              |

**Workflow codes**

| Code | Name             | Authored by | `x-hcx-status`      | Means                                                                                             |
| ---- | ---------------- | ----------- | ------------------- | ------------------------------------------------------------------------------------------------- |
| `17` | Payment Received | provider    | `response.complete` | Payment received acknowledgment under PMJAY; a generic payer takes it with the notice's 30 echoed |

**Data elements**

| Element            | Label                    | Group   | Type     | Card.  | FHIR path                                   | Example            | Notes |
| ------------------ | ------------------------ | ------- | -------- | ------ | ------------------------------------------- | ------------------ | ----- |
| `settlementNumber` | Settlement Advice Number | Payment | `string` | `1..1` | `PaymentReconciliation.identifier[0].value` | `SETTLE-PMJAY-001` |       |
| `workflowId`       | Workflow Code            | Header  | `string` | `1..1` | `Header.x-hcx-workflow_id`                  | `17`               |       |

NRCeS profiles: [PaymentReconciliation](https://nrces.in/ndhm/fhir/r4/StructureDefinition-PaymentReconciliation.html).


---

# Preauthorisation enhancement

Extends an approved preauthorisation: a longer stay or an added package. The same endpoint and the same case number, under workflow 13, with the header `x-hcx-use_case: Enhancement` and a new correlation id.

Sent on `/v1/preauth/submit`, answered on `/v1/preauth/on_submit`, workflow 13, and 131 to answer an enhancement query.

## The bundle

| # | Resource                | Profile                                                                                                                                      |
| - | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | `Claim`                 | [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html)                                                                        |
| 2 | `Patient`               | [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)                                                                    |
| 3 | `Organization (prov)`   | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                                                          |
| 4 | `Organization (pay)`    | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                                                          |
| 5 | `Coverage`              | [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)                                                                  |
| 6 | `Practitioner`          | [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html)                                                          |
| 7 | `Procedure`             | [Procedure](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Procedure.html)                                                                |
| 8 | `Procedure`             | [Procedure](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Procedure.html)                                                                |
| 9 | `QuestionnaireResponse` | `QuestionnaireResponse`, which NRCeS does not publish; base FHIR [QuestionnaireResponse](https://hl7.org/fhir/R4/questionnaireresponse.html) |

## Elements

### Claim

NRCeS profile: [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html).

| Element                                         | Example                                                                                                                                                                                  |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `identifier[]`                                  | system `https://nhcx.abdm.gov.in`, value `NM-26-0SE00002G`                                                                                                                               |
| `identifier[].type.coding[]`                    | `CLN` Claim number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`                                                                                               |
| `status`                                        | `active`                                                                                                                                                                                 |
| `type.coding[]`                                 | `737481003` Inpatient care management (procedure) in `http://snomed.info/sct`                                                                                                            |
| `use`                                           | `preauthorization`                                                                                                                                                                       |
| `patient`                                       | reference `https://nhcx.abdm.gov.in/patient`                                                                                                                                             |
| `billablePeriod`                                | start `2026-09-10T00:00:00+05:30`, end `2026-09-10T00:00:00+05:30`                                                                                                                       |
| `created`                                       | `2026-09-10T23:50:33+05:30`                                                                                                                                                              |
| `insurer`                                       | reference `https://nhcx.abdm.gov.in/payer`                                                                                                                                               |
| `provider`                                      | reference `https://nhcx.abdm.gov.in/provider`                                                                                                                                            |
| `priority.coding[]`                             | `normal` Normal in `http://terminology.hl7.org/CodeSystem/processpriority`                                                                                                               |
| `careTeam[]`                                    | sequence `1`                                                                                                                                                                             |
| `careTeam[].provider`                           | reference `https://nhcx.abdm.gov.in/practitioner`                                                                                                                                        |
| `careTeam[].role.coding[]`                      | `primary` Primary provider in `http://terminology.hl7.org/CodeSystem/claimcareteamrole`                                                                                                  |
| `careTeam[].qualification.coding[]`             | `394802001` General medicine in `http://snomed.info/sct`                                                                                                                                 |
| `supportingInfo[]`                              | id `SupportingInformation/1`, sequence `1`                                                                                                                                               |
|                                                 | id `SupportingInformation/2`, sequence `2`                                                                                                                                               |
|                                                 | id `SupportingInformation/3`, sequence `3`                                                                                                                                               |
|                                                 | and 8 more                                                                                                                                                                               |
| `supportingInfo[].category.coding[]`            | `INV` Document Type - Investigation in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`                                                                           |
|                                                 | `ONS` Period, start or end dates of aspects of the Condition. (e.g. admission, discha… in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`                        |
|                                                 | `OTH` Other in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`                                                                                                   |
|                                                 | and 1 more                                                                                                                                                                               |
| `supportingInfo[].code.coding[]`                | `POI` Proof of Identity (Aadhaar / Passport / Voter ID) in `https://nhcx.abdm.gov.in/document-code`                                                                                      |
|                                                 | `CER` Medical Certificate / Doctor Referral in `https://nhcx.abdm.gov.in/document-code`                                                                                                  |
|                                                 | `RAD` Radiology / X-Ray / CT / MRI Scan Reports in `https://nhcx.abdm.gov.in/document-code`                                                                                              |
|                                                 | and 8 more                                                                                                                                                                               |
| `supportingInfo[].valueAttachment`              | contentType `application/pdf`, title `Proof of Identity (Aadhaar / Passport / Voter ID)`                                                                                                 |
|                                                 | contentType `application/pdf`, title `Medical Certificate / Doctor Referral`                                                                                                             |
|                                                 | contentType `application/pdf`, title `Radiology / X-Ray / CT / MRI Scan Reports`                                                                                                         |
|                                                 | and 5 more                                                                                                                                                                               |
| `supportingInfo[].valueReference`               | reference `https://nhcx.abdm.gov.in/questionnaireresponse/1`, display `Total Knee Replacement (Unilateral), Standard Treatment Guidelines`                                               |
| `diagnosis[]`                                   | sequence `1`                                                                                                                                                                             |
| `diagnosis[].diagnosisCodeableConcept.coding[]` | `E11.9` Type 2 diabetes mellitus without complications in `http://hl7.org/fhir/sid/icd-10`                                                                                               |
| `diagnosis[].type[].coding[]`                   | `admitting` Admitting Diagnosis in `http://terminology.hl7.org/CodeSystem/ex-diagnosistype`                                                                                              |
| `diagnosis[].onAdmission.coding[]`              | `yes` Yes in `http://terminology.hl7.org/CodeSystem/ex-diagnosis-on-admission`                                                                                                           |
| `procedure[]`                                   | id `Procedure/1`, sequence `1`, date `2026-09-10T00:00:00+05:30`                                                                                                                         |
|                                                 | id `Procedure/2`, sequence `2`, date `2026-09-10T00:00:00+05:30`                                                                                                                         |
| `procedure[].type[].coding[]`                   | `surgical` Surgical in `https://nhcx.abdm.gov.in/procedure-type`                                                                                                                         |
| `procedure[].procedureReference`                | reference `https://nhcx.abdm.gov.in/procedure/1`, display `Total Knee Replacement (Unilateral)`                                                                                          |
|                                                 | reference `https://nhcx.abdm.gov.in/procedure/2`, display `Acute Appendectomy (Laparoscopic)`                                                                                            |
| `insurance[]`                                   | sequence `1`, focal `true`                                                                                                                                                               |
| `insurance[].coverage`                          | reference `https://nhcx.abdm.gov.in/coverage`                                                                                                                                            |
| `item[]`                                        | id `Item/1`, sequence `1`, factor `1`, careTeamSequence `1`, diagnosisSequence `1`, procedureSequence `1`, informationSequence `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`   |
|                                                 | id `Item/2`, sequence `2`, factor `0.5`, careTeamSequence `1`, diagnosisSequence `1`, procedureSequence `2`, informationSequence `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11` |
| `item[].productOrService.coding[]`              | `PROC-KNEE-01` Total Knee Replacement (Unilateral) in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-procedure-code`                                                                     |
|                                                 | `PROC-APP-02` Acute Appendectomy (Laparoscopic) in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-procedure-code`                                                                        |
| `item[].servicedPeriod`                         | start `2026-09-10`, end `2026-09-10`                                                                                                                                                     |
| `item[].quantity`                               | value `1`                                                                                                                                                                                |
| `item[].unitPrice`                              | value `150000`, currency `INR`                                                                                                                                                           |
|                                                 | value `45000`, currency `INR`                                                                                                                                                            |
| `item[].net`                                    | value `150000`, currency `INR`                                                                                                                                                           |
|                                                 | value `45000`, currency `INR`                                                                                                                                                            |
| `item[].category.coding[]`                      | `Surgical` Surgical in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-benefit-category`                                                                                                  |
| `total`                                         | value `195000`, currency `INR`                                                                                                                                                           |

### Patient

NRCeS profile: [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html).

| Element                      | Example                                                                                                                      |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `identifier[]`               | value `MRAV1985001`                                                                                                          |
|                              | value `91-1234-1234-1234`                                                                                                    |
| `identifier[].type.coding[]` | `PMJAY` Pradhan Mantri Jan Aarogya Yojana (PMJAY) ID in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code` |
|                              | `ABHA` Ayushman Bharat Health Account (ABHA) ID in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`      |
|                              | `MB` Member Number in `http://terminology.hl7.org/CodeSystem/v2-0203`                                                        |
| `name[]`                     | text `<patient name>`                                                                                                        |
| `telecom[]`                  | system `phone`, value `9876543210`                                                                                           |
| `gender`                     | `male`                                                                                                                       |
| `birthDate`                  | `1985-06-15`                                                                                                                 |

### Organization (prov)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `identifier[]`               | system `https://nhcx.abdm.gov.in`, value `IN1910000151`                                 |
| `identifier[].type.coding[]` | `NPI` National provider identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`   |
| `type[].coding[]`            | `prov` Healthcare Provider in `http://terminology.hl7.org/CodeSystem/organization-type` |
| `name`                       | `KyroCare Multispeciality Hospital`                                                     |

### Organization (pay)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                               |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `identifier[]`               | system `https://nhcx.abdm.gov.in`, value `1000004805`                                                 |
| `identifier[].type.coding[]` | `NIIP` National Insurance Payor Identifier (Payor) in `http://terminology.hl7.org/CodeSystem/v2-0203` |
| `type[].coding[]`            | `pay` Payer in `http://terminology.hl7.org/CodeSystem/organization-type`                              |
| `name`                       | `Sandbox Payer`                                                                                       |

### Coverage

NRCeS profile: [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html).

| Element                      | Example                                                                                  |
| ---------------------------- | ---------------------------------------------------------------------------------------- |
| `identifier[]`               | value `POL7UMU001`                                                                       |
| `identifier[].type.coding[]` | `NH` National Health Plan Identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`  |
| `status`                     | `active`                                                                                 |
| `type.coding[]`              | `HIP` health insurance plan policy in `http://terminology.hl7.org/CodeSystem/v3-ActCode` |
| `subscriber`                 | reference `https://nhcx.abdm.gov.in/patient`                                             |
| `subscriberId`               | `MRAV1985001`                                                                            |
| `beneficiary`                | reference `https://nhcx.abdm.gov.in/patient`                                             |
| `relationship.coding[]`      | `self` in `http://terminology.hl7.org/CodeSystem/subscriber-relationship`                |
| `payor[]`                    | reference `https://nhcx.abdm.gov.in/payer`                                               |

### Practitioner

NRCeS profile: [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html).

| Element                         | Example                                                                                                              |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `identifier[]`                  | system `https://nhcx.abdm.gov.in`, value `71-8422-5818-7201`                                                         |
|                                 | system `https://hpr.abdm.gov.in`, value `71-8422-5818-7201`                                                          |
| `identifier[].type.coding[]`    | `HPID` Healthcare Professional ID (HPID) in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`     |
|                                 | `HPIN` Health Practitioner ID issued by NDHM in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code` |
| `name[]`                        | text `Dr. Ananya Rao`                                                                                                |
| `qualification[].code.coding[]` | `MD` Doctor of Medicine in `http://terminology.hl7.org/CodeSystem/v2-0360`                                           |

### Procedure

NRCeS profile: [Procedure](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Procedure.html).

| Element             | Example                                                      |
| ------------------- | ------------------------------------------------------------ |
| `status`            | `preparation`                                                |
| `code`              | text `Total Knee Replacement (Unilateral)`                   |
| `code.coding[]`     | `71388002` Procedure (procedure) in `http://snomed.info/sct` |
| `subject`           | reference `https://nhcx.abdm.gov.in/patient`                 |
| `performedDateTime` | `2026-09-10T00:00:00+05:30`                                  |

### Procedure

NRCeS profile: [Procedure](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Procedure.html).

| Element             | Example                                                      |
| ------------------- | ------------------------------------------------------------ |
| `status`            | `preparation`                                                |
| `code`              | text `Acute Appendectomy (Laparoscopic)`                     |
| `code.coding[]`     | `71388002` Procedure (procedure) in `http://snomed.info/sct` |
| `subject`           | reference `https://nhcx.abdm.gov.in/patient`                 |
| `performedDateTime` | `2026-09-10T00:00:00+05:30`                                  |

### QuestionnaireResponse

| Element           | Example                                                                                                              |
| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| `questionnaire`   | `<participant-defined>`                                                                                              |
| `status`          | `completed`                                                                                                          |
| `subject`         | reference `https://nhcx.abdm.gov.in/patient`                                                                         |
| `authored`        | `2026-09-10T23:50:33+05:30`                                                                                          |
| `item[]`          | linkId `PROC-KNEE-01/stg/1`, text `Duration of symptoms and the conservative treatment tried (months of physiother…` |
|                   | linkId `PROC-KNEE-01/stg/2`, text `Kellgren-Lawrence grade of osteoarthritis on the standing X-ray`                  |
|                   | linkId `PROC-KNEE-01/stg/3`, text `Range of motion and deformity of the knee (flexion contracture, varus/valgus)`    |
|                   | and 2 more                                                                                                           |
| `item[].answer[]` | valueString `Recorded.`                                                                                              |

## Rules

### The protocol says enhancement, not the payload

`Claim.use` stays `preauthorization` and the case number is unchanged. The workflow code and `x-hcx-use_case` declare the enhancement.

### Cumulative

Carry the approved items and the ones now sought. `Claim.total` is the sum of all of them.

### No link in the payload

`Claim.related` is absent. The case number and your stored correlation ids are the thread.

### One at a time

Refused when there is no approval, when a request on the case is still open, or after the claim has been raised.

### Order

Response items can come back out of order; read by `itemSequence`. Order a case's messages by receipt, not by `Bundle.timestamp`.

## PMJAY

The generic bundle above is what every payer takes, IRDAI-regulated insurers and TPAs included. PMJAY takes it with the changes and requirements below.

### What changes in the bundle

#### Resources

- PMJAY adds 1 `QuestionnaireResponse`.

#### Elements PMJAY adds

| Element                                                 | Example                                                                                                                                |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `Claim.item[].modifier[].coding[]`                      | `STRAT006a` Routine Ward                                                                                                               |
| `Claim.item[].programCode[].coding[]`                   | `AB-PMJAY` Ayushman Bharat Pradhan Mantri Jan Arogya Yojana (AB-PMJAY) in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-program-code` |
| `QuestionnaireResponse.item[].answer[].valueAttachment` | contentType `application/pdf`, title `Medical Superintendent Declaration Form (During Admission)`                                      |

### What PMJAY specifies

- On the response, the `benefit` total is the increment and the wallet's `eligible` total is cumulative.
- The acknowledgement carries no `preAuthRef`. Carry the parent case id onto the enhancement yourself.
- A query on an enhancement arrives on 241 and is answered by a fresh submit on 131.

### What PMJAY requires

- Only packages flagged `EnhancementAllowed` `Y` may be added.
- One `Conservative` package per case. Refused with `PAYR-1245`.
- One request at a time on a case. Refused with `PAYR-1322`.

## Use cases, APIs and data elements

### D6 Raise an enhancement (pmjay)

Adds to an approved pre-authorisation, as many times as needed until discharge, one at a time, and only for packages whose plan flag allows it. The bundle carries the approved items and the ones now sought. A query on it arrives as a ClaimResponse on 241, on the case's own thread, and is answered by a fresh submit on 131.

|                       |                                                                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **API**               | `/v1/preauth/submit` [`apis/03-preauth/v1-preauth-enhancement.bru`](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-submit)     |
| **Callback**          | `/v1/preauth/on_submit` [`apis/03-preauth/v1-preauth-on-submit.bru`](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-on-submit) |
| **Workflow**          | 13, and 131 to answer an enhancement query raised on 241                                                                               |
| **Carries JWE**       | yes                                                                                                                                    |
| **Focal resource**    | `Claim`                                                                                                                                |
| **Simulator console** | `/builder?family=preauth&usecase=enhance`                                                                                              |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `13`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |
| `x-hcx-use_case`       | `Enhancement`       |

**Workflow codes**

| Code  | Name                                 | Authored by | `x-hcx-status`                                            | Means                                   |
| ----- | ------------------------------------ | ----------- | --------------------------------------------------------- | --------------------------------------- |
| `13`  | Enhancement Request Initiated        | provider    | `request.initiated`                                       | Enhancement (additional amount) request |
| `131` | Enhancement Query Response Submitted | provider    | `response.partial`, `response.error`, `response.complete` | Response to enhancement query           |
| `241` | Enhancement Request Queried          | payer       | `request.initiated`                                       | Enhancement request queried by payer    |

**Data elements**

| Element       | Label                      | Group  | Type     | Card.  | FHIR path                          | Example              | Notes |
| ------------- | -------------------------- | ------ | -------- | ------ | ---------------------------------- | -------------------- | ----- |
| `claimNumber` | Case Number                | Case   | `string` | `1..1` | `Claim.identifier[0].value`        | `VB26AA2600001`      |       |
| `preAuthRef`  | Initial Approval Reference | Case   | `string` | `1..1` | `Claim.insurance[0].preAuthRef[0]` | `APPR-2026-HP-00891` |       |
| `workflowId`  | Workflow Code              | Header | `string` | `1..1` | `Header.x-hcx-workflow_id`         | `13`                 |       |

NRCeS profiles: [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html).


---

# Preauthorisation query and answer

When the payer wants more before it decides. A private insurer raises the query as a communication and takes the answer as one. PMJAY raises it as a `ClaimResponse` on the case's own thread and takes the answer as the whole preauthorisation, resubmitted.

## The query

Sent on `/v1/communication/request`, workflow 24.

### The bundle

| # | Resource               | Profile                                                                                             |
| - | ---------------------- | --------------------------------------------------------------------------------------------------- |
| 1 | `Task`                 | [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)                                 |
| 2 | `CommunicationRequest` | [CommunicationRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CommunicationRequest.html) |
| 3 | `Claim`                | [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html)                               |
| 4 | `Patient`              | [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)                           |
| 5 | `Organization (ins)`   | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                 |
| 6 | `Organization (prov)`  | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                 |
| 7 | `Practitioner`         | [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html)                 |
| 8 | `Coverage`             | [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)                         |

### Elements

#### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                  | Example                                                                                                        |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `status`                 | `requested`                                                                                                    |
| `intent`                 | `order`                                                                                                        |
| `reasonCode.coding[]`    | `additionalinfo` Additional Information Request in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-reason-code` |
| `code.coding[]`          | `poll` in `http://terminology.hl7.org/CodeSystem/financialtaskcode`                                            |
| `description`            | `Share the pre-operative X-ray and the clinical notes.`                                                        |
| `authoredOn`             | `2026-09-10T23:51:47+05:30`                                                                                    |
| `requester`              | reference `urn:uuid:39cd4b51-bddd-5cc1-a65a-6fa4a2a83cb5`, display `Organization`                              |
| `owner`                  | reference `urn:uuid:84d112ec-041c-57f8-986c-6619ccd8245e`, display `Organization`                              |
| `input[].type.coding[]`  | `include` in `http://terminology.hl7.org/CodeSystem/financialtaskinputtype`                                    |
| `input[].valueReference` | reference `urn:uuid:4b35a6eb-3f99-5d0c-b0c8-5b2f049fdbde`, display `CommunicationRequest`                      |

#### CommunicationRequest

NRCeS profile: [CommunicationRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CommunicationRequest.html).

| Element                 | Example                                                                                                        |
| ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `identifier[]`          | value `NM-26-0SE00002I`                                                                                        |
| `basedOn[]`             | reference `urn:uuid:c1a17d6e-c718-58de-8d3d-fd4c0607d729`, display `Claim-preauth`                             |
| `status`                | `active`                                                                                                       |
| `category[].coding[]`   | `alert` in `http://terminology.hl7.org/CodeSystem/communication-category`                                      |
| `priority`              | `routine`                                                                                                      |
| `payload[]`             | contentString `Share the pre-operative X-ray and the clinical notes.`                                          |
| `authoredOn`            | `2026-09-10T23:51:47+05:30`                                                                                    |
| `requester`             | reference `urn:uuid:39cd4b51-bddd-5cc1-a65a-6fa4a2a83cb5`, display `Organization`                              |
| `recipient[]`           | reference `urn:uuid:84d112ec-041c-57f8-986c-6619ccd8245e`, display `Organization`                              |
| `sender`                | reference `urn:uuid:39cd4b51-bddd-5cc1-a65a-6fa4a2a83cb5`, display `Organization`                              |
| `reasonCode[]`          | text `Share the pre-operative X-ray and the clinical notes.`                                                   |
| `reasonCode[].coding[]` | `additionalinfo` Additional Information Request in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-reason-code` |

The `Claim`, `Patient`, `Organization`, `Practitioner`, `Coverage` entries are shaped as in the chapters that introduce them.

## The answer

Sent on `/v1/communication/on_request`, workflow 24, echoed.

### The bundle

| # | Resource               | Profile                                                                                             |
| - | ---------------------- | --------------------------------------------------------------------------------------------------- |
| 1 | `Task`                 | [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)                                 |
| 2 | `Communication`        | [Communication](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Communication.html)               |
| 3 | `CommunicationRequest` | [CommunicationRequest](https://nrces.in/ndhm/fhir/r4/StructureDefinition-CommunicationRequest.html) |
| 4 | `Claim`                | [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html)                               |
| 5 | `Patient`              | [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)                           |
| 6 | `Organization (prov)`  | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                 |
| 7 | `Organization (pay)`   | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                 |
| 8 | `Practitioner`         | [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html)                 |
| 9 | `Coverage`             | [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)                         |

### Elements

#### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                  | Example                                                                                                        |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `status`                 | `completed`                                                                                                    |
| `intent`                 | `order`                                                                                                        |
| `code.coding[]`          | `deliver` in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-codes`                                        |
| `authoredOn`             | `2026-09-10T23:51:53+05:30`                                                                                    |
| `requester`              | reference `https://nhcx.abdm.gov.in/provider`, display `Organization`                                          |
| `owner`                  | reference `https://nhcx.abdm.gov.in/payer`, display `Organization`                                             |
| `input[].type.coding[]`  | `include` in `http://terminology.hl7.org/CodeSystem/financialtaskinputtype`                                    |
| `input[].valueReference` | reference `urn:uuid:3e398f2b-ab14-41e5-8939-d7746eea43de`, display `Communication`                             |
| `reasonCode.coding[]`    | `additionalinfo` Additional Information Request in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-reason-code` |

#### Communication

NRCeS profile: [Communication](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Communication.html).

| Element                       | Example                                                                                                                        |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `identifier[]`                | value `NM-26-0SE00002I`                                                                                                        |
| `basedOn[]`                   | reference `urn:uuid:4b35a6eb-3f99-5d0c-b0c8-5b2f049fdbde`, display `CommunicationRequest`                                      |
| `inResponseTo[]`              | reference `urn:uuid:4b35a6eb-3f99-5d0c-b0c8-5b2f049fdbde`, display `CommunicationRequest`                                      |
| `about[]`                     | reference `https://nhcx.abdm.gov.in/preauth/request`, display `Claim urn:uuid:c1a17d6e-c718-58de-8d3d-fd4c0607d729`            |
| `status`                      | `completed`                                                                                                                    |
| `category[].coding[]`         | `notification` in `http://terminology.hl7.org/CodeSystem/communication-category`                                               |
| `priority`                    | `routine`                                                                                                                      |
| `recipient[]`                 | reference `https://nhcx.abdm.gov.in/payer`, display `Organization`                                                             |
| `sender`                      | reference `https://nhcx.abdm.gov.in/provider`, display `Organization`                                                          |
| `payload[]`                   | contentString `X-ray and clinical notes attached as asked.`                                                                    |
| `payload[].contentAttachment` | contentType `application/pdf`, title `Proof of Identity (Aadhaar / Passport / Voter ID)`, creation `2026-09-10T23:51:40+05:30` |
|                               | contentType `application/pdf`, title `Medical Certificate / Doctor Referral`, creation `2026-09-10T23:51:40+05:30`             |
|                               | contentType `application/pdf`, title `Radiology / X-Ray / CT / MRI Scan Reports`, creation `2026-09-10T23:51:40+05:30`         |
|                               | and 5 more                                                                                                                     |
| `payload[].extension[]`       | url `<participant-defined>`, valueString `POI`                                                                                 |
|                               | url `<participant-defined>`, valueString `CER`                                                                                 |
|                               | url `<participant-defined>`, valueString `RAD`                                                                                 |
|                               | and 5 more                                                                                                                     |

The `CommunicationRequest`, `Claim`, `Patient`, `Organization`, `Practitioner`, `Coverage` entries are shaped as in the chapters that introduce them.

## Rules

### The generic query

A `Task` coded `poll`, reason `additionalinfo`, with an `include` input referencing a `CommunicationRequest` whose `basedOn` names the preauthorisation. Sent on `/v1/communication/request` under 24.

### The generic answer

A `Task` coded `deliver` in `ndhm-task-codes`, `completed`, with an `include` input referencing a `Communication` whose `basedOn` names the request and whose `payload` carries the message and the documents. Posted on `/v1/communication/on_request`, echoing the correlation id and workflow id.

## PMJAY

The generic bundle above is what every payer takes, IRDAI-regulated insurers and TPAs included. PMJAY takes it with the changes and requirements below.

### What changes in the bundle

#### The query

PMJAY uses a different bundle for this step, headed by `ClaimResponse` rather than `Task`.

| # | Resource              | Profile                                                                                                    |
| - | --------------------- | ---------------------------------------------------------------------------------------------------------- |
| 1 | `ClaimResponse`       | none declared; NRCeS [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html) |
| 2 | `Patient`             | none declared; NRCeS [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)             |
| 3 | `Organization (pay)`  | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)   |
| 4 | `Organization (prov)` | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)   |
| 5 | `Coverage`            | none declared; NRCeS [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)           |

###### ClaimResponse

NRCeS profile: [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html).

| Element                                   | Example                                                                                      |
| ----------------------------------------- | -------------------------------------------------------------------------------------------- |
| `identifier[]`                            | system `https://hcx.pmjay.gov.in/v1/preauthorization`, value `NM-26-0SF000031`               |
| `identifier[].type.coding[]`              | `CLN` Claim number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`   |
| `status`                                  | `active`                                                                                     |
| `use`                                     | `preauthorization`                                                                           |
| `patient`                                 | reference `https://payer.nha.gov.in/preauthorization/v1/preauth/on_submit/claimresponse/pa…` |
| `created`                                 | `2026-09-11T00:33:03+05:30`                                                                  |
| `insurer`                                 | reference `https://payer.nha.gov.in/preauthorization/v1/preauth/on_submit/claimresponse/or…` |
| `requestor`                               | reference `https://payer.nha.gov.in/preauthorization/v1/preauth/on_submit/claimresponse/or…` |
| `outcome`                                 | `partial`                                                                                    |
| `disposition`                             | `query`                                                                                      |
| `preAuthRef`                              | `2026091110000817`                                                                           |
| `payeeType.coding[]`                      | `provider` Provider in `http://terminology.hl7.org/CodeSystem/payeetype`                     |
| `item[]`                                  | id `Item/Item/2`, itemSequence `2`                                                           |
|                                           | id `Item/Item/1`, itemSequence `1`                                                           |
| `item[].adjudication[].category.coding[]` | `submitted` Submitted Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`         |
|                                           | `eligible` Eligible Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`           |
|                                           | `reason` Reason for Adjudication in `https://hl7.org/fhir/R4/valueset-adjudication.html`     |
|                                           | and 3 more                                                                                   |
| `item[].adjudication[].amount`            | value `1500`                                                                                 |
|                                           | value `1725`                                                                                 |
|                                           | value `1800`                                                                                 |
|                                           | and 1 more                                                                                   |
| `item[].adjudication[].reason.coding[]`   | display `: Request acknowledged and accepted for further processing.`                        |
|                                           | `Queried` Queried                                                                            |
|                                           | `Approved` Approved                                                                          |
| `item[].adjudication[]`                   | value `0`                                                                                    |
|                                           | value `100`                                                                                  |
|                                           | value `1`                                                                                    |
| `adjudication[].category.coding[]`        | `status` Status                                                                              |
| `adjudication[].reason.coding[]`          | `queried` Queried                                                                            |
| `total[].category.coding[]`               | `benefit` Benefit Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`             |
|                                           | `submitted` Submitted Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`         |
|                                           | `tax` Tax in `https://hl7.org/fhir/R4/valueset-adjudication.html`                            |
|                                           | and 2 more                                                                                   |
| `total[].amount`                          | value `2070`                                                                                 |
|                                           | value `1725`                                                                                 |
|                                           | value `0`                                                                                    |
|                                           | and 1 more                                                                                   |
| `total[]`                                 | id `PMJAY0000X/PMJAY-T`                                                                      |

The `Patient`, `Organization`, `Coverage` entries are shaped as in the chapters that introduce them.

#### The answer

PMJAY uses a different bundle for this step, headed by `Claim` rather than `Task`.

| # | Resource                | Profile                                                                                                                                      |
| - | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | `Claim`                 | [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html)                                                                        |
| 2 | `Patient`               | [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)                                                                    |
| 3 | `Organization (prov)`   | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                                                          |
| 4 | `Organization (pay)`    | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                                                          |
| 5 | `Coverage`              | [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)                                                                  |
| 6 | `Practitioner`          | [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html)                                                          |
| 7 | `Procedure`             | [Procedure](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Procedure.html)                                                                |
| 8 | `QuestionnaireResponse` | `QuestionnaireResponse`, which NRCeS does not publish; base FHIR [QuestionnaireResponse](https://hl7.org/fhir/R4/questionnaireresponse.html) |
| 9 | `QuestionnaireResponse` | `QuestionnaireResponse`, which NRCeS does not publish; base FHIR [QuestionnaireResponse](https://hl7.org/fhir/R4/questionnaireresponse.html) |

###### Claim

NRCeS profile: [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html).

| Element                                         | Example                                                                                                                                                                    |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `identifier[]`                                  | system `https://nhcx.abdm.gov.in`, value `NM-26-0SE00002N`                                                                                                                 |
| `identifier[].type.coding[]`                    | `CLN` Claim number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`                                                                                 |
| `status`                                        | `active`                                                                                                                                                                   |
| `type.coding[]`                                 | `737481003` Inpatient care management (procedure) in `http://snomed.info/sct`                                                                                              |
| `use`                                           | `preauthorization`                                                                                                                                                         |
| `patient`                                       | reference `https://nhcx.abdm.gov.in/patient`                                                                                                                               |
| `billablePeriod`                                | start `2026-09-10T00:00:00+05:30`, end `2026-09-10T00:00:00+05:30`                                                                                                         |
| `created`                                       | `2026-09-10T23:55:36+05:30`                                                                                                                                                |
| `insurer`                                       | reference `https://nhcx.abdm.gov.in/payer`                                                                                                                                 |
| `provider`                                      | reference `https://nhcx.abdm.gov.in/provider`                                                                                                                              |
| `priority.coding[]`                             | `normal` Normal in `http://terminology.hl7.org/CodeSystem/processpriority`                                                                                                 |
| `careTeam[]`                                    | sequence `1`                                                                                                                                                               |
| `careTeam[].provider`                           | reference `https://nhcx.abdm.gov.in/practitioner`                                                                                                                          |
| `careTeam[].role.coding[]`                      | `primary` Primary provider in `http://terminology.hl7.org/CodeSystem/claimcareteamrole`                                                                                    |
| `careTeam[].qualification.coding[]`             | `394802001` General medicine in `http://snomed.info/sct`                                                                                                                   |
| `supportingInfo[]`                              | id `SupportingInformation/1`, sequence `1`                                                                                                                                 |
|                                                 | id `SupportingInformation/2`, sequence `2`                                                                                                                                 |
|                                                 | id `SupportingInformation/3`, sequence `3`                                                                                                                                 |
|                                                 | and 6 more                                                                                                                                                                 |
| `supportingInfo[].category.coding[]`            | `INV` Document Type - Investigation in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`                                                             |
|                                                 | `ONS` Period, start or end dates of aspects of the Condition. (e.g. admission, discha… in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`          |
|                                                 | `OTH` Other in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`                                                                                     |
|                                                 | and 2 more                                                                                                                                                                 |
| `supportingInfo[].code.coding[]`                | `MAND0455` CXR PA view or CECT chest abdomen and pelvis in `https://nhcx.abdm.gov.in/document-code`                                                                        |
|                                                 | `MAND0409` any investigations done in `https://nhcx.abdm.gov.in/document-code`                                                                                             |
|                                                 | `MAND0570` Planned line of management in `https://nhcx.abdm.gov.in/document-code`                                                                                          |
|                                                 | and 5 more                                                                                                                                                                 |
| `supportingInfo[].valueAttachment`              | contentType `application/pdf`, title `CXR PA view or CECT chest abdomen and pelvis`                                                                                        |
|                                                 | contentType `application/pdf`, title `any investigations done`                                                                                                             |
|                                                 | contentType `application/pdf`, title `Planned line of management`                                                                                                          |
|                                                 | and 1 more                                                                                                                                                                 |
| `supportingInfo[].valueReference`               | reference `https://nhcx.abdm.gov.in/questionnaireresponse/1`, display `Admission Details`                                                                                  |
|                                                 | reference `https://nhcx.abdm.gov.in/questionnaireresponse/2`, display `Authentication Consent`                                                                             |
| `diagnosis[]`                                   | sequence `1`                                                                                                                                                               |
| `diagnosis[].diagnosisCodeableConcept.coding[]` | `E11.9` Type 2 diabetes mellitus without complications in `http://hl7.org/fhir/sid/icd-10`                                                                                 |
| `diagnosis[].type[].coding[]`                   | `admitting` Admitting Diagnosis in `http://terminology.hl7.org/CodeSystem/ex-diagnosistype`                                                                                |
| `diagnosis[].onAdmission.coding[]`              | `yes` Yes in `http://terminology.hl7.org/CodeSystem/ex-diagnosis-on-admission`                                                                                             |
| `procedure[]`                                   | id `Procedure/1`, sequence `1`, date `2026-09-10T00:00:00+05:30`                                                                                                           |
| `procedure[].type[].coding[]`                   | `conservative` Conservative in `https://nhcx.abdm.gov.in/procedure-type`                                                                                                   |
| `procedure[].procedureReference`                | reference `https://nhcx.abdm.gov.in/procedure/1`, display `Pleural Effusion (Pleural Effusion)`                                                                            |
| `insurance[]`                                   | sequence `1`, focal `true`                                                                                                                                                 |
| `insurance[].coverage`                          | reference `https://nhcx.abdm.gov.in/coverage`                                                                                                                              |
| `item[]`                                        | id `Item/1`, sequence `1`, factor `1`, careTeamSequence `1`, diagnosisSequence `1`, procedureSequence `1`, informationSequence `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9` |
| `item[].productOrService.coding[]`              | `MG0111A` Pleural Effusion (Pleural Effusion) in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-procedure-code`                                                            |
| `item[].servicedPeriod`                         | start `2026-09-10`, end `2026-09-10`                                                                                                                                       |
| `item[].quantity`                               | value `1`                                                                                                                                                                  |
| `item[].unitPrice`                              | value `1800`, currency `INR`                                                                                                                                               |
| `item[].net`                                    | value `1800`, currency `INR`                                                                                                                                               |
| `item[].category.coding[]`                      | `MG` General Medicine in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-benefit-category`                                                                                  |
| `item[].modifier[].coding[]`                    | `STRAT006a` Routine Ward                                                                                                                                                   |
| `item[].programCode[].coding[]`                 | `AB-PMJAY` Ayushman Bharat Pradhan Mantri Jan Arogya Yojana (AB-PMJAY) in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-program-code`                                     |
| `total`                                         | value `1800`, currency `INR`                                                                                                                                               |

###### QuestionnaireResponse

| Element           | Example                                              |
| ----------------- | ---------------------------------------------------- |
| `questionnaire`   | `https://payer.gov.in/policy/questionnaire/100020`   |
| `status`          | `completed`                                          |
| `subject`         | reference `https://nhcx.abdm.gov.in/patient`         |
| `authored`        | `2026-09-10T23:55:36+05:30`                          |
| `item[]`          | linkId `100075`, text `Admission Date`               |
|                   | linkId `100074`, text `Surgery/Treatment Start Date` |
|                   | linkId `100073`, text `Admission Type`               |
|                   | and 1 more                                           |
| `item[].answer[]` | valueDateTime `2026-09-10T18:25:00+05:30`            |
|                   | valueString `PLANNED`                                |
|                   | valueString `Yes`                                    |

###### QuestionnaireResponse

| Element                           | Example                                                                                           |
| --------------------------------- | ------------------------------------------------------------------------------------------------- |
| `questionnaire`                   | `https://payer.gov.in/policy/questionnaire/100024`                                                |
| `status`                          | `completed`                                                                                       |
| `subject`                         | reference `https://nhcx.abdm.gov.in/patient`                                                      |
| `authored`                        | `2026-09-10T23:55:36+05:30`                                                                       |
| `item[]`                          | linkId `100093`, text `Medical Superintendent Declaration Form (During Admission)`                |
|                                   | linkId `100095`, text `Remarks`                                                                   |
| `item[].answer[].valueAttachment` | contentType `application/pdf`, title `Medical Superintendent Declaration Form (During Admission)` |
| `item[].answer[]`                 | valueString `Recorded.`                                                                           |

The `Patient`, `Organization`, `Coverage`, `Practitioner`, `Procedure` entries are shaped as in the chapters that introduce them.

### What PMJAY specifies

- The query arrives on `/v1/preauth/on_submit` under 24: a `ClaimResponse` with `outcome` `partial` and reason `queried`.
- The question is free text in `item.adjudication` where the category is `reason`, in `reason.coding.display`. On a live case it grows into a log, split by `|` into turns and by `~` into user, timestamp, type, comment and desk. Tolerate a single segment, treat the literal `null` as empty, and never put `|` or `~` in anything you send back.
- The log is cumulative. The answer you sent reappears in it on the next response, which is the only sign it was read.
- The answer is the whole preauthorisation bundle again on `/v1/preauth/submit` under 19, on the same case number, with the reply text in `item.productOrService.text`.

### What PMJAY requires

- Answer on 19, never on a new 12, which opens a second case.
- Put the query remarks under `supportingInfo` category `NMI`, code `CQD`, as a `valueString`.
- Supporting-info dates in `+05:30`.

## Use cases, APIs and data elements

### D7 Answer a pre-authorisation query (pmjay)

The query arrived as a ClaimResponse on 24, on the case's own thread, with the question in the item adjudication, not on the communication API. Answer with a fresh submit of the same bundle shape on this code, never as a new 12, which opens a second case.

|                       |                                                                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **API**               | `/v1/preauth/submit` [`apis/03-preauth/v1-preauth-submit.bru`](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-submit)          |
| **Callback**          | `/v1/preauth/on_submit` [`apis/03-preauth/v1-preauth-on-submit.bru`](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-on-submit) |
| **Workflow**          | 19                                                                                                                                     |
| **Carries JWE**       | yes                                                                                                                                    |
| **Focal resource**    | `Claim`                                                                                                                                |
| **Simulator console** | `/builder?family=preauth&usecase=query-answer`                                                                                         |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `19`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |
| `x-hcx-use_case`       | `New`               |

**Workflow codes**

| Code | Name                             | Authored by | `x-hcx-status`      | Means                                |
| ---- | -------------------------------- | ----------- | ------------------- | ------------------------------------ |
| `19` | Preauth Query Response Submitted | provider    | `response.complete` | Response to payer's query on preauth |

**Data elements**

| Element       | Label                         | Group     | Type           | Card.  | FHIR path                                                 | Example           | Notes |
| ------------- | ----------------------------- | --------- | -------------- | ------ | --------------------------------------------------------- | ----------------- | ----- |
| `claimNumber` | Case Number                   | Case      | `string`       | `1..1` | `Claim.identifier[0].value`                               | `VB26AA2600001`   |       |
| `workflowId`  | Workflow Code                 | Header    | `string`       | `1..1` | `Header.x-hcx-workflow_id`                                | `19`              |       |
| `nmiDocument` | Need More Info (NMI) Document | Documents | `base64Binary` | `1..1` | `Claim.supportingInfo[category=NMI].valueAttachment.data` | `JVBERi0xLjQK...` |       |

NRCeS profiles: [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html).


---

# Preauthorisation request

The first bundle with clinical content. The provider asks the payer to approve a treatment before it is given. The spine is a `Claim` with `use` set to `preauthorization`.

Sent on `/v1/preauth/submit`, answered on `/v1/preauth/on_submit`, workflow 12 new, 121 resubmission.

## The bundle

| # | Resource                | Profile                                                                                                                                      |
| - | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | `Claim`                 | [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html)                                                                        |
| 2 | `Patient`               | [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)                                                                    |
| 3 | `Organization (prov)`   | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                                                          |
| 4 | `Organization (pay)`    | [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)                                                          |
| 5 | `Coverage`              | [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)                                                                  |
| 6 | `Practitioner`          | [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html)                                                          |
| 7 | `Procedure`             | [Procedure](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Procedure.html)                                                                |
| 8 | `QuestionnaireResponse` | `QuestionnaireResponse`, which NRCeS does not publish; base FHIR [QuestionnaireResponse](https://hl7.org/fhir/R4/questionnaireresponse.html) |

## Elements

### Claim

NRCeS profile: [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html).

| Element                                         | Example                                                                                                                                                                                |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `identifier[]`                                  | system `https://nhcx.abdm.gov.in`, value `NM-26-0SE00002M`                                                                                                                             |
| `identifier[].type.coding[]`                    | `CLN` Claim number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`                                                                                             |
| `status`                                        | `active`                                                                                                                                                                               |
| `type.coding[]`                                 | `737481003` Inpatient care management (procedure) in `http://snomed.info/sct`                                                                                                          |
| `use`                                           | `preauthorization`                                                                                                                                                                     |
| `patient`                                       | reference `https://nhcx.abdm.gov.in/patient`                                                                                                                                           |
| `billablePeriod`                                | start `2026-09-10T00:00:00+05:30`, end `2026-09-10T00:00:00+05:30`                                                                                                                     |
| `created`                                       | `2026-09-10T23:53:57+05:30`                                                                                                                                                            |
| `insurer`                                       | reference `https://nhcx.abdm.gov.in/payer`                                                                                                                                             |
| `provider`                                      | reference `https://nhcx.abdm.gov.in/provider`                                                                                                                                          |
| `priority.coding[]`                             | `normal` Normal in `http://terminology.hl7.org/CodeSystem/processpriority`                                                                                                             |
| `careTeam[]`                                    | sequence `1`                                                                                                                                                                           |
| `careTeam[].provider`                           | reference `https://nhcx.abdm.gov.in/practitioner`                                                                                                                                      |
| `careTeam[].role.coding[]`                      | `primary` Primary provider in `http://terminology.hl7.org/CodeSystem/claimcareteamrole`                                                                                                |
| `careTeam[].qualification.coding[]`             | `394802001` General medicine in `http://snomed.info/sct`                                                                                                                               |
| `supportingInfo[]`                              | id `SupportingInformation/1`, sequence `1`                                                                                                                                             |
|                                                 | id `SupportingInformation/2`, sequence `2`                                                                                                                                             |
|                                                 | id `SupportingInformation/3`, sequence `3`                                                                                                                                             |
|                                                 | and 8 more                                                                                                                                                                             |
| `supportingInfo[].category.coding[]`            | `INV` Document Type - Investigation in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`                                                                         |
|                                                 | `ONS` Period, start or end dates of aspects of the Condition. (e.g. admission, discha… in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`                      |
|                                                 | `OTH` Other in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-supportinginfo-category`                                                                                                 |
|                                                 | and 1 more                                                                                                                                                                             |
| `supportingInfo[].code.coding[]`                | `POI` Proof of Identity (Aadhaar / Passport / Voter ID) in `https://nhcx.abdm.gov.in/document-code`                                                                                    |
|                                                 | `CER` Medical Certificate / Doctor Referral in `https://nhcx.abdm.gov.in/document-code`                                                                                                |
|                                                 | `RAD` Radiology / X-Ray / CT / MRI Scan Reports in `https://nhcx.abdm.gov.in/document-code`                                                                                            |
|                                                 | and 8 more                                                                                                                                                                             |
| `supportingInfo[].valueAttachment`              | contentType `application/pdf`, title `Proof of Identity (Aadhaar / Passport / Voter ID)`                                                                                               |
|                                                 | contentType `application/pdf`, title `Medical Certificate / Doctor Referral`                                                                                                           |
|                                                 | contentType `application/pdf`, title `Radiology / X-Ray / CT / MRI Scan Reports`                                                                                                       |
|                                                 | and 5 more                                                                                                                                                                             |
| `supportingInfo[].valueReference`               | reference `https://nhcx.abdm.gov.in/questionnaireresponse/1`, display `Total Knee Replacement (Unilateral), Standard Treatment Guidelines`                                             |
| `diagnosis[]`                                   | sequence `1`                                                                                                                                                                           |
| `diagnosis[].diagnosisCodeableConcept.coding[]` | `E11.9` Type 2 diabetes mellitus without complications in `http://hl7.org/fhir/sid/icd-10`                                                                                             |
| `diagnosis[].type[].coding[]`                   | `admitting` Admitting Diagnosis in `http://terminology.hl7.org/CodeSystem/ex-diagnosistype`                                                                                            |
| `diagnosis[].onAdmission.coding[]`              | `yes` Yes in `http://terminology.hl7.org/CodeSystem/ex-diagnosis-on-admission`                                                                                                         |
| `procedure[]`                                   | id `Procedure/1`, sequence `1`, date `2026-09-10T00:00:00+05:30`                                                                                                                       |
| `procedure[].type[].coding[]`                   | `surgical` Surgical in `https://nhcx.abdm.gov.in/procedure-type`                                                                                                                       |
| `procedure[].procedureReference`                | reference `https://nhcx.abdm.gov.in/procedure/1`, display `Total Knee Replacement (Unilateral)`                                                                                        |
| `insurance[]`                                   | sequence `1`, focal `true`                                                                                                                                                             |
| `insurance[].coverage`                          | reference `https://nhcx.abdm.gov.in/coverage`                                                                                                                                          |
| `item[]`                                        | id `Item/1`, sequence `1`, factor `1`, careTeamSequence `1`, diagnosisSequence `1`, procedureSequence `1`, informationSequence `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11` |
| `item[].productOrService.coding[]`              | `PROC-KNEE-01` Total Knee Replacement (Unilateral) in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-procedure-code`                                                                   |
| `item[].servicedPeriod`                         | start `2026-09-10`, end `2026-09-10`                                                                                                                                                   |
| `item[].quantity`                               | value `1`                                                                                                                                                                              |
| `item[].unitPrice`                              | value `150000`, currency `INR`                                                                                                                                                         |
| `item[].net`                                    | value `150000`, currency `INR`                                                                                                                                                         |
| `item[].category.coding[]`                      | `Surgical` Surgical in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-benefit-category`                                                                                                |
| `total`                                         | value `150000`, currency `INR`                                                                                                                                                         |

### Patient

NRCeS profile: [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html).

| Element                      | Example                                                                                                                      |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `identifier[]`               | value `MRAV1985001`                                                                                                          |
|                              | value `91-1234-1234-1234`                                                                                                    |
| `identifier[].type.coding[]` | `PMJAY` Pradhan Mantri Jan Aarogya Yojana (PMJAY) ID in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code` |
|                              | `ABHA` Ayushman Bharat Health Account (ABHA) ID in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`      |
|                              | `MB` Member Number in `http://terminology.hl7.org/CodeSystem/v2-0203`                                                        |
| `name[]`                     | text `<patient name>`                                                                                                        |
| `telecom[]`                  | system `phone`, value `9876543210`                                                                                           |
| `gender`                     | `male`                                                                                                                       |
| `birthDate`                  | `1985-06-15`                                                                                                                 |

### Organization (prov)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `identifier[]`               | system `https://nhcx.abdm.gov.in`, value `IN1910000151`                                 |
| `identifier[].type.coding[]` | `NPI` National provider identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`   |
| `type[].coding[]`            | `prov` Healthcare Provider in `http://terminology.hl7.org/CodeSystem/organization-type` |
| `name`                       | `KyroCare Multispeciality Hospital`                                                     |

### Organization (pay)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                               |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `identifier[]`               | system `https://nhcx.abdm.gov.in`, value `1000004805`                                                 |
| `identifier[].type.coding[]` | `NIIP` National Insurance Payor Identifier (Payor) in `http://terminology.hl7.org/CodeSystem/v2-0203` |
| `type[].coding[]`            | `pay` Payer in `http://terminology.hl7.org/CodeSystem/organization-type`                              |
| `name`                       | `Sandbox Payer`                                                                                       |

### Coverage

NRCeS profile: [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html).

| Element                      | Example                                                                                  |
| ---------------------------- | ---------------------------------------------------------------------------------------- |
| `identifier[]`               | value `POL7UMU001`                                                                       |
| `identifier[].type.coding[]` | `NH` National Health Plan Identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`  |
| `status`                     | `active`                                                                                 |
| `type.coding[]`              | `HIP` health insurance plan policy in `http://terminology.hl7.org/CodeSystem/v3-ActCode` |
| `subscriber`                 | reference `https://nhcx.abdm.gov.in/patient`                                             |
| `subscriberId`               | `MRAV1985001`                                                                            |
| `beneficiary`                | reference `https://nhcx.abdm.gov.in/patient`                                             |
| `relationship.coding[]`      | `self` in `http://terminology.hl7.org/CodeSystem/subscriber-relationship`                |
| `payor[]`                    | reference `https://nhcx.abdm.gov.in/payer`                                               |

### Practitioner

NRCeS profile: [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html).

| Element                         | Example                                                                                                              |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `identifier[]`                  | system `https://nhcx.abdm.gov.in`, value `71-8422-5818-7201`                                                         |
|                                 | system `https://hpr.abdm.gov.in`, value `71-8422-5818-7201`                                                          |
| `identifier[].type.coding[]`    | `HPID` Healthcare Professional ID (HPID) in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code`     |
|                                 | `HPIN` Health Practitioner ID issued by NDHM in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code` |
| `name[]`                        | text `Dr. Ananya Rao`                                                                                                |
| `qualification[].code.coding[]` | `MD` Doctor of Medicine in `http://terminology.hl7.org/CodeSystem/v2-0360`                                           |

### Procedure

NRCeS profile: [Procedure](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Procedure.html).

| Element             | Example                                                      |
| ------------------- | ------------------------------------------------------------ |
| `status`            | `preparation`                                                |
| `code`              | text `Total Knee Replacement (Unilateral)`                   |
| `code.coding[]`     | `71388002` Procedure (procedure) in `http://snomed.info/sct` |
| `subject`           | reference `https://nhcx.abdm.gov.in/patient`                 |
| `performedDateTime` | `2026-09-10T00:00:00+05:30`                                  |

### QuestionnaireResponse

| Element           | Example                                                                                                              |
| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| `questionnaire`   | `<participant-defined>`                                                                                              |
| `status`          | `completed`                                                                                                          |
| `subject`         | reference `https://nhcx.abdm.gov.in/patient`                                                                         |
| `authored`        | `2026-09-10T23:53:57+05:30`                                                                                          |
| `item[]`          | linkId `PROC-KNEE-01/stg/1`, text `Duration of symptoms and the conservative treatment tried (months of physiother…` |
|                   | linkId `PROC-KNEE-01/stg/2`, text `Kellgren-Lawrence grade of osteoarthritis on the standing X-ray`                  |
|                   | linkId `PROC-KNEE-01/stg/3`, text `Range of motion and deformity of the knee (flexion contracture, varus/valgus)`    |
|                   | and 2 more                                                                                                           |
| `item[].answer[]` | valueString `Recorded.`                                                                                              |

## Rules

### The case number

`Claim.identifier`, typed `CLN`, carries the provider's case number. Every later message on the case, the payer's included, names it.

### One focal insurance

Exactly one `Claim.insurance[]` entry carries `focal: true`.

### Items

Each item links to the care team, diagnosis and procedure by sequence. `net` is `unitPrice` times `quantity`; do not compute with `factor`. `Claim.total` equals the sum of the item nets.

### Documents

The mandatory document codes are the ones the auth-requirements answer returned. Send each code and display exactly as given.

### The STG answers

Each package's STG questionnaire is answered as a `QuestionnaireResponse` in the bundle, with the `linkId`s the plan gives.

### Claim.type

SNOMED `737481003`, Inpatient care management. Payers echo it, some under the `ndhm-claim-type` ValueSet URL.

### References to records

A `valueReference` may point at the `Composition` heading an embedded record rather than at a `DocumentReference`. Follow the reference, then walk the record.

## PMJAY

The generic bundle above is what every payer takes, IRDAI-regulated insurers and TPAs included. PMJAY takes it with the changes and requirements below.

### What changes in the bundle

#### Resources

- PMJAY adds 1 `QuestionnaireResponse`.

#### Elements PMJAY adds

| Element                                                 | Example                                                                                                                                |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `Claim.item[].modifier[].coding[]`                      | `STRAT006a` Routine Ward                                                                                                               |
| `Claim.item[].programCode[].coding[]`                   | `AB-PMJAY` Ayushman Bharat Pradhan Mantri Jan Arogya Yojana (AB-PMJAY) in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-program-code` |
| `QuestionnaireResponse.item[].answer[].valueAttachment` | contentType `application/pdf`, title `Medical Superintendent Declaration Form (During Admission)`                                      |

### What PMJAY specifies

- `item.programCode` carries `AB-PMJAY` under `ndhm-program-code`.
- `item.modifier` carries the ward tier from the master's stratification codes, and `item.category` the master's specialty code.
- The Authentication Consent answer is a second `QuestionnaireResponse` beside the STG answers, with its attachments as `valueAttachment` and its dates as `valueDateTime`.
- Document codes are the `MAND` codes the auth-requirements answer returned.

### What PMJAY requires

- The biometric user token on the request, or the plan's Authentication Consent questionnaire answered as a `QuestionnaireResponse`. Refused with `PAYR-1256` otherwise.
- The STG questionnaire answered for every package that needs one. Refused with `PAYR-1254` otherwise.
- Not more than one day before admission, with the registration and admission dates as supporting information.
- One live preauthorisation per beneficiary per hospital. Refused with `PAYR-1238` while another is open.
- `LM100` is not allowed on a preauthorisation. Refused with `PAYR-1270`.
- Auto-approval only when this is the first preauthorisation on the case and every package carries `ApprovalNotRequired` `Y`.

## Use cases, APIs and data elements

### B3 Submit pre-authorisation (provider)

Permission to treat. A resubmission, an enhancement and a query answer all reuse the same bundle with a new correlation id and the original reference; only the workflow code tells them apart. The acknowledgement on 20 brings the payer's own case number, and the desk files everything under it.

|                    |                                                                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/preauth/submit` [`apis/03-preauth/v1-preauth-submit.bru`](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-submit)          |
| **Callback**       | `/v1/preauth/on_submit` [`apis/03-preauth/v1-preauth-on-submit.bru`](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-on-submit) |
| **Workflow**       | 12 new, 121 resubmission, 13 enhancement; under PMJAY 19 answers a query and 131 an enhancement query                                  |
| **Carries JWE**    | yes                                                                                                                                    |
| **Focal resource** | `Claim`                                                                                                                                |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `12`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |
| `x-hcx-use_case`       | `New`               |

**Workflow codes**

| Code  | Name                                 | Authored by | `x-hcx-status`                                            | Means                                   |
| ----- | ------------------------------------ | ----------- | --------------------------------------------------------- | --------------------------------------- |
| `12`  | Preauth Request Initiated            | provider    | `request.initiated`                                       | New preauth submission                  |
| `121` | Preauth Request Resubmitted          | provider    | `request.initiated`                                       | Resubmission after query/rejection      |
| `13`  | Enhancement Request Initiated        | provider    | `request.initiated`                                       | Enhancement (additional amount) request |
| `19`  | Preauth Query Response Submitted     | provider    | `response.complete`                                       | Response to payer's query on preauth    |
| `131` | Enhancement Query Response Submitted | provider    | `response.partial`, `response.error`, `response.complete` | Response to enhancement query           |

**Data elements**

| Element                | Label                               | Group        | Type       | Card.  | FHIR path                                                                       | Example                             | Notes                                                          |
| ---------------------- | ----------------------------------- | ------------ | ---------- | ------ | ------------------------------------------------------------------------------- | ----------------------------------- | -------------------------------------------------------------- |
| `claimNumber`          | Pre-auth Case Number                | Case         | `string`   | `1..1` | `Claim.identifier[0].value`                                                     | `PA20260226001`                     | also at `Bundle.id`                                            |
| `use`                  | Claim Use                           | Case         | `code`     | `1..1` | `Claim.use`                                                                     | `preauthorization`                  |                                                                |
| `preAuthRef`           | Approval Reference (if enhancement) | Case         | `string`   | `0..1` | `Claim.insurance[0].preAuthRef[0]`                                              | `APPR-2026-HP-00891`                |                                                                |
| `patientName`          | Patient Full Name                   | Beneficiary  | `string`   | `1..1` | `Patient.name[0].text`                                                          | `Ramesh Chandra Sharma`             |                                                                |
| `memberId`             | Scheme / Insurer Member ID          | Beneficiary  | `string`   | `1..1` | `Patient.identifier[type=PMJAY].value`                                          | `PMJAY-HP-2024-998811`              | also at `Coverage.subscriberId`                                |
| `abhaNumber`           | ABHA Number                         | Beneficiary  | `string`   | `0..1` | `Patient.identifier[type=ABHA].value`                                           | `91234567890123`                    |                                                                |
| `gender`               | Gender                              | Beneficiary  | `code`     | `1..1` | `Patient.gender`                                                                | `male`                              | code system `http://hl7.org/fhir/administrative-gender`        |
| `birthDate`            | Date of Birth                       | Beneficiary  | `date`     | `1..1` | `Patient.birthDate`                                                             | `1982-06-15`                        |                                                                |
| `patientPhone`         | Mobile Phone                        | Beneficiary  | `string`   | `0..1` | `Patient.telecom[system=phone].value`                                           | `9876543210`                        |                                                                |
| `policyNumber`         | Policy Number                       | Coverage     | `string`   | `1..1` | `Coverage.identifier[0].value`                                                  | `PMJAY/HP/S/G`                      |                                                                |
| `facilityId`           | Hospital Facility ID (HFR/NPI)      | Provider     | `string`   | `1..1` | `Organization[type=prov].identifier[system=https://facility.abdm.gov.in].value` | `IN1910000151`                      |                                                                |
| `providerName`         | Hospital Name                       | Provider     | `string`   | `1..1` | `Organization[type=prov].name`                                                  | `Apex Multispeciality Hospital`     |                                                                |
| `payerId`              | Payer Identifier (NIIP)             | Payer        | `string`   | `1..1` | `Organization[type=pay].identifier[system=https://irdai.gov.in].value`          | `1000003538`                        |                                                                |
| `payerName`            | Payer Name                          | Payer        | `string`   | `1..1` | `Organization[type=pay].name`                                                   | `National Health Authority - PMJAY` |                                                                |
| `practitionerId`       | Practitioner ID (HPID/HPIN)         | Practitioner | `string`   | `1..1` | `Practitioner.identifier[system=https://hpr.abdm.gov.in].value`                 | `21-8899-4455-6677`                 |                                                                |
| `practitionerName`     | Doctor Name                         | Practitioner | `string`   | `1..1` | `Practitioner.name[0].text`                                                     | `Dr. Arvind Kumar`                  |                                                                |
| `admissionDate`        | Admission Date                      | Stay         | `dateTime` | `1..1` | `Claim.billablePeriod.start`                                                    | `2026-02-26T10:00:00+05:30`         |                                                                |
| `dischargeDate`        | Discharge Date                      | Stay         | `dateTime` | `1..1` | `Claim.billablePeriod.end`                                                      | `2026-03-02T14:30:00+05:30`         |                                                                |
| `careSetting`          | Care Setting                        | Stay         | `code`     | `1..1` | `Claim.type.coding[0].code`                                                     | `institutional`                     | code system `http://terminology.hl7.org/CodeSystem/claim-type` |
| `primaryDiagnosisCode` | Primary Diagnosis (ICD-10)          | Clinical     | `string`   | `1..1` | `Claim.diagnosis[0].diagnosisCodeableConcept.coding[0].code`                    | `A97.0`                             | code system `http://hl7.org/fhir/sid/icd-10`                   |
| `procedureCode`        | Package / Procedure Code            | Clinical     | `string`   | `1..1` | `Claim.procedure[0].procedureCodeableConcept.coding[0].code`                    | `MG004A`                            |                                                                |
| `estimatedTotal`       | Estimated Package Amount            | Billing      | `decimal`  | `1..1` | `Claim.total.value`                                                             | `15500.00`                          |                                                                |

NRCeS profiles: [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html), [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html), [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html), [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html), [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html).

### D4 Submit pre-authorisation (pmjay)

Not more than one day before admission, with the biometric token or the consent response, the documents the auth-requirements answer asked for, the STG questionnaire for each package, and the registration and admission dates as supporting info. Auto-approved only if it is the first pre-authorisation for the case and every package allows it.

|                       |                                                                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **API**               | `/v1/preauth/submit` [`apis/03-preauth/v1-preauth-submit.bru`](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-submit)          |
| **Callback**          | `/v1/preauth/on_submit` [`apis/03-preauth/v1-preauth-on-submit.bru`](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-on-submit) |
| **Workflow**          | 12                                                                                                                                     |
| **Carries JWE**       | yes                                                                                                                                    |
| **Focal resource**    | `Claim`                                                                                                                                |
| **Simulator console** | `/builder?family=preauth&usecase=initiate`                                                                                             |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `12`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |
| `x-hcx-use_case`       | `New`               |

**Workflow codes**

| Code | Name                      | Authored by | `x-hcx-status`      | Means                  |
| ---- | ------------------------- | ----------- | ------------------- | ---------------------- |
| `12` | Preauth Request Initiated | provider    | `request.initiated` | New preauth submission |

**Data elements**

| Element                | Label                          | Group        | Type           | Card.  | FHIR path                                                                       | Example                             | Notes                                                   |
| ---------------------- | ------------------------------ | ------------ | -------------- | ------ | ------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------- |
| `claimNumber`          | PMJAY Case Number              | Case         | `string`       | `1..1` | `Claim.identifier[0].value`                                                     | `VB26AA2600001`                     |                                                         |
| `patientName`          | Patient Full Name              | Beneficiary  | `string`       | `1..1` | `Patient.name[0].text`                                                          | `Ramesh Chandra Sharma`             |                                                         |
| `memberId`             | Scheme / Insurer Member ID     | Beneficiary  | `string`       | `1..1` | `Patient.identifier[type=PMJAY].value`                                          | `PMJAY-HP-2024-998811`              | also at `Coverage.subscriberId`                         |
| `abhaNumber`           | ABHA Number                    | Beneficiary  | `string`       | `0..1` | `Patient.identifier[type=ABHA].value`                                           | `91234567890123`                    |                                                         |
| `gender`               | Gender                         | Beneficiary  | `code`         | `1..1` | `Patient.gender`                                                                | `male`                              | code system `http://hl7.org/fhir/administrative-gender` |
| `birthDate`            | Date of Birth                  | Beneficiary  | `date`         | `1..1` | `Patient.birthDate`                                                             | `1982-06-15`                        |                                                         |
| `patientPhone`         | Mobile Phone                   | Beneficiary  | `string`       | `0..1` | `Patient.telecom[system=phone].value`                                           | `9876543210`                        |                                                         |
| `facilityId`           | Hospital Facility ID (HFR/NPI) | Provider     | `string`       | `1..1` | `Organization[type=prov].identifier[system=https://facility.abdm.gov.in].value` | `IN1910000151`                      |                                                         |
| `providerName`         | Hospital Name                  | Provider     | `string`       | `1..1` | `Organization[type=prov].name`                                                  | `Apex Multispeciality Hospital`     |                                                         |
| `payerId`              | Payer Identifier (NIIP)        | Payer        | `string`       | `1..1` | `Organization[type=pay].identifier[system=https://irdai.gov.in].value`          | `1000003538`                        |                                                         |
| `payerName`            | Payer Name                     | Payer        | `string`       | `1..1` | `Organization[type=pay].name`                                                   | `National Health Authority - PMJAY` |                                                         |
| `practitionerId`       | Practitioner ID (HPID/HPIN)    | Practitioner | `string`       | `1..1` | `Practitioner.identifier[system=https://hpr.abdm.gov.in].value`                 | `21-8899-4455-6677`                 |                                                         |
| `practitionerName`     | Doctor Name                    | Practitioner | `string`       | `1..1` | `Practitioner.name[0].text`                                                     | `Dr. Arvind Kumar`                  |                                                         |
| `primaryDiagnosisCode` | Primary Diagnosis (ICD-10)     | Clinical     | `string`       | `1..1` | `Claim.diagnosis[0].diagnosisCodeableConcept.coding[0].code`                    | `A97.0`                             | code system `http://hl7.org/fhir/sid/icd-10`            |
| `procedureCode`        | Package / Procedure Code       | Clinical     | `string`       | `1..1` | `Claim.procedure[0].procedureCodeableConcept.coding[0].code`                    | `MG004A`                            |                                                         |
| `patientPhoto`         | Patient Photo on Bed (POI)     | Documents    | `base64Binary` | `1..1` | `Claim.supportingInfo[category=POI].valueAttachment.data`                       | `JVBERi0xLjQK...`                   |                                                         |

NRCeS profiles: [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html), [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html), [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html), [Practitioner](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Practitioner.html).

### D5 Resubmit pre-authorisation (pmjay)

Revises an approved or rejected case for a different amount or package. Nullifies every earlier instance; the payer treats it as the new base request.

|                       |                                                                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **API**               | `/v1/preauth/submit` [`apis/03-preauth/v1-preauth-submit.bru`](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-submit)          |
| **Callback**          | `/v1/preauth/on_submit` [`apis/03-preauth/v1-preauth-on-submit.bru`](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-on-submit) |
| **Workflow**          | 121                                                                                                                                    |
| **Carries JWE**       | yes                                                                                                                                    |
| **Focal resource**    | `Claim`                                                                                                                                |
| **Simulator console** | `/builder?family=preauth&usecase=resubmit`                                                                                             |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `121`               |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |
| `x-hcx-use_case`       | `Resubmit`          |

**Workflow codes**

| Code  | Name                        | Authored by | `x-hcx-status`      | Means                              |
| ----- | --------------------------- | ----------- | ------------------- | ---------------------------------- |
| `121` | Preauth Request Resubmitted | provider    | `request.initiated` | Resubmission after query/rejection |

**Data elements**

| Element       | Label                | Group  | Type     | Card.  | FHIR path                   | Example         | Notes |
| ------------- | -------------------- | ------ | -------- | ------ | --------------------------- | --------------- | ----- |
| `claimNumber` | Existing Case Number | Case   | `string` | `1..1` | `Claim.identifier[0].value` | `VB26AA2600001` |       |
| `workflowId`  | Workflow Code        | Header | `string` | `1..1` | `Header.x-hcx-workflow_id`  | `121`           |       |

NRCeS profiles: [Claim](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Claim.html).


---

# Preauthorisation response

The payer's answer, on the provider's `/v1/preauth/on_submit` callback. A collection bundle whose spine is a `ClaimResponse` carrying the request's case number. The same shape carries an acknowledgement, an approval, a query and a rejection.

Sent on `/v1/preauth/on_submit`.

## The bundle

| # | Resource              | Profile                                                                                                    |
| - | --------------------- | ---------------------------------------------------------------------------------------------------------- |
| 1 | `ClaimResponse`       | none declared; NRCeS [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html) |
| 2 | `Patient`             | none declared; NRCeS [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)             |
| 3 | `Organization (pay)`  | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)   |
| 4 | `Organization (prov)` | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)   |
| 5 | `Coverage`            | none declared; NRCeS [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html)           |

## Elements

### ClaimResponse

NRCeS profile: [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html).

| Element                                   | Example                                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------------------------------ |
| `identifier[]`                            | system `<participant-defined>`, value `NM-26-0SE00002M`                                    |
| `identifier[].type.coding[]`              | `CLN` Claim number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code` |
| `status`                                  | `active`                                                                                   |
| `use`                                     | `preauthorization`                                                                         |
| `patient`                                 | reference `<participant-defined>`                                                          |
| `created`                                 | `2026-09-10T23:54:09+05:30`                                                                |
| `insurer`                                 | reference `<participant-defined>`                                                          |
| `requestor`                               | reference `<participant-defined>`                                                          |
| `outcome`                                 | `complete`                                                                                 |
| `disposition`                             | `Approved after the status enquiry.`                                                       |
| `preAuthRef`                              | `CL/26/0SE000108`                                                                          |
| `payeeType.coding[]`                      | `provider` Provider in `http://terminology.hl7.org/CodeSystem/payeetype`                   |
| `item[]`                                  | id `Item/LI-899f9802`, itemSequence `1`                                                    |
| `item[].adjudication[].category.coding[]` | `submitted` Submitted Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`       |
|                                           | `eligible` Eligible Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`         |
|                                           | `reason` Reason for Adjudication in `https://hl7.org/fhir/R4/valueset-adjudication.html`   |
|                                           | and 1 more                                                                                 |
| `item[].adjudication[].amount`            | value `150000`                                                                             |
| `item[].adjudication[].reason.coding[]`   | display `Approved after the status enquiry.`                                               |
|                                           | `Approved` Approved                                                                        |
| `adjudication[].category.coding[]`        | `status` Status                                                                            |
| `adjudication[].reason.coding[]`          | `approved` Approved                                                                        |
| `total[].category.coding[]`               | `benefit` Benefit Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`           |
|                                           | `submitted` Submitted Amount in `https://hl7.org/fhir/R4/valueset-adjudication.html`       |
|                                           | `eligible` Eligible Amount                                                                 |
| `total[].amount`                          | value `150000`                                                                             |
| `total[]`                                 | id `MRAV1985001/SANDBOX-DEFAULT-01`                                                        |

### Patient

NRCeS profile: [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html).

| Element                      | Example                                                               |
| ---------------------------- | --------------------------------------------------------------------- |
| `identifier[]`               | system `<participant-defined>`, value `MRAV1985001`                   |
| `identifier[].type.coding[]` | `MB` Member Number in `http://terminology.hl7.org/CodeSystem/v2-0203` |
| `name[]`                     | family `Kumar`, given `Ravi`, text `Ravi Kumar`                       |
| `gender`                     | `male`                                                                |
| `birthDate`                  | `1985-06-15`                                                          |

### Organization (pay)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                               |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `active`                     | `true`                                                                                                |
| `identifier[]`               | system `https://facility.abdm.gov.in`, value `1000004805`                                             |
| `identifier[].type.coding[]` | `NIIP` National Insurance Payor Identifier (Payor) in `http://terminology.hl7.org/CodeSystem/v2-0203` |
| `type[].coding[]`            | `pay` Payer in `http://terminology.hl7.org/CodeSystem/organization-type`                              |
| `name`                       | `Sandbox Payer`                                                                                       |

### Organization (prov)

NRCeS profile: [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html).

| Element                      | Example                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `active`                     | `true`                                                                                  |
| `identifier[]`               | system `https://facility.abdm.gov.in`, value `IN1910000151`                             |
| `identifier[].type.coding[]` | `NPI` National provider identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`   |
| `type[].coding[]`            | `prov` Healthcare Provider in `http://terminology.hl7.org/CodeSystem/organization-type` |
| `name`                       | `XYZ Multispeciality Hospital`                                                          |

### Coverage

NRCeS profile: [Coverage](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Coverage.html).

| Element                      | Example                                                                                  |
| ---------------------------- | ---------------------------------------------------------------------------------------- |
| `identifier[]`               | system `<participant-defined>`, value `SANDBOX-DEFAULT-01`                               |
| `identifier[].type.coding[]` | `NH` National Health Plan Identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`  |
| `status`                     | `active`                                                                                 |
| `type.coding[]`              | `HIP` health insurance plan policy in `http://terminology.hl7.org/CodeSystem/v3-ActCode` |
| `beneficiary`                | reference `<participant-defined>`                                                        |
| `period`                     | start `2026-01-01T00:00:00+05:30`, end `2026-12-31T00:00:00+05:30`                       |
| `payor[]`                    | reference `<participant-defined>`                                                        |
| `class[]`                    | id `POL7UMU002`, value `SANDBOX-DEFAULT-01`                                              |
| `class[].type.coding[]`      | `XV` Health Plan Identifier in `http://terminology.hl7.org/CodeSystem/v2-0203`           |

## The answers

The same bundle, told apart by the workflow code, `outcome` and the claim-level adjudication reason.

| Variant              | Workflow | outcome    | reason                |
| -------------------- | -------- | ---------- | --------------------- |
| Acknowledged         | `20`     | `queued`   | `submitted` Submitted |
| Approved             | `21`     | `complete` | `approved` Approved   |
| Enhancement approved | `22`     | `complete` | `approved` Approved   |
| Rejected             | `23`     | `error`    | `rejected` Rejected   |
| Queried              | `24`     | `partial`  | `queried` Queried     |

## Rules

### Read outcome with the reason

`outcome` `complete` covers approval and rejection alike. Read it with `adjudication[].reason` at claim level.

### Answer early, decide later

Acknowledge at once on 20 as `response.partial`, then decide on 21 or 23 as `response.complete`, or the exchange retires the correlation before the adjudicator gets to it.

### The case number

`preAuthRef` carries the payer's own case number. Store it on arrival; later requests on the case name it.

### Items by sequence

Read item adjudication by `itemSequence`, never by array position. A reduced amount does not force `outcome` to `partial`; reconcile the amounts yourself.

### Totals

`total[]` carries `benefit`, `submitted` and `eligible`. The `eligible` total names the member and the plan in its `id`; key on the category and the `id` together.

### disposition is prose

For a human. Route on `outcome` and the adjudication codes.

### Match on the case number

Join the response to the request on `identifier` and `preAuthRef`, never on the provider identifier or name, which can change shape between request and response.

### Adjudication systems

Some senders bind adjudication categories to a documentation URL. Match on the code.

## PMJAY

The generic bundle above is what every payer takes, IRDAI-regulated insurers and TPAs included. PMJAY takes it with the changes and requirements below.

### What changes in the bundle

PMJAY sends this exchange in the generic shape.

### What PMJAY specifies

- A rejection is `outcome` `error` with reason `rejected` and benefit 0. Generic payers send `complete` with `cancelled` or `rejected`. Handle both.
- A query is `outcome` `partial` with reason `queried`, the question as free text in the item adjudication; see the query chapter.
- `preAuthRef` carries the scheme's case id. It is what the payer service uses to address the case.

### What PMJAY requires

- Store the case reference the moment it arrives. Enhancements, claims and the payer service address the case by it.

## Use cases, APIs and data elements

### C5 Respond to pre-authorisation (payer)

The adjudicated pre-authorisation. The acknowledgement on 20 travels as response.partial and carries the payer's own case number; the decisions travel as response.complete. Read outcome and the adjudication amounts together: complete covers approval and denial alike. Under PMJAY a query is this ClaimResponse on 24 or 241, on the case's own thread.

|                    |                                                                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/preauth/on_submit` [`apis/03-preauth/v1-preauth-on-submit.bru`](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-on-submit) |
| **Callback**       | `/v1/preauth/submit` [`apis/03-preauth/v1-preauth-submit.bru`](/docs/nhcx/v1/api/preauth/endpoints/preauth-v1-preauth-submit)          |
| **Workflow**       | 20 received, 21 approved, 23 rejected, 24 queried, 22 enhancement approved, 231 denied, 241 queried                                    |
| **Carries JWE**    | yes                                                                                                                                    |
| **Focal resource** | `ClaimResponse`                                                                                                                        |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1518@hcx`          |
| `x-hcx-recipient_code` | `1000004446@hcx`    |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-workflow_id`    | `21`                |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `response.complete` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |
| `x-hcx-debug_flag`     | `INFO`              |

**Workflow codes**

| Code  | Name                         | Authored by       | `x-hcx-status`                       | Means                                                    |
| ----- | ---------------------------- | ----------------- | ------------------------------------ | -------------------------------------------------------- |
| `20`  | Preauth Request Received     | payer             | `response.partial`, `response.error` | Payer has received and acknowledged the preauth request  |
| `21`  | Preauth Request Approved     | payer             | `response.complete`                  | Preauth fully approved - proceed with treatment          |
| `23`  | Preauth Request Rejected     | payer             | `response.complete`                  | Preauth rejected - review error/processNote for reason   |
| `24`  | Preauth Request Queried      | payer             | `request.initiated`                  | Payer needs more information - respond using workflow 19 |
| `22`  | Enhancement Request Approved | payer             | `response.complete`                  | Enhancement request approved by payer                    |
| `231` | Enhancement Deny             | status sheet only | `response.complete`                  |                                                          |
| `241` | Enhancement Request Queried  | payer             | `request.initiated`                  | Enhancement request queried by payer                     |

**Data elements**

| Element          | Label                      | Group      | Type      | Card.  | FHIR path                                            | Example                           | Notes |
| ---------------- | -------------------------- | ---------- | --------- | ------ | ---------------------------------------------------- | --------------------------------- | ----- |
| `outcome`        | Verdict Outcome            | Verdict    | `code`    | `1..1` | `ClaimResponse.outcome`                              | `complete`                        |       |
| `preAuthRef`     | Payer Case Tracking ID     | Verdict    | `string`  | `0..1` | `ClaimResponse.preAuthRef`                           | `APPR-2026-HP-00891`              |       |
| `approvedAmount` | Approved Pre-auth Sanction | Financials | `decimal` | `0..1` | `ClaimResponse.total[category=benefit].amount.value` | `15500.00`                        |       |
| `disposition`    | Adjudicator Remarks        | Verdict    | `string`  | `0..1` | `ClaimResponse.disposition`                          | `Approved by PPD-Trust committee` |       |

NRCeS profiles: [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html).


---

# Status and search

Two exchanges that are specified and seldom used. Confirm support with the payer before building either of them.

## Status

A sender asks what became of a request it made. There is no FHIR payload either way. The Status sheet of the requests-and-responses workbook says the request payload "should be empty string": no bundle, no `Task`, no resource. Everything the call needs travels in the protected header. `x-hcx-correlation_id` is the `x-hcx-api_call_id` of the request whose status is sought, `x-hcx-status` is `request.initiated`, `x-hcx-workflow_id` and `x-hcx-use_case` (`New`, `Enhancement` or `Resubmit`) are optional, and so is `x-hcx-ben-abha-id`. The status comes back on `/v1/on_status`, again in the protected header: `x-hcx-status` `request.dispatched`, the correlation id of the request, and `x-hcx-error_details` (`code`, `message`, `trace`) where it failed. The sheet gives the callback no payload section. The sandbox exit checklists word the request payload as the "encrypted payload of request for which the status is seeking for" and describe no bundle for it.

Sent on `/v1/status`, answered on `/v1/on_status`.

## Search

Sent on `/v1/search/submit`.

### The bundle

| # | Resource       | Profile                                                                                                  |
| - | -------------- | -------------------------------------------------------------------------------------------------------- |
| 1 | `Task`         | [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)                                      |
| 2 | `Organization` | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html) |
| 3 | `Organization` | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html) |

### Elements

#### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                 | Example                                                                                            |
| ----------------------- | -------------------------------------------------------------------------------------------------- |
| `identifier[]`          | system `https://nhcx.gov.in/task`, value `SR0000000001`                                            |
| `status`                | `requested`                                                                                        |
| `intent`                | `order`                                                                                            |
| `code.coding[]`         | `search` Search in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-codes`                      |
| `description`           | `Search claim records for case CL0000000001`                                                       |
| `authoredOn`            | `2026-02-26T12:00:00+05:30`                                                                        |
| `requester`             | reference `urn:uuid:e0000001-0000-0000-0000-000000000002`                                          |
| `owner`                 | reference `urn:uuid:e0000001-0000-0000-0000-000000000003`                                          |
| `input[]`               | valueString `CL0000000001`                                                                         |
| `input[].type.coding[]` | `ClaimNumber` Claim Number in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code` |

The `Organization` entries are shaped as in the chapters that introduce them.

## Search response

Sent on `/v1/search/on_submit`.

### The bundle

| # | Resource        | Profile                                                                                                    |
| - | --------------- | ---------------------------------------------------------------------------------------------------------- |
| 1 | `Task`          | [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html)                                        |
| 2 | `ClaimResponse` | none declared; NRCeS [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html) |
| 3 | `Patient`       | none declared; NRCeS [Patient](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html)             |
| 4 | `Organization`  | none declared; NRCeS [Organization](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html)   |

### Elements

#### Task

NRCeS profile: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

| Element                   | Example                                                                       |
| ------------------------- | ----------------------------------------------------------------------------- |
| `status`                  | `completed`                                                                   |
| `intent`                  | `order`                                                                       |
| `code.coding[]`           | `search` Search in `https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-task-codes` |
| `output[].type.coding[]`  | `ClaimResponse` in `http://hl7.org/fhir/resource-types`                       |
| `output[].valueReference` | reference `urn:uuid:e0000001-0000-0000-0000-000000000011`                     |

#### ClaimResponse

NRCeS profile: [ClaimResponse](https://nrces.in/ndhm/fhir/r4/StructureDefinition-ClaimResponse.html).

| Element         | Example                    |
| --------------- | -------------------------- |
| `status`        | `active`                   |
| `type.coding[]` | `institutional`            |
| `use`           | `claim`                    |
| `patient`       | reference `Patient/1`      |
| `insurer`       | reference `Organization/2` |
| `outcome`       | `complete`                 |

The `Patient`, `Organization` entries are shaped as in the chapters that introduce them.

## Rules

### Status

No bundle and no `Task`. Send an empty payload with the correlation id set to the call id of the request you are asking about, and read the answer from the callback's protected header.

### Search

`Task.code` `search` in `ndhm-task-codes`, with inputs from the task input-type value set, such as `ClaimNumber`, `PolicyNumber`, `FromDate` and `ToDate`. The answer is a `Task`, `completed`, whose outputs reference the matching `ClaimResponse` resources in the same bundle, possibly across several callbacks on one correlation id.

### Agree the codes

The task code for search is given more than one way in the specifications. Agree it with the payer in writing first.

## PMJAY

The generic bundle above is what every payer takes, IRDAI-regulated insurers and TPAs included. PMJAY takes it with the changes and requirements below.

### What changes in the bundle

PMJAY sends this exchange in the generic shape.

### What PMJAY requires

- A status enquiry as a `Task` is refused. Read where a case stands from the payer service's role lookup.

## Use cases, APIs and data elements

### A5 Get status (shared)

Where any request you made got to, by its correlation id. The sandbox's own status page answers without a token.

|                       |                                                                                                          |
| --------------------- | -------------------------------------------------------------------------------------------------------- |
| **API**               | `/v1/status` [`apis/08-status/v1-status.bru`](/docs/nhcx/v1/api/status/endpoints/status-v1-status)       |
| **Callback**          | `/v1/on_status` [`apis/13-other/v1-on_status.bru`](/docs/nhcx/v1/api/other/endpoints/other-v1-on-status) |
| **Carries JWE**       | yes                                                                                                      |
| **Focal resource**    | `None; the payload is an empty string and the protected header carries the call`                         |
| **Simulator console** | `/status`                                                                                                |

**Request headers**

| Header                 | Example value           |
| ---------------------- | ----------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`        |
| `x-hcx-recipient_code` | `1518@hcx`              |
| `x-hcx-api_call_id`    | `{{$guid}}`             |
| `x-hcx-request_id`     | `{{$guid}}`             |
| `x-hcx-correlation_id` | `{{originalApiCallId}}` |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}`     |
| `x-hcx-status`         | `request.initiated`     |
| `x-hcx-ben-abha-id`    | `91711234567890`        |

**Data elements**

| Element         | Label                                    | Group           | Type     | Card.  | FHIR path                     | Example                                | Notes |
| --------------- | ---------------------------------------- | --------------- | -------- | ------ | ----------------------------- | -------------------------------------- | ----- |
| `correlationId` | API call ID of the request being checked | Header          | `uuid`   | `1..1` | `Header.x-hcx-correlation_id` | `4f9d2b80-13b4-4e2a-9e12-8f9024a56789` |       |
| `status`        | Dispatch Status                          | Callback Header | `string` | `1..1` | `Header.x-hcx-status`         | `request.dispatched`                   |       |

### B6 Search claims (provider)

Look up claim information by criteria. The provider sandbox exit checklist names /v1/search/submit for claim search, while the Technical Specifications route /search/submit from NHA through NHCX to the payer: a cross-payer search for NHA or a regulator. A provider's search over its own cases is /claim/search in the protocol, which the access-control policy allows for requests that originated from the provider. No source confirms which of the two the sandbox accepts from a provider.

|                    |                                                                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/search/submit` [`apis/08-status/v1-search-submit.bru`](/docs/nhcx/v1/api/status/endpoints/status-v1-search-submit)          |
| **Callback**       | `/v1/search/on_submit` [`apis/08-status/v1-search-on-submit.bru`](/docs/nhcx/v1/api/status/endpoints/status-v1-search-on-submit) |
| **Carries JWE**    | yes                                                                                                                              |
| **Focal resource** | `Task`                                                                                                                           |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1000004446@hcx`    |
| `x-hcx-recipient_code` | `1518@hcx`          |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `request.initiated` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |

**Data elements**

| Element        | Label                | Group      | Type     | Card.  | FHIR path                                   | Example        | Notes |
| -------------- | -------------------- | ---------- | -------- | ------ | ------------------------------------------- | -------------- | ----- |
| `taskCode`     | Task Code            | Task       | `code`   | `1..1` | `Task.code.coding[0].code`                  | `search`       |       |
| `claimNumber`  | Search Claim Number  | Task Input | `string` | `0..1` | `Task.input[type=ClaimNumber].valueString`  | `CL0000000001` |       |
| `policyNumber` | Search Policy Number | Task Input | `string` | `0..1` | `Task.input[type=PolicyNumber].valueString` | `PMJAY/HP/S/G` |       |

NRCeS profiles: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).

### C8 Respond to search (payer)

The ClaimResponse objects matching the criteria asked for.

|                    |                                                                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| **API**            | `/v1/search/on_submit` [`apis/08-status/v1-search-on-submit.bru`](/docs/nhcx/v1/api/status/endpoints/status-v1-search-on-submit) |
| **Callback**       | `/v1/search/submit` [`apis/08-status/v1-search-submit.bru`](/docs/nhcx/v1/api/status/endpoints/status-v1-search-submit)          |
| **Carries JWE**    | yes                                                                                                                              |
| **Focal resource** | `Task`                                                                                                                           |

**Request headers**

| Header                 | Example value       |
| ---------------------- | ------------------- |
| `x-hcx-sender_code`    | `1518@hcx`          |
| `x-hcx-recipient_code` | `1000004446@hcx`    |
| `x-hcx-api_call_id`    | `{{$guid}}`         |
| `x-hcx-request_id`     | `{{$guid}}`         |
| `x-hcx-correlation_id` | `{{$guid}}`         |
| `x-hcx-timestamp`      | `{{$isoTimestamp}}` |
| `x-hcx-status`         | `response.complete` |
| `x-hcx-ben-abha-id`    | `91711234567890`    |

**Data elements**

| Element            | Label                  | Group       | Type        | Card.  | FHIR path                                | Example                       | Notes |
| ------------------ | ---------------------- | ----------- | ----------- | ------ | ---------------------------------------- | ----------------------------- | ----- |
| `taskStatus`       | Search Task Status     | Task        | `code`      | `1..1` | `Task.status`                            | `completed`                   |       |
| `claimResponseRef` | Matching ClaimResponse | Task Output | `reference` | `0..*` | `Task.output[].valueReference.reference` | `ClaimResponse/cr-approved-1` |       |

NRCeS profiles: [Task](https://nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html).


---

# Governance and audit

What a participant owes the network beyond making the calls work: how messages are secured in transit and at the API layer, what must be logged and for how long, how grievances are handled, how a participant joins and how one is removed. None of it is a claim exchange and all of it is binding on anyone operating in production.

## The security layers

Three, and they do different jobs. A system that has one is not secure.

| Layer     | Mechanism                                 | What it protects                                  |
| --------- | ----------------------------------------- | ------------------------------------------------- |
| Transport | HTTPS with TLS, mandatory in production   | The channel                                       |
| Message   | JWE with the recipient's public key       | The payload, from everyone including the exchange |
| API       | JWT bearer tokens with a mandatory expiry | Access to the endpoints                           |

Transport security is stated without qualification: all communication between the exchange and participating entities uses TLS, and all APIs work only over HTTPS in production.

## The two JWTs, and they are not the same

This is the part most often built wrong, because the same word covers two tokens signed by different parties with different algorithms.

**Your token, calling the gateway.** Signed `HS256`, with the participant's `client_secret` as the key. Claims `jti`, `iss` (the exchange instance), `sub` (your client ID), `iat` and `exp`. You obtain it from the sessions endpoint with your client ID and secret, and you present it on the `Authorization` header. Session Token in Getting Started covers obtaining it; note that NHCX's own endpoints read it from `bearer_auth` in practice, which is why the safe course is to send both header names.

**The exchange's token, calling you.** Signed `RS256`, with the exchange's own private key. Claims `jti`, `iss`, `sub` set to the same value as `iss`, `iat` and `exp`. Participant systems are expected to validate it against the exchange's public key.

**The public key is still not published.** Neither is the header it arrives on. Receiving a Callback in Getting Started sets out what that means: every integration built from these documents has shipped with signature checking disabled, because rejecting everything makes the endpoint useless. Ask for the key during onboarding, at the same time you register your endpoint, hold the gap open deliberately rather than silently, and defend the endpoint with an address allow-list and whatever else your edge offers until you have it.

**Revocation.** The exchange revokes a participant's API access by generating a new `client_secret` and updating the registry. Your tokens stop working and you mint new ones with the new secret. There is no separate revocation call to watch for, so a sudden authentication failure across every call is a state to recognise.

## Key rotation

- Rotate the encryption key pair **once a year**. The specification recommends it; the certificate a self-signed X.509 generates by default expires in a year anyway.
- Mechanisms must exist for providers, payers and the exchange to **tell the ecosystem about a suspected key compromise**. Decide in advance who at your organisation makes that call and how.
- A certificate-only change in production skips the passcode steps. Creating and Updating a Participant has the call.
- The practical failure is asymmetric and worth naming: if the certificate on your record does not match the private key you hold, everybody else can seal messages you cannot open, and nothing tells you until traffic fails.

## What must be logged

The event-audit guidelines are the strictest obligation in this chapter and the least implemented.

- **Every event in the claims flow must be digitally signed and logged**, in both directions, between provider systems, beneficiary apps and payer systems. Claim created, claim forwarded, data requested, authorisation, payment.
- **Logs must be append-only.** They must not be editable. The stated purpose is immutability, non-tamperability and non-repudiability.
- **Retention is set by the law of the land**, configurable, and the material deliberately does not name a period.
- **The audit trail must be transparently available to the customer.**

The exchange keeps its own audit log of every API call it receives: the domain headers, the signature and encryption details, sender and recipient, and whether validation passed. It never logs the payload, because it cannot read it.

Two requirements on that log are worth knowing because they are things you can use rather than things you must build.

- **The audit log is queryable through an API**, so a participant can retrieve the trail of its own transactions.
- **The exchange publishes reports against it** for payers, providers, beneficiaries, regulators and observers, and each instance publishes the list of reports it supports and the level of detail in each.

Each instance also defines an archival policy covering retention, deletion and how to reach logs after archival. Ask for your instance's policy and its report list during onboarding; neither is in the published material.

## Grievance redressal

The claims desk meets grievances as a communication reason code. The governance layer underneath it is a published policy that every operator must produce and every participant signs.

What the guidelines require of that policy:

- Digital initiation, routing and tracking of a grievance raised by any participant against any other.
- A published list of grievances covered, and a mechanism for those that are not.
- **Every participant must run a nodal governance body**, contactable at the digital and physical addresses given at onboarding, and those contact details are readable by every other participant through the registry. The exchange publishes its own governance body the same way.
- Published types, priorities and **service levels per grievance type**.
- A due-diligence cycle before responding, the right to **reopen**, and escalation to the exchange operator on accelerated timelines when the requester is not satisfied.
- Versioning, signature by new members at onboarding, and proactive notice of any change.

Two consequences for a build. Your registry entry is a published contact point for disputes, so the mobile number and email on it are operational rather than administrative. And a grievance has a service level attached, so the communication inbox that receives one is not a mailbox somebody reads when they can.

The guidelines are aligned with IRDAI's own grievance-redressal guidelines and are explicitly a draft for consultation. The model policy has not been published.

## Beneficiary authentication, generally

PMJAY biometrics are one case of a wider expectation. Provider systems are expected to support Aadhaar eKYC for beneficiary verification, and Aadhaar authentication by mobile OTP or biometric to initiate a claim transaction. The guidelines note that provider systems enrolled with ABDM already hold biometric devices, because health ID creation needs them. Payer systems and the exchange integrate Aadhaar authentication for verifying the beneficiary at claim validation.

Biometric Authentication in Building a Provider covers the scheme's own implementation of this.

## Joining, and being removed

Onboarding is two stages, and the first certifies the second.

**Sandbox.** Apply, be verified as eligible, receive credentials, integrate, then pass the functional and security tests that apply to your role. The operator may require additional security review such as STQC or CERT-In. You submit your test results, including how your application uses and interacts with the exchange APIs, and on approval receive a completion certificate **valid for a configured period**. Nobody states that period; ask.

**Production.** Register, using Health Facility Registry authentication where you have it and documentary verification from IRDAI or an equivalent agency where you do not. Your sandbox certificate is reviewed. Production credentials are issued. Then go live, with the advice to plan change management, train staff and pilot with a small set of clients first.

**Deboarding** happens three ways, and the second is the one to design against.

| Kind                         | Initiated by               | Examples                                                                                                                                                                                                                     |
| ---------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Involuntary, by a regulator  | IRDAI or a legal authority | A provider suspended for fraud; a TPA or payer deactivated                                                                                                                                                                   |
| Involuntary, by the exchange | The operator               | Serious or repeated policy violation, including grave service-level breaches; attempted unauthorised access; behaviour that destabilises the exchange, such as **frequent bursts of requests beyond authorised rate limits** |
| Voluntary                    | The participant            | Moving to another exchange, shutting down, merging                                                                                                                                                                           |

Involuntary removal comes with an elaborate warning mechanism and a right of appeal through the grievance process.

That rate-limit clause is the only acknowledgement in the corpus that rate limits exist. No number is published anywhere. Build a client that backs off rather than one that retries hard, and ask for your instance's limits at onboarding.

## What to ask for at onboarding

Everything the published material leaves blank, in this chapter and across the documentation, collected so it is asked once.

- The exchange's **public key** for validating inbound JWTs, and the header the token arrives on.
- The instance's **audit report list** and the address of the audit query API.
- The instance's **archival policy**: retention, deletion, post-archival access.
- The **grievance policy**, its version, its covered types and their service levels, and the nodal contact you are expected to publish.
- The **rate limits** your participant code is subject to.
- The **validity period** of your sandbox certificate.
- Whether **STQC or CERT-In** review applies to you.
- The **turnaround-time windows** for preauthorisation and claim. The plan's `ScheduledTATApproval` flag says the period "varies with policy" and the FAQ says there is no fixed TAT as of now; no values are published.
- The **forward instruction** on coverage eligibility: its fields and its flow. The specification gives it one sentence.
- The **`/v1/error` body schema**. The sources say to implement the endpoint and receive the reject details, but its field names are not published.
- The **currency rule** for money fields. The claim sample carries no `currency` on `Claim.total`, the payment notice sample carries it on the paid amount, and no source states a rule.
- The **coverage-based insurance plan**. Only the package-based plan is sampled, in either direction.
- **Payment notices 31 and 33**. Only the initiation is sampled, so the notice that carries a real bank reference has never been observed.
- The **timestamp form**, format and zone. The handbook says Indian time (`+05:30`) and that UTC fails validation, the FAQ says UTC with a trailing `Z`, and the samples use `+05:30`.


---

# Notifications and patient apps

The third kind of participant. A personal health record app registers on the exchange as a beneficiary service provider, subscribes on a beneficiary's behalf, and receives a readable message every time something happens to that beneficiary's claim. It sends no claims and answers no queries. It is the only role on the network whose whole job is to be told things.

This chapter is for anyone building such an app, and for a hospital or payer that also runs one.

## The model: subscribe on login, last linked wins

```mermaid
sequenceDiagram
  box Beneficiary
    participant A as Patient app
  end
  box Exchange
    participant X as NHCX
  end
  box Provider side
    participant H as Hospital
  end
  box Payer side
    participant Y as Payer
  end
  A->>X: subscribe for this ABHA, on login
  X-->>A: subscription confirmed
  H->>X: preauth/submit
  X->>Y: forwards
  Y->>X: preauth/on_submit, approved
  X->>H: callback to the hospital
  X->>A: notification with a readable message
```

When a beneficiary logs into an app with their ABHA, that app calls subscribe and becomes the recipient of every notification for that ABHA. **Any earlier subscription is replaced.** Only one app receives notifications for a beneficiary at any moment.

That rule is deliberate and it has consequences worth designing around.

- There is no duplicate delivery to handle, and no fan-out.
- A beneficiary who opens a second app silently stops receiving notifications in the first. Neither app is told.
- Subscription is an action to take on every login, not once at install.

## Before you start

- **Milestone 1.** The app must have completed ABDM Milestone 1 integration.
- **Registration as a beneficiary service provider.** Sandbox testing, sandbox certification, then onboarding to the production registry. The role code is 10009 and the registry ID may be the app's own client ID.
- **An HTTPS endpoint** with TLS 1.2 or newer, and the ability to generate and validate JWTs.

## Subscribing

```bash
curl --location --request POST 'https://hcxsbx.abdm.gov.in/v1/notification/subscribe' \  --header 'Content-Type: application/json' \  --header 'Authorization: Bearer <access token>' \  --header 'x-hcx-sender_code: phr-app-xyz@bsp' \  --header 'x-hcx-recipient_code: nhcx-gateway@hcx' \  --header 'x-hcx-timestamp: <iso timestamp>' \  --header 'x-hcx-correlation_id: <uuid>' \  --data-raw '{    "payload": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00iLCJ4LWhjeC1zZW5kZXJfY29kZSI6InBoci1hcHAteHl6QGJzcCJ9.encrypted_key.iv.ciphertext.tag",    "_payload_plaintext": {      "subscription_id": "sub_ravi_001",      "topic_code": [        "workflow_events"      ],      "recipient_code": "phr-app-xyz@bsp",      "subscriber": {        "id": "ravi@abdm"      },      "on_notification_url": "https://api.phrapp.com/v1/hcx/notification/on_subscribe"    }  }'
```

[Notification subscribe in the API reference](/docs/nhcx/v1/api/other/endpoints/other-v1-notification-subscribe)

The call is sealed like any other message on the exchange, with the app as sender and the gateway as recipient. The subscription service's live specification is at `https://hcxsbx.abdm.gov.in/subscriptionhcxservice/swagger-ui/index.html`, and Environments and Addresses lists it with the others.

| Field                 | Required | What it carries                                         |
| --------------------- | -------- | ------------------------------------------------------- |
| `subscription_id`     | Yes      | Your own unique identifier for this subscription        |
| `topic_code`          | Yes      | An array of topics, see below                           |
| `recipient_code`      | Yes      | Your participant code                                   |
| `subscriber.id`       | Yes      | The beneficiary's ABHA address, for example `ravi@abdm` |
| `on_notification_url` | Yes      | Where notifications should be delivered                 |
| `expiry`              | No       | When the subscription lapses                            |

```json
{  "subscription_id": "sub_ravi_001",  "topic_code": ["workflow_events"],  "recipient_code": "phr-app-xyz@bsp",  "subscriber": { "id": "ravi@abdm" },  "on_notification_url": "https://api.phrapp.example/v1/hcx/notification/on_subscribe"}
```

### Topics

| Topic                | What arrives                                      |
| -------------------- | ------------------------------------------------- |
| `workflow_events`    | Claim lifecycle: preauthorisation, claim, payment |
| `network_events`     | Exchange platform updates and maintenance         |
| `participant_events` | Changes to payer and provider registrations       |

Most apps need `workflow_events` alone. The field is an array, so subscribe to more than one where you have a reason.

The workflow codes for this exchange are N01 to a payer, N02 to a provider, N03 to a beneficiary and N04 for the acknowledgement.

## Receiving a notification

The exchange posts to the `on_notification_url` you registered.

| Field             | What it carries                                                   |
| ----------------- | ----------------------------------------------------------------- |
| `notification_id` | Unique per notification                                           |
| `topic_code`      | The topic it arrived under                                        |
| `timestamp`       | ISO 8601                                                          |
| `subscriber.id`   | The beneficiary's ABHA                                            |
| `message`         | **A human-readable sentence the app can display as it stands**    |
| `domain_values`   | Optional map of the domain headers, for audit or richer rendering |

```json
{  "notification_id": "notif_20260428_001",  "topic_code": "workflow_events",  "timestamp": "2026-04-28T14:30:00+05:30",  "subscriber": { "id": "ravi@abdm" },  "message": "Preauthorization approved for Rs. 50,000. Valid from 2026-04-28 to 2026-05-05. Reference: PA-2026-004567",  "domain_values": {    "x-hcx-correlation_id": "corr_20260428_12345",    "x-hcx-status": "response.complete",    "x-hcx-action": "preauth_response",    "x-hcx-amount_submitted": "75000.00"  }}
```

**The `message` field is the point of the whole exchange.** It is written by the exchange to be shown to a patient without parsing, and an app that ignores it and renders its own sentence from `domain_values` is doing avoidable work and will drift from what every other app shows.

`domain_values` is where the named domain headers actually appear, and it is the clearest evidence in the corpus that domain headers are a real mechanism rather than a placeholder. Envelope Fields lists them.

## Event types

| Event              | Status values          |
| ------------------ | ---------------------- |
| `preauth_request`  | `queued`, `processing` |
| `preauth_response` | `approved`, `rejected` |
| `claim_request`    | `queued`, `processing` |
| `claim_response`   | `approved`, `rejected` |
| `payment_notice`   | `paid`, `pending`      |
| `communication`    | `information_required` |

Note that this vocabulary is not the workflow-code vocabulary and not the status-word vocabulary. It is a third, simpler set, designed for display.

## Errors

| Code  | Meaning                     | What to do                              |
| ----- | --------------------------- | --------------------------------------- |
| `401` | Token expired               | Regenerate and retry                    |
| `403` | Not authorised              | Check your registry entry and role      |
| `409` | Subscription already exists | Should not occur under last-linked-wins |
| `500` | Gateway problem             | Retry with backoff                      |

## What the payer and provider do

Nothing extra. The exchange generates notifications from the traffic that already flows. A payer's ordinary responses feed them, and the payer's own notifications carry workflow N01.

For a hospital that also runs a patient app, the two are separate participants with separate codes and separate certificates, even inside one organisation.

## Security and privacy

Four requirements from the integration document, none of them optional in production.

- Store the access token encrypted, refresh before expiry, and never log the participant secret.
- Enforce HTTPS with TLS 1.2 or newer on the callback.
- Validate the JWT the exchange signs its call with, and check that `sender_code` is the exchange. The public key problem described in Governance and Audit applies here too.
- **Obtain explicit consent from the beneficiary before subscribing**, and show the subscription state somewhere the beneficiary can find and change it.

That last one is the substantive difference between this role and the others. A hospital's participation is contracted; a patient app's is consented to, one beneficiary at a time.

## What this chapter cannot tell you

The integration document is written against an older reading of the protocol than the rest of the corpus. It gives `alg` as `RSA-OAEP` rather than `RSA-OAEP-256`, and a token life of 6,000 seconds. That figure is wrong: the token lasts 1,200 seconds (20 minutes). Follow the current protocol as Envelope Fields and Session Token give it, and treat the document's payload shapes as the part that is specific to notifications.

No sample notification bundle exists in the corpus, and no participant is recorded as having exercised this exchange.


---

# PMJAY error codes

Every error code a PMJAY integration can meet, in one table. `NHCX-` codes come from the exchange, `PAYR-` codes from the PMJAY payer, and `ERR-PYR-` codes have been seen only in live traffic. Search by code, by a phrase from the message, or by the path you called. Filter by the part of the claim the code belongs to.

Eighteen codes from `PAYR-1001` to `PAYR-1020` mean different things on the standard payer sheet and on the PMJAY payer's, so read a code with the message beside it. [Reading error codes](/docs/nhcx/v1/reference/error-code-guide) explains the code spaces and what to do about each collision.

Search by code, message or path

310 of 310 codes

| Code            | What it means                                                                                                                                                                                                                                                                                                                                                                                                      | Message as sent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Area                                                                          | Arrives on                                                                                                                                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ERR-PYR-CLM-007 | **No preauthorisation or claim exists for the claim's case number**The PMJAY payer refused your claim because it found no preauthorisation or claim under the case number you sent.                                                                                                                                                                                                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Observed live                                                                 | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| NHCX-401        | **The exchange does not accept your authorisation for this call**The NHCX refused your call because it does not accept you as authorised to make it. The message text is User Unauthorized.                                                                                                                                                                                                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error``/v3/sessions`                                                                                                                                                                                    |
| NHCX-1001       | **The recipient's system is not reachable**The NHCX accepted your message but could not deliver it. The recipient's registered endpoint did not answer.                                                                                                                                                                                                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error`                                                                                                                                                                                                  |
| NHCX-1002       | **The sender is not a registered participant**The NHCX does not recognise the sender of your message. Your organisation is not registered as a participant, or the sender code on the message is wrong.                                                                                                                                                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error`                                                                                                                                                                                                  |
| NHCX-1003       | **The recipient is not a registered participant**The NHCX does not recognise the recipient your message is addressed to. The recipient code is wrong, or that organisation is not registered.                                                                                                                                                                                                                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error``/v2/participant/get/policies`                                                                                                                                                                    |
| NHCX-1004       | **No recipient is registered for the scheme you asked for**The NHCX found no recipient registered for the scheme on your message. The recipient details do not fit the scheme that the policy belongs to.                                                                                                                                                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error``/v2/participant/get/policies`                                                                                                                                                                    |
| NHCX-1005       | **A request header is missing or not valid**The NHCX refused your call because a header is missing or holds a value it cannot accept.                                                                                                                                                                                                                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error`                                                                                                                                                                                                  |
| NHCX-1006       | **The correlation id has already been used**The NHCX already has a request with the correlation id on your message. Each request cycle needs its own correlation id.                                                                                                                                                                                                                                               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error`                                                                                                                                                                                                  |
| NHCX-1007       | **The exchange could not process the request's structure or values**The NHCX failed while processing your message. The message text points at the structure or the values of your request.                                                                                                                                                                                                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error`                                                                                                                                                                                                  |
| NHCX-1008       | **The exchange had a temporary failure**The NHCX failed while processing your message. The message text asks you to try again after some time.                                                                                                                                                                                                                                                                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error`                                                                                                                                                                                                  |
| NHCX-1009       | **The exchange failed and recorded the cause in its own logs**The NHCX failed while processing your message. The detail is in the exchange's own logs, which you cannot see.                                                                                                                                                                                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error`                                                                                                                                                                                                  |
| NHCX-1010       | **No request matches the correlation id on your answer**You sent an answer on an on\_ path, and the NHCX holds no request with its correlation id.                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error``/v1/status`                                                                                                                                                                                      |
| NHCX-1011       | **The x-hcx-status value is not valid**The NHCX refused your message because x-hcx-status in the protected header holds a value it does not accept.                                                                                                                                                                                                                                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error`                                                                                                                                                                                                  |
| NHCX-1012       | **No message matches the api\_call\_id you gave**The NHCX found no message with the API call id you referred to.                                                                                                                                                                                                                                                                                                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error``/v1/on_status``/v1/status`                                                                                                                                                                       |
| NHCX-1013       | **The request body is empty or not valid**The NHCX received a call with an empty body, or a body it cannot read as a request.                                                                                                                                                                                                                                                                                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error`                                                                                                                                                                                                  |
| NHCX-1014       | **The exchange could not deliver the response to its sender**The NHCX could not deliver a response to the participant it was meant for. That participant's registered endpoint did not take it.                                                                                                                                                                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error`                                                                                                                                                                                                  |
| NHCX-1015       | **The client is not allowed to change this participant's registry details**The participant registry refused a change to a participant's record because the client id behind your token is not the one that created the participant. Only the creator's credentials can change the endpoint URL or the encryption certificate through the API. Anyone else changes them on the NHCX portal or through NHCX support. | You are not authorized to update/modify details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v2/participant/update``/v2/update/cert`                                                                                                                                                                    |
| NHCX-1016       | **The call does not fit the exchange open on this correlation id**The NHCX refused your call because its action does not fit the exchange open under this correlation id.                                                                                                                                                                                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error`                                                                                                                                                                                                  |
| NHCX-1017       | **The recipient answered a delivery in a form the exchange does not accept**The NHCX delivered a message, and the recipient's system answered in a form the exchange does not accept. The exchange treats that answer as a failed delivery.                                                                                                                                                                        | Invalid response received from receiver                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Gateway                                                                       | `/v1/error`                                                                                                                                                                                                  |
| NHCX-1018       | **The ABHA number is not in the XX-XXXX-XXXX-XXXX form**The NHCX refused your message because the ABHA number is not in the form it accepts.                                                                                                                                                                                                                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Gateway                                                                       | `/v1/error`                                                                                                                                                                                                  |
| PAYR-1001       | **The recipient could not decrypt your request**The recipient could not open the sealed JWE you sent. Its private key does not match the certificate you sealed with, or the sealed content is malformed.                                                                                                                                                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/coverageeligibility/on_check``/v1/preauth/on_submit`                                                                                                                               |
| PAYR-1002       | **The payer could not encrypt its answer to you**The payer received and processed your request, but could not seal its answer to you. It seals answers with the public certificate your organisation registered in NHCX.                                                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v2/update/cert`                                                                                                              |
| PAYR-1003       | **The payer's system could not reach the exchange and will resend, or the workflow requested is not valid**PAYR-1003 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structureClaim                                     | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1004       | **Your facility is not registered with the payer for the policy, or the FHIR bundle is malformed**PAYR-1004 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1005       | **The beneficiary is not a covered member of the policy, or the request is more than 24 hours old**PAYR-1005 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                                                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structureCoverage eligibilityPreauthorisationClaim | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1006       | **The policy does not exist, or a name in the request is not valid**PAYR-1006 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1007       | **The policy has expired, or the gender in the request is not valid**PAYR-1007 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1008       | **The beneficiary's remaining cover is not enough for the request, or the FHIR bundle is not valid or cannot be parsed**PAYR-1008 has two meanings, depending on which payer sent it, and the PMJAY payer also uses it for fifteen messages the error sheet prints without a code.                                                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1009       | **The requested items are not valid or not covered, or the Patient resource has no identifier**PAYR-1009 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1010       | **A preauthorisation was required but not obtained, or the Patient identifier has no type**PAYR-1010 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1011       | **The approved package does not support enhancement, or the Claim resource has no identifier**PAYR-1011 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1012       | **The claim amount is more than the approved preauthorisation amount, or the Claim identifier has no type**PAYR-1012 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1013       | **The procedures or packages have no prior approval, or the provider Organization resource has no identifier**PAYR-1013 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1014       | **The date of birth is after the date of service, or the provider Organization identifier has no type**PAYR-1014 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                                               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1015       | **The date of service is after the date of death, or the payer Organization resource has no identifier**PAYR-1015 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1016       | **The claim duplicates one already submitted for the same services and dates, or the payer Organization identifier has no type**PAYR-1016 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1017       | **The amount calculations are not correct, or the Task resource has no task code**PAYR-1017 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit``/v1/task/on_submit``/v1/task/submit`                                                                                      |
| PAYR-1018       | **The time limit for submission has expired, or the Task resource has no reason code**PAYR-1018 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit``/v1/task/on_submit``/v1/task/submit`                                                                                      |
| PAYR-1019       | **The additional information the payer asked for did not arrive in time, or a supporting info sequence is not valid**PAYR-1019 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1020       | **The payer holds no valid bank details for your facility, or a supporting info category is not valid**PAYR-1020 has two meanings, depending on which payer sent it:                                                                                                                                                                                                                                               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Standard payer sheetBundle structure                                          | `/v1/claim/on_submit``/v1/claim/submit``/v1/paymentnotice/request`                                                                                                                                           |
| PAYR-1021       | **A supporting info entry has an invalid code**Your FHIR bundle lists supporting information, such as dates, discharge details and documents. Each entry has a category and a code. The payer rejected the request because one entry's code is not valid for it.                                                                                                                                                   | Invalid code received in supporting info element for sequence %s. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1023       | **A procedure has an invalid category**Your FHIR bundle describes each procedure in a Procedure resource. The payer rejected the request because a procedure's category is missing or not one it accepts.                                                                                                                                                                                                          | Invalid procedure category received for procedure component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1024       | **A procedure has an invalid status**Your FHIR bundle describes each procedure in a Procedure resource, with a status. The payer rejected the request because a procedure's status is missing or not valid.                                                                                                                                                                                                        | Invalid procedure status received for procedure component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1025       | **A procedure has an invalid sequence**A claim in a FHIR bundle lists its procedures with sequence numbers. Items point at procedures by that number. The payer rejected the request because a procedure's sequence is missing or not valid.                                                                                                                                                                       | Invalid procedure sequence received for procedure component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1026       | **The claim references a procedure that is not in the bundle**The Claim resource in your FHIR bundle points at each procedure through a reference. The payer rejected the request because one of those references finds no Procedure resource in the bundle.                                                                                                                                                       | No procedure component found for reference in claim component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1027       | **A claim item has an invalid id**Each billed item in the Claim resource of your FHIR bundle carries an id. The payer rejected the request because an item's id is missing or not valid.                                                                                                                                                                                                                           | Invalid item id found for item in claim component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1028       | **A claim item has an invalid sequence**Each billed item in the Claim resource of your FHIR bundle carries a sequence number. The payer rejected the request because an item's sequence is missing or not valid.                                                                                                                                                                                                   | Invalid item sequence received for item in claim component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1029       | **The bundle id is invalid**Every request carries one FHIR bundle, and the bundle has an id. The payer rejected the request because the bundle's id is missing or not valid.                                                                                                                                                                                                                                       | Invalid bundle id received for FHIR bundle. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1030       | **A questionnaire id in the bundle is invalid**Some policies ask the provider to answer questionnaires. The answers travel as QuestionnaireResponse resources in the FHIR bundle. The payer rejected the request because a questionnaire id in the bundle is not valid.                                                                                                                                            | Invalid questionnaire id received in FHIR bundle for questionnaire component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1031       | **A bundle entry has an invalid URL**Every resource in a FHIR bundle sits in an entry with a full URL. References between resources use that URL. The payer rejected the request because an entry's URL is missing or not valid.                                                                                                                                                                                   | Invalid url received for bundle entry in FHIR bundle. Hence request will not be processed further. Please reach out to technical team.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1032       | **The eligibility check has an invalid purpose**A coverage eligibility check states what the provider wants to know, in its purpose. The payer rejected the check because the purpose in your FHIR bundle is missing or not one it supports.                                                                                                                                                                       | Invalid purpose received for coverage eligibility request. Hence request will not be processed further. Please try again with valid purpose details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Bundle structure                                                              | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1033       | **The eligibility check has no items for its purpose**Some eligibility questions are about a specific package or treatment. The FHIR bundle names it in an item. The payer rejected the check because the purpose needs items and the check carries none.                                                                                                                                                          | No items received for coverage eligibility purpose. Since items are mandatory for the requested purpose, hence request will not be processed further. Please try again with valid item details.                                                                                                                                                                                                                                                                                                                                                                                                                                   | Bundle structure                                                              | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1034       | **A procedure code is invalid**Each procedure and billed item in your FHIR bundle names a package by its code. The payer rejected the request because a procedure code is not valid.                                                                                                                                                                                                                               | Invalid procedure code received. Please try again with valid procedure details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1035       | **The policy code is invalid**Every request names the insurance policy it is made under. The payer rejected the request because the policy code in your FHIR bundle is not valid.                                                                                                                                                                                                                                  | Invalid policy code received. Please try again with valid policy details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/insuranceplan/on_request``/v1/insuranceplan/request``/v1/preauth/on_submit``/v1/preauth/submit` |
| PAYR-1036       | **A supporting info entry lacks a valid attachment**Some supporting information entries in your FHIR bundle carry a document, such as a clinical note or a report. The payer rejected the request because an entry that must carry a document has no valid attachment.                                                                                                                                             | Invalid attachment received in supporting info with sequence number %s. Please try again with valid attachment details as attachment value is expected. If issue is not resolved, please reach out to technical team.                                                                                                                                                                                                                                                                                                                                                                                                             | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1037       | **The communication has no identifier**When a payer sends a communication request, you answer with a FHIR bundle that carries a Communication resource. The payer rejected your answer because the Communication resource has no identifier.                                                                                                                                                                       | No identifier found for communication component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Bundle structure                                                              | `/v1/communication/on_request``/v1/communication/request`                                                                                                                                                    |
| PAYR-1038       | **The communication identifier has no type**When a payer sends a communication request, you answer with a FHIR bundle that carries a Communication resource. The payer rejected your answer because the Communication resource's identifier has no type.                                                                                                                                                           | No type found for communication component identifier. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Bundle structure                                                              | `/v1/communication/on_request``/v1/communication/request`                                                                                                                                                    |
| PAYR-1039       | **The communication has no payload**When a payer sends a communication request, you answer with a FHIR bundle that carries a Communication resource. The payer rejected your answer because the Communication resource has no payload.                                                                                                                                                                             | No payload found for communication component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Bundle structure                                                              | `/v1/communication/on_request``/v1/communication/request`                                                                                                                                                    |
| PAYR-1040       | **A reference points at a resource that is not in the bundle**Resources in a FHIR bundle point at each other through references. The payer rejected the request because a reference points at a resource that is not in the bundle.                                                                                                                                                                                | No component found for given reference. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1041       | **A procedure has no identifier**Each Procedure resource in your FHIR bundle carries an identifier, its serial number. The payer rejected the request because a Procedure resource has no identifier.                                                                                                                                                                                                              | No identifier found for procedure component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1042       | **A procedure identifier has no type**Each Procedure resource in your FHIR bundle carries an identifier with a type. The payer rejected the request because a procedure identifier has no type.                                                                                                                                                                                                                    | No type found for procedure component identifier. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1043       | **A date is in the wrong format**Dates in a FHIR bundle follow the date format of the NRCeS profiles. The payer rejected the request because a date does not.                                                                                                                                                                                                                                                      | Date received in the request does not adhere to the NRCES date datatype format. Hence request will not be processed further. Please refere to the date format in NRCES portal.                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1044       | **A date and time is in the wrong format**Dates with times in a FHIR bundle follow the date and time format of the NRCeS profiles. The payer rejected the request because one does not.                                                                                                                                                                                                                            | Date and time received in the request does not adhere to the NRCES date datatype format. Hence request will not be processed further. Please refere to the date time format in NRCES portal.                                                                                                                                                                                                                                                                                                                                                                                                                                      | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1045       | **A claim item has an invalid quantity**Each billed item in the Claim resource of your FHIR bundle states how many units it bills. The payer rejected the request because an item's quantity is missing or not valid.                                                                                                                                                                                              | Invalid quantity received for item. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1046       | **A supporting info entry has no value or date**Every supporting information entry in your FHIR bundle carries its content, either a value or a date. The payer rejected the request because one entry carries neither.                                                                                                                                                                                            | No value or timing details received for supporting info for sequence %s. Hence request will not be processed further. Please reach out to technical team.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1047       | **A supporting info entry has an invalid reference**A supporting information entry can point at another resource in your FHIR bundle, such as a clinical record. The payer rejected the request because an entry's reference is not valid.                                                                                                                                                                         | Invalid reference received in supporting info with sequence number %s. Please try again with valid resource as reference value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1048       | **A supporting info entry references a resource that is not in the bundle**A supporting information entry can point at another resource in your FHIR bundle. The payer rejected the request because the resource the entry points at is not in the bundle.                                                                                                                                                         | No reference resource received for supporting info with sequence number %s. Please try again with valid resource for reference value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1049       | **The payer cannot accept the bundle**The payer could not accept your FHIR bundle as a whole. The message names no element.                                                                                                                                                                                                                                                                                        | Invalid FHIR bundle received. Hence request will not be processed further. please reach out to technical team.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1050       | **A practitioner identifier has no type**Practitioners in your FHIR bundle carry identifiers, such as their HPR id. The payer rejected the request because a practitioner's identifier has no type.                                                                                                                                                                                                                | No type found for practitioner component identifier. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1051       | **A clinical record has no section**Clinical records attached to a preauthorisation or claim travel as Composition resources in the FHIR bundle. A Composition groups its content into sections. The payer rejected the request because a Composition has no section.                                                                                                                                              | No section found for composition component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1052       | **A clinical record section has no references**Clinical records in your FHIR bundle are Composition resources. Each section lists its content as references. The payer rejected the request because a section has no references.                                                                                                                                                                                   | No references found in composition section. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1053       | **A nested clinical record section has an invalid reference**A Composition section in your FHIR bundle can hold child sections, each with references. The payer rejected the request because a reference in a child section is not valid.                                                                                                                                                                          | Invalid reference found in child sections of composition section. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1054       | **A clinical record section is empty**Clinical records in your FHIR bundle are Composition resources made of sections. The payer rejected the request because a section carries no content.                                                                                                                                                                                                                        | No section content found for composition component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1055       | **A clinical record has no subject or its subject is not a patient**Each clinical record in your FHIR bundle is a Composition that names the patient it is about, in its subject. The payer rejected the request because a Composition has no subject, or its subject is not a Patient.                                                                                                                            | No subject found for composition component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1056       | **The patient's contact organization is not an Organization**The payer checks the Patient that each clinical record in your FHIR bundle is about. It rejected the request because that patient's contact organization is not an Organization.                                                                                                                                                                      | Invalid contact organization found for subject in composition component. This should be of type Organization. Hence request will not be processed further. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                      | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1057       | **The patient's general practitioner has the wrong type**The payer checks the Patient that each clinical record in your FHIR bundle is about. It rejected the request because that patient's general practitioner is the wrong type of resource.                                                                                                                                                                   | Invalid general practioner type found for subject in composition component. This should be of type Organization/Practitioner/PractitionerRole. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html                                                                                                                                                                                                                                                                                                                                                  | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1058       | **The patient's managing organization is not an Organization**The payer checks the Patient that each clinical record in your FHIR bundle is about. It rejected the request because that patient's managing organization is not an Organization.                                                                                                                                                                    | Invalid managing organization type found for subject in composition component. This should be of type Organization. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Patient.html                                                                                                                                                                                                                                                                                                                                                                             | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1059       | **A clinical record points at something other than an encounter**Clinical records and observations in your FHIR bundle point at the visit they belong to, an Encounter. The payer rejected the request because a Composition or Observation points at something other than an Encounter.                                                                                                                           | Invalid encounter type found for composition/observation component. This should be of type Encounter. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-DiagnosticReportRecord.html                                                                                                                                                                                                                                                                                                                                                                            | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1060       | **A clinical record has no encounter or its encounter has no subject**Clinical records and observations in your FHIR bundle point at the visit they belong to, an Encounter. That Encounter names the patient. The payer rejected the request because one of these links is missing.                                                                                                                               | No encounter found for composition/observation component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1061       | **An encounter's subject has the wrong resource type**Your bundle carries clinical records as Composition and Observation resources. Each can point at an Encounter, the visit the record belongs to. One of those Encounters names a subject of a type the payer does not accept, so the payer stopped processing your request.                                                                                   | Invalid subject type found for encounter in composition/observation component. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html                                                                                                                                                                                                                                                                                                                                                                                                                | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1062       | **An encounter has no episode of care the payer can find**Your bundle carries clinical records as Composition and Observation resources. Each can point at an Encounter, the visit the record belongs to. The payer could not find an episode of care for one of those Encounters, so it stopped processing your request.                                                                                          | No episode of care found for encounter in composition/observation component. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html                                                                                                                                                                                                                                                                                                                                                                                                                  | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1063       | **An encounter's episode of care has the wrong resource type**Your bundle carries clinical records as Composition and Observation resources. Each can point at an Encounter, the visit the record belongs to. One of those Encounters has an episode of care reference that points at the wrong kind of resource, so the payer stopped processing your request.                                                    | Invalid episode of care type found for encounter in composition/observation component. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html                                                                                                                                                                                                                                                                                                                                                                                                        | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1064       | **An encounter has no based-on reference the payer can find**Your bundle carries clinical records as Composition and Observation resources. Each can point at an Encounter, the visit the record belongs to. The payer could not find the based-on reference for one of those Encounters, so it stopped processing your request.                                                                                   | No based on found for encounter in composition/observation component. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html                                                                                                                                                                                                                                                                                                                                                                                                                         | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1065       | **An encounter's based-on reference has the wrong resource type**Your bundle carries clinical records as Composition and Observation resources. Each can point at an Encounter, the visit the record belongs to. One of those Encounters has a based-on reference that points at the wrong kind of resource, so the payer stopped processing your request.                                                         | Invalid based on type found for encounter in composition/observation component. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html                                                                                                                                                                                                                                                                                                                                                                                                               | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1066       | **An encounter has no appointment the payer can find**Your bundle carries clinical records as Composition and Observation resources. Each can point at an Encounter, the visit the record belongs to. The payer could not find an appointment for one of those Encounters, so it stopped processing your request.                                                                                                  | No appointment found for encounter in composition/observation component. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html                                                                                                                                                                                                                                                                                                                                                                                                                      | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1067       | **An encounter's appointment has the wrong resource type**Your bundle carries clinical records as Composition and Observation resources. Each can point at an Encounter, the visit the record belongs to. One of those Encounters has an appointment reference that points at the wrong kind of resource, so the payer stopped processing your request.                                                            | Invalid appointment type found for encounter in composition/observation component. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html                                                                                                                                                                                                                                                                                                                                                                                                            | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1068       | **An encounter has no reason reference the payer can find**Your bundle carries clinical records as Composition and Observation resources. Each can point at an Encounter, the visit the record belongs to. The payer could not find the reason reference for one of those Encounters, so it stopped processing your request.                                                                                       | No reason reference found for encounter in composition/observation component. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html                                                                                                                                                                                                                                                                                                                                                                                                                 | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1069       | **An encounter's reason reference has the wrong resource type**Your bundle carries clinical records as Composition and Observation resources. Each can point at an Encounter, the visit the record belongs to. One of those Encounters has a reason reference that points at the wrong kind of resource, so the payer stopped processing your request.                                                             | Invalid reason reference type found for encounter in composition/observation component. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html                                                                                                                                                                                                                                                                                                                                                                                                       | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1070       | **A composition has no author**Your bundle carries clinical documents as Composition resources. One of them does not say who wrote it, so the payer stopped processing your request.                                                                                                                                                                                                                               | No author found for composition component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1071       | **A composition's author has the wrong resource type**Your bundle carries clinical documents as Composition resources. One of them names an author of a type the payer does not accept, so the payer stopped processing your request.                                                                                                                                                                              | Invalid author type found for composition component. This should be of type Practitioner / PractitionerRole / Organization / Patient / Device / RelatedPerson. Hence request will not be processed further. Please try again with valid author type for the composition.                                                                                                                                                                                                                                                                                                                                                          | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1072       | **A claim procedure has no procedure reference**The Claim resource in your bundle lists procedures in procedure. One entry does not say which Procedure resource it means, so the payer stopped processing your request.                                                                                                                                                                                           | No procedure reference received for procedure element in claim resource. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1073       | **An observation has no based-on reference**Your bundle carries test results and other findings as Observation resources. The payer could not find the based-on reference for one of them, so it stopped processing your request.                                                                                                                                                                                  | No based on found for observation component. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Observation.html                                                                                                                                                                                                                                                                                                                                                                                                                                                | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1074       | **An observation's based-on reference has the wrong resource type**Your bundle carries test results and other findings as Observation resources. One of them has a based-on reference that points at the wrong kind of resource, so the payer stopped processing your request.                                                                                                                                     | Invalid based on type found for observation component. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Observation.html                                                                                                                                                                                                                                                                                                                                                                                                                                      | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1075       | **An observation has no part-of reference**Your bundle carries test results and other findings as Observation resources. The payer could not find the part-of reference for one of them, so it stopped processing your request.                                                                                                                                                                                    | No part of found for observation component. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Observation.html                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1076       | **An observation's part-of reference has the wrong resource type**Your bundle carries test results and other findings as Observation resources. One of them has a part-of reference that points at the wrong kind of resource, so the payer stopped processing your request.                                                                                                                                       | Invalid part of type found for observation component. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Observation.html                                                                                                                                                                                                                                                                                                                                                                                                                                       | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1077       | **An observation has no subject**Your bundle carries test results and other findings as Observation resources. One of them does not say which patient it is about, so the payer stopped processing your request.                                                                                                                                                                                                   | No subject found for observation component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1078       | **An observation's subject is not a Patient**Your bundle carries test results and other findings as Observation resources. One of them names a subject that is not a Patient, so the payer stopped processing your request.                                                                                                                                                                                        | Invalid subject type found for observation component. This should be of type Patient. Hence request will not be processed further. Please try again with valid subject type for the observation.                                                                                                                                                                                                                                                                                                                                                                                                                                  | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1079       | **The claim has no care team**The Claim resource in your bundle must name the practitioners treating the patient in careTeam. It has none, so the payer stopped processing your request.                                                                                                                                                                                                                           | No care team details received. Hence request will not be processed further. Please add the care team details and try again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1080       | **A practitioner's HPR id is not valid**Each Practitioner in your bundle carries the practitioner's HPR id. The payer did not accept the id on one of them, so it stopped processing your request.                                                                                                                                                                                                                 | Invalid HPR details received for practioner resource with url %s. Hence request will not be processed further. Please try again with valid HPR id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1081       | **An item's service date is not valid**Each item in the Claim resource carries the date or period of service. The payer did not accept the date on one item, so it stopped processing your request.                                                                                                                                                                                                                | Invalid service date received for item with sequence %s in claim resource. Hence request will not be processed further. Please try again with valid item service date.                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1082       | **A composition linked from supporting info has an invalid title**Supporting information on the Claim can point at a Composition, such as a lab report. The payer did not accept the title of one of those Compositions, so it stopped processing your request.                                                                                                                                                    | Invalid title received for composition for supporting info with sequence %s in claim resource. Hence request will not be processed further. Please try again with valid composition title.                                                                                                                                                                                                                                                                                                                                                                                                                                        | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1083       | **A practitioner has no HPR id**Each Practitioner in your bundle must carry the practitioner's HPR id. One of them has none, so the payer stopped processing your request.                                                                                                                                                                                                                                         | No HPR details found for the practitioner for resource %s. Hence request will not be processed further. Please send the details in the identifier for Practitioner resource with category code as HPIN.                                                                                                                                                                                                                                                                                                                                                                                                                           | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1084       | **A reference points at a questionnaire response that is not in the bundle**Supporting information can point at a QuestionnaireResponse, for example the answers to a policy or treatment questionnaire. One reference points at a url with no QuestionnaireResponse behind it, so the payer stopped processing your request.                                                                                      | No questionnaire response resource found for url %s. Hence request will not be processed further. Please add the resources for all the references given in the FHIR bundle and try again.                                                                                                                                                                                                                                                                                                                                                                                                                                         | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1085       | **A questionnaire response reference points at the wrong resource type**Supporting information can point at a QuestionnaireResponse. One such reference points at an entry of another resource type, so the payer stopped processing your request.                                                                                                                                                                 | Invalid questionnaire response resource type found in the FHIR bundle for url %s. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1086       | **A reference points at a procedure that is not in the bundle**Each Claim.procedure entry points at a Procedure resource in the bundle. One reference points at a url with no Procedure behind it, so the payer stopped processing your request.                                                                                                                                                                   | No procedure resource found for url %s. Hence request will not be processed further. Please add the resources for all the references given in the FHIR bundle and try again.                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1087       | **A procedure reference points at the wrong resource type**Each Claim.procedure entry points at a Procedure resource in the bundle. One reference points at an entry of another resource type, so the payer stopped processing your request.                                                                                                                                                                       | Invalid procedure resource type found in the FHIR bundle for url %s. Hence request will not be processed further. Procedure resource type is expected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1088       | **A composition failed the payer's checks**Your bundle carries clinical documents as Composition resources. One of them failed the payer's checks, and the message does not name the element. The payer stopped processing your request.                                                                                                                                                                           | Invalid composition details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1089       | **The claim has no billing items**The Claim resource lists what you are billing for in item. It has no items, so the payer stopped processing your request.                                                                                                                                                                                                                                                        | No billing items found. Hence request will not be processed further. Please try again with valid billing items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1090       | **The coverage has no identifier**Every eligibility, preauthorisation and claim bundle carries a Coverage resource for the beneficiary's policy. Yours has no identifier, so the payer could not tell which policy you mean.                                                                                                                                                                                       | No identifier found for coverage component. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1091       | **The coverage identifier has no type**Every eligibility, preauthorisation and claim bundle carries a Coverage resource for the beneficiary's policy. Its identifier has no type, so the payer stopped processing your request.                                                                                                                                                                                    | No type found for coverage component identifier. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1092       | **The payer failed while processing your request**The payer hit a failure while processing your request. The message names no element in your bundle. It asks you to start a new request.                                                                                                                                                                                                                          | Something went wrong while processing request, kindly intiate new request                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1093       | **An encounter linked from a composition has no subject**Your bundle carries clinical records as Composition and Observation resources. Each can point at an Encounter, the visit the record belongs to. The Encounter behind one Composition does not say which patient it is about, so the payer stopped processing your request.                                                                                | No subject found for encounter in composition component. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html                                                                                                                                                                                                                                                                                                                                                                                                                                      | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1094       | **An encounter's subject has the wrong resource type**Your bundle carries clinical records as Composition and Observation resources. Each can point at an Encounter, the visit the record belongs to. One of those Encounters names a subject of a type the payer does not accept, so the payer stopped processing your request.                                                                                   | Invalid subject type found for encounter in composition/observation component. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Encounter.html                                                                                                                                                                                                                                                                                                                                                                                                                | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1095       | **The claim carries no valid discharge information**A claim must say how the patient was discharged. Yours carries no valid discharge information, so the payer stopped processing it.                                                                                                                                                                                                                             | Invalid discharge information received for claim request. Hence request will not be processed further. Please send the discharge information in supporting info in claim resource, with category as DIS (refer - https\://www\.nrces.in/ndhm/fhir/r4/ValueSet-ndhm-supportinginfo-category.html), and codes in LAMA/DAMA/DTH/DTM (refer - https\://www\.nrces.in/ndhm/fhir/r4/ValueSet-ndhm-supportinginfo-code.html).                                                                                                                                                                                                            | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1096       | **A death discharge carries no valid death date**When the discharge type is death, the claim must carry the date of death. Yours carries no valid death date, so the payer stopped processing it.                                                                                                                                                                                                                  | Invalid death date received for claim request. Hence request will not be processed further. Please send the death date information in supporting info in claim resource, with category as ONS (refer - https\://www\.nrces.in/ndhm/fhir/r4/ValueSet-ndhm-supportinginfo-category.html), and code as DTM (refer - https\://www\.nrces.in/ndhm/fhir/r4/ValueSet-ndhm-supportinginfo-code.html).                                                                                                                                                                                                                                     | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1097       | **The request arrived with no encrypted payload**Every request carries your FHIR bundle, encrypted, in the payload property of the request body. The payer opened your request and found no encrypted payload.                                                                                                                                                                                                     | No payload found in the request. Please ensure that the request that is being sent, contains encrypted payload within the mandatory payload properties.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1098       | **The registration date has the wrong value type**The Claim resource carries the patient's registration date as a supporting info entry with category OTH and code EDT. That entry's value has a type the payer does not accept.                                                                                                                                                                                   | Value type received as %s for category - OTH and code - EDT for item with sequence %s in supporting info in claim resource. In supporting info list, item with category - OTH and code - EDT combination is used to get the registration date. So the registration date should be sent as timing (date or period) or as a string value, adhering to the NRCES standards, with the category - OTH and code - EDT.                                                                                                                                                                                                                  | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1099       | **The discharge date has the wrong value type**The claim carries the discharge date as a supporting info entry with category ONS and code DSDE. That entry's value has a type the payer does not accept.                                                                                                                                                                                                           | Value type received as %s for category - ONS and code - DSDE for item with sequence %s in supporting info in claim resource. In supporting info list, item with category - ONS and code - DSDE combination is used to get the discharge date. So the discharge date should be sent as timing (date or period) or as a string value, adhering to the NRCES standards, with the category - ONS and code - DSDE.                                                                                                                                                                                                                     | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1101       | **The eligibility purpose is not valid**Every eligibility check says what you want to know, in CoverageEligibilityRequest.purpose. The payer did not accept the purpose you sent, so it returned no result.                                                                                                                                                                                                        | Invalid purpose received as (%s) for beneficiary id (%s) from hospital id (%s). Hence no result will be returned. Please try again with a valid purpose.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Coverage eligibilityPreauthorisation                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                 |
| PAYR-1102       | **The id you searched with is not valid**The payer looks up the beneficiary from the id in your request. The id you sent is not one it recognises.                                                                                                                                                                                                                                                                 | Invalid search parameter requested. Please try again with a valid id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Coverage eligibilityPreauthorisationClaim                                     | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1103       | **The care plan id is not valid**Your request carries a care plan id. The payer does not recognise the id you sent, so it stopped processing the request.                                                                                                                                                                                                                                                          | Invalid careplan id received. Please try again with valid careplan id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Coverage eligibilityPreauthorisation                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                 |
| PAYR-1104       | **More than one beneficiary record matches**The payer looks up the beneficiary from the identifiers in your request. They match more than one record in its system, so it cannot tell which person you mean.                                                                                                                                                                                                       | Multiple records found for the beneficiary. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Coverage eligibilityPreauthorisation                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                 |
| PAYR-1105       | **The payer has no configuration for your hospital**The payer keeps a configuration for each hospital it deals with. It found none for yours, so it could not process your check.                                                                                                                                                                                                                                  | Hospital configuration not found. Please contact support team.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1106       | **The payer has no details for a requested procedure**An auth-requirements check lists the procedures you want to know about. The payer holds no details for one of them.                                                                                                                                                                                                                                          | No details found for the requested procedures in the system.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1107       | **The check carries no billable item**An auth-requirements check must list the procedures you want to know about. Yours carries no item the payer can bill against.                                                                                                                                                                                                                                                | No billable item received. Please try again with valid item data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1108       | **The payer has no details for the requested stratification**An item in an eligibility check can carry a stratification, such as a ward or care level. The payer holds no details for the one you sent.                                                                                                                                                                                                            | No details found for the requested stratification in the system.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1109       | **The payer has no details for a requested investigation**An eligibility check can ask about investigations, such as laboratory tests. The payer holds no details for one you sent.                                                                                                                                                                                                                                | No details found for the requested investigations in the system.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1110       | **The payer has no details for a requested implant**An eligibility check can ask about implants used in a procedure. The payer holds no details for one you sent.                                                                                                                                                                                                                                                  | No details found for the requested implants in the system.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1111       | **A payer rule rejected the request**The payer applies business rules to every check. One of them rejected yours. The message does not say which rule failed.                                                                                                                                                                                                                                                      | Rule failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1112       | **The payer id is not valid**Your check names the payer it is for. The payer id you sent is not valid, so the payer stopped processing the check.                                                                                                                                                                                                                                                                  | Invalid payer id received. Please try again ith valid payer details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1113       | **An item code is not valid**Each item in an eligibility check carries a package or procedure code. The payer did not accept the code named in the message.                                                                                                                                                                                                                                                        | Invalid item code received as %s. Please try again with valid data                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1114       | **An item's speciality code is not valid**Each item in an eligibility check carries a speciality code, such as the code for general medicine. The payer did not accept the one on the item named in the message.                                                                                                                                                                                                   | Invalid speciality code received as %s for item %s. Please try again with valid data. Speciality code is available as the code of the category for specific cost of plan in isurance plan                                                                                                                                                                                                                                                                                                                                                                                                                                         | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1115       | **An item's quantity is not valid**Each item in an eligibility check carries a quantity. The payer did not accept the quantity on the item named in the message.                                                                                                                                                                                                                                                   | Invalid procedure quantity received as %s for item %s. Please try again with valid data. Item quantity should be greater than 1                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1116       | **Your hospital is not authorised under the policy**A hospital can raise cases only under the policies it is authorised for. Yours is not authorised under the policy in the message.                                                                                                                                                                                                                              | Hospital is not authorized to raise any case under policy %s. Hence request will not be processed further. Please connect with the support team to get the required authorization                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1117       | **The payer has no details for the policy**Your check names the beneficiary's policy. The payer holds no details for the policy named in the message.                                                                                                                                                                                                                                                              | No policy details found for %s. Hence request will not be processed further                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1118       | **The payer has no details for the requested items**An auth-requirements check lists the items you want to know about. The payer holds no details for them.                                                                                                                                                                                                                                                        | No details found for requested items. Hence request will not be processed further                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1119       | **The payer received no details for the payer id from the exchange**The payer looks up the payer id in your request with the exchange. The exchange returned no details for the id in the message.                                                                                                                                                                                                                 | No payer details received for payer id %s from HCX. Please try again with valid payer details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1120       | **The reference id has been used before**Each request carries a reference id. The payer has already received one with the id in the message.                                                                                                                                                                                                                                                                       | Duplicate reference id found as %s. Please try again with valid reference details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1121       | **The policy is not found for this beneficiary**The payer checks that the beneficiary holds the policy in your request. It holds no record of that policy for that beneficiary.                                                                                                                                                                                                                                    | No policy details found for %s for beneficiary %s. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1122       | **The beneficiary has no policy with the payer**The payer looks for the policies held by the beneficiary in your request. It found none.                                                                                                                                                                                                                                                                           | No policy details found for beneficiary %s. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1123       | **The beneficiary is not covered by this payer**You sent the check to a payer that does not cover the beneficiary. The beneficiary must be enrolled in one of its policies first.                                                                                                                                                                                                                                  | Beneficiary is not a covered member for requested payer. Please enroll beneficiary for applicable policy of requested payer and try again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Coverage eligibility                                                          | `/v1/coverageeligibility/check``/v1/coverageeligibility/on_check`                                                                                                                                            |
| PAYR-1201       | **Claimed amount is zero or above the wallet balance**The amount you asked the payer to approve is not allowed. It is zero or less, or more than the balance left in the beneficiary's wallet. A PMJAY family shares one wallet across every member's treatment.                                                                                                                                                   | Invalid claimed amount received for case number %s. Please try again with a valid claim amount. Claimed amount should be greater than INR 0 and less than equals to balance wallet amount of the beneficiary.                                                                                                                                                                                                                                                                                                                                                                                                                     | PreauthorisationClaim                                                         | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1202       | **Speciality code is not in the insurance plan**An item in your request names a speciality the payer does not recognise for your hospital. Speciality codes must come from the hospital's insurance plan.                                                                                                                                                                                                          | Invalid speciality code received as %s for item %s for case number %s. Please try again with valid data. Speciality code is available as the code of the category for specific cost of plan in isurance plan.                                                                                                                                                                                                                                                                                                                                                                                                                     | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1203       | **Speciality description does not match the insurance plan**The speciality description you sent for a procedure does not match the payer's text for that speciality. Descriptions must come from the hospital's insurance plan, word for word.                                                                                                                                                                     | Invalid speciality description received as %s for procedure %s for case number %s. Please try again with valid data. Speciality description is available as the display of the category for specific cost of plan in isurance plan.                                                                                                                                                                                                                                                                                                                                                                                               | PreauthorisationClaim                                                         | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1204       | **Procedure code is not in the insurance plan**You requested a procedure code that the payer does not offer at your hospital. Procedure codes must come from the hospital's insurance plan.                                                                                                                                                                                                                        | Invalid procedure code received as %s for case number %s. Please try again with valid data. Procedure code is available as the code of the type for benefit component, of specific cost, of plan in isurance plan.                                                                                                                                                                                                                                                                                                                                                                                                                | PreauthorisationClaim                                                         | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1205       | **Procedure description does not match the insurance plan**The description you sent for a procedure does not match the payer's text for that procedure code. Descriptions must come from the hospital's insurance plan, word for word.                                                                                                                                                                             | Invalid procedure description received as %s for procedure %s for case number %s. Please try again with valid data. Procedure description is available as the display of the type for benefit component, of specific cost, of plan in isurance plan.                                                                                                                                                                                                                                                                                                                                                                              | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1206       | **Procedure type is not accepted**The type you gave a requested procedure is not one the payer accepts for it.                                                                                                                                                                                                                                                                                                     | Invalid procedure type received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1207       | **Procedure factor is not accepted**The factor you sent for a requested procedure is not one the payer accepts.                                                                                                                                                                                                                                                                                                    | Invalid procedure factor received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1208       | **Item quantity is not accepted**The quantity you sent for an item is not one the payer accepts.                                                                                                                                                                                                                                                                                                                   | Invalid procedure quantity received as %s for item %s for case number %s. Please try again with valid data. Item quantity should be greater than 1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1209       | **Item net amount is zero or less**An item in your request has a net amount of zero or less. Every item must carry a positive amount.                                                                                                                                                                                                                                                                              | Invalid net amount received as INR %s for item %s for case number %s. Please try again with valid data. Item net amount should be greater than INR 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1210       | **Procedure status is not accepted**The status you sent for a requested procedure is not one the payer accepts.                                                                                                                                                                                                                                                                                                    | Invalid procedure status received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1211       | **Beneficiary and care plan match no rule at this hospital**The payer found no rule that lets this beneficiary receive this care plan at your hospital.                                                                                                                                                                                                                                                            | Requested beneficary details and careplan details does not match any criteria for processing the case at this hospital. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1212       | **Enhancement has no approved preauthorisation**You asked to extend a preauthorisation the payer never approved. An enhancement only extends a preauthorisation that is already approved.                                                                                                                                                                                                                          | No previous preauthorization approved record found for the enhancement request for case number %s. Hence request will not be processed further. Please initiate a new preauthorization.                                                                                                                                                                                                                                                                                                                                                                                                                                           | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1213       | **Enhancement sent while the case is still in progress**The payer is still deciding an earlier request on this case. It accepts no enhancement until that adjudication is complete.                                                                                                                                                                                                                                | Existing case in progress found for case number %s. Hence enhancement request will not be accepted. Please try after the adjudication is completed for the current case.                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1214       | **Resubmission has no approved preauthorisation**You resubmitted a preauthorisation that the payer holds no approval for. It processes the request no further.                                                                                                                                                                                                                                                     | No previous preauthorization approved record found for the resubmission request for case number %s. Hence request will not be processed further. Please initiate a new preauthorization.                                                                                                                                                                                                                                                                                                                                                                                                                                          | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1215       | **Resubmission sent while the case is still in progress**The payer is still deciding an earlier request on this case. It accepts no resubmission until that adjudication is complete.                                                                                                                                                                                                                              | Existing case in progress found for case number %s. Hence resubmission request will not be accepted. Please try after the adjudication is completed for the current case.                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1216       | **New preauthorisation sent for a case already in progress**A request on this case is still in progress with the payer. It accepts no new preauthorisation on the case until that finishes.                                                                                                                                                                                                                        | Existing case in progress found for case number %s. Hence new preauthorization request will not be accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1217       | **New preauthorisation sent for a case already approved**This case already has an approved preauthorisation. To change it, extend it or resubmit it. Do not open a new one.                                                                                                                                                                                                                                        | Previous preauthorization approved record found for the new preauthorization request for case number %s. Hence request will not be processed further. Please initiate enhancement/resubmission.                                                                                                                                                                                                                                                                                                                                                                                                                                   | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1218       | **Query response sent for a case that was not queried**You answered a query the payer never raised. It holds no queried preauthorisation for this case.                                                                                                                                                                                                                                                            | No queried preauthorization record found for the query update request for case number %s. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1219       | **Case is not in the queried state**You sent a query response for a case the payer has not queried. It processes the request no further.                                                                                                                                                                                                                                                                           | Case number %s is not queried. Hence query updation request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1220       | **Investigation description does not match its code**An investigation in your request carries a description that does not match its code.                                                                                                                                                                                                                                                                          | Invalid investigation description received as %s for investigation code %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | PreauthorisationClaim                                                         | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1221       | **Investigation code is not valid**An investigation in your request carries a code the payer does not recognise.                                                                                                                                                                                                                                                                                                   | Invalid investigation code received as %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | PreauthorisationClaim                                                         | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1222       | **Investigation status is not accepted**The status you sent for an investigation is not one the payer accepts.                                                                                                                                                                                                                                                                                                     | Invalid investigation status received as %s for investigation %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1223       | **Investigation attachment is not valid**The document attached to an investigation could not be accepted.                                                                                                                                                                                                                                                                                                          | Invalid investigation attachment received for investigation %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1224       | **Implant description does not match its code**An implant in your request carries a description that does not match its code.                                                                                                                                                                                                                                                                                      | Invalid implant description received as %s for implant code %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | PreauthorisationClaim                                                         | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1225       | **Implant code is not valid**An implant in your request carries a code the payer does not recognise.                                                                                                                                                                                                                                                                                                               | Invalid implant code received as %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | PreauthorisationClaim                                                         | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1226       | **Implant status is not accepted**The status you sent for an implant is not one the payer accepts.                                                                                                                                                                                                                                                                                                                 | Invalid implant status received as %s for investigation %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1227       | **Implant attachment is not valid**The document attached to an implant could not be accepted.                                                                                                                                                                                                                                                                                                                      | Invalid implant attachment received for investigation %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1228       | **Implant quantity is not accepted**The quantity you sent for an implant is not one the payer accepts.                                                                                                                                                                                                                                                                                                             | Invalid implant quantity received as %s for implant %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1229       | **Implant net amount is not accepted**The net amount you sent for an implant is not one the payer accepts.                                                                                                                                                                                                                                                                                                         | Invalid implant net amount received as INR %s for implant %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1230       | **Implant unit price is not accepted**The unit price you sent for an implant is not one the payer accepts.                                                                                                                                                                                                                                                                                                         | Invalid implant unit price received as INR %s for implant %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1231       | **Claim already raised for this case**The final claim for this case is already raised. After that, the payer accepts no preauthorisation request on the case.                                                                                                                                                                                                                                                      | Claim has already been raised for case number %s. Hence preauthorization request will not be accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1232       | **Investigations missing for a private hospital**Your request carries no investigation details. For a private hospital, investigation details are mandatory.                                                                                                                                                                                                                                                       | No investigation found for case number %s. Investigation details are mandatory for private hospitals.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1233       | **Wallet short and patient liability not allowed**The request costs more than the beneficiary's wallet holds. Patient liability does not apply at your hospital, so the shortfall cannot move to the patient.                                                                                                                                                                                                      | Patient liability is not aplicable for the hospital and beneficiary do not have enough wallet balance with deficit amount INR %s for the requested preauthorization for case number %s.                                                                                                                                                                                                                                                                                                                                                                                                                                           | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1234       | **No preauthorisation found for the case number**Your request refers to a case the payer holds no preauthorisation for.                                                                                                                                                                                                                                                                                            | No preauthorization record found for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1235       | **Wallet balance is insufficient**The beneficiary's wallet does not hold enough balance for this request. A PMJAY family shares one wallet, so treatment for any member draws it down.                                                                                                                                                                                                                             | Insufficient wallet balance. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1236       | **Claim type is not in-patient or out-patient**The request does not say, in a form the payer accepts, whether this is in-patient or out-patient care.                                                                                                                                                                                                                                                              | Invalid claim type (in-patient/out-patient) received. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1237       | **Beneficiary has an active preauthorisation at another hospital**The beneficiary already has an active preauthorisation at another hospital. The payer refuses a second one while that stays active.                                                                                                                                                                                                              | Beneficiary is having an active preauthorization request at %s. Hence the request will not be processed. Kindly inform %s to cancel the active preauthorization request or raise a claim to proceed with current preauthorization.                                                                                                                                                                                                                                                                                                                                                                                                | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1238       | **Beneficiary has an active preauthorisation at your hospital**The beneficiary already has an active preauthorisation at your hospital. Close it before you open another.                                                                                                                                                                                                                                          | Beneficiary is having an active preauthorization request at this hospital with reference number %s. Hence the request will not be processed. Kindly cancel the active preauthorization request or raise a claim to proceed with current preauthorization.                                                                                                                                                                                                                                                                                                                                                                         | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1239       | **Hospital configuration not found**The payer has no configuration for your hospital, so it cannot process the request.                                                                                                                                                                                                                                                                                            | Hospital configuration not found. Please contact support team.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1240       | **Requested procedures not found**The payer holds no details for one or more procedures in your request.                                                                                                                                                                                                                                                                                                           | No details found for the requested procedures in the system.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1241       | **Registration date is not valid**The patient's registration date in your request is missing or not a date the payer accepts.                                                                                                                                                                                                                                                                                      | Invalid registration date received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1242       | **Registration date format is not valid**The patient's registration date is present, but not in a format the payer accepts.                                                                                                                                                                                                                                                                                        | Invalid registration date format received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1243       | **Admission date is not valid**The admission date in your request is missing or not a date the payer accepts.                                                                                                                                                                                                                                                                                                      | Invalid admission date received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1244       | **Admission date format is not valid**The admission date is present, but not in a format the payer accepts.                                                                                                                                                                                                                                                                                                        | Invalid admission date format received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1245       | **A scheme rule failed**Your request broke one of the payer's scheme rules. The payer can put the rule's own text in the message in place of Rule failure.                                                                                                                                                                                                                                                         | Rule failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1246       | **Payer id is not valid**The request names the payer with an identifier the payer does not accept.                                                                                                                                                                                                                                                                                                                 | Invalid payer id received as %s. Please try again with valid payer id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1247       | **Payer details not received from the exchange**The payer could not get the details for the payer id in your request from NHCX, so it stopped processing.                                                                                                                                                                                                                                                          | Payer details for payer id %s is not received from HCX for the request. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1248       | **Item code is not valid**An item in your request carries a code the payer does not accept.                                                                                                                                                                                                                                                                                                                        | Invalid item code received as %s for item sequence %s case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1249       | **Item sequence is not valid**An item in your request carries a sequence number the payer does not accept.                                                                                                                                                                                                                                                                                                         | Invalid item sequence received as %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1250       | **Policy is not listed**The policy code in your request is not one the payer lists.                                                                                                                                                                                                                                                                                                                                | Requested policy %s is not listed. Please try again with valid policy code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1251       | **No billable treatment plan**Your request carries nothing the payer can bill against for this case.                                                                                                                                                                                                                                                                                                               | No billable treatment plan received for case number %s. Please try again with valid treatment plan data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1252       | **Case is not in a state that can be cancelled**You asked to cancel a preauthorisation that is not in a cancellable state. Only a submitted or approved preauthorisation can be cancelled.                                                                                                                                                                                                                         | Case number %s is not in active preauthorization state with the current status of the case with the payer system is %s. Hence the preauthorization can not be cancelled. Only the cases with current status as preauthorization submitted or preauthorization approved can be cancelled.                                                                                                                                                                                                                                                                                                                                          | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit``/v1/task/on_submit``/v1/task/submit`                                                                                                                             |
| PAYR-1253       | **Case is already cancelled**You asked to cancel a preauthorisation that is already cancelled.                                                                                                                                                                                                                                                                                                                     | Case number %s is already cancelled. Hence the preauthorization can not be cancelled again. Only the cases with current status as preauthorization submitted or preauthorization approved can be cancelled.                                                                                                                                                                                                                                                                                                                                                                                                                       | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit``/v1/task/on_submit``/v1/task/submit`                                                                                                                             |
| PAYR-1254       | **Treatment guideline questionnaire response missing**A procedure you requested needs a completed Standard Treatment Guideline (STG) checklist. Your request did not include the response to it. STGs are mandatory in PMJAY.                                                                                                                                                                                      | Response for STG Questionnaire id %s is mandatory for procedure code %s. Hence the preauthorization request will not be processed as the questionnaire response is not received for procedure code.                                                                                                                                                                                                                                                                                                                                                                                                                               | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1255       | **Case number already cancelled**The case number in your request belongs to a cancelled preauthorisation. A cancelled case number accepts no further preauthorisation.                                                                                                                                                                                                                                             | Case number %s is already cancelled. Hence no preauthorization request will be accepted for this case number. New preauthorization request needs to be raised with new case/reference number to proceed further.                                                                                                                                                                                                                                                                                                                                                                                                                  | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1256       | **No biometric authentication and no consent questionnaire**A new preauthorisation must prove the patient is present at your hospital. Your request carried neither biometric authentication nor the Authentication Consent Questionnaire response.                                                                                                                                                                | Response for Authentication Consent Questionnaire is missing for case number %s. This must be sent if the biometric authentication for patient is not available. For new preauthorization request, either biometric authentication for patient or response for Authentication Consent questionnaire must be sent. Please check/update the insurance plan for the policy for the details of the questionnaire. Please adhere to the response of the coverage eligibility for auth-requirements purpose to check the mandatory documents to be attached with the request                                                            | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1257       | **Payment already initiated for the case**Payment for this case has already started. A case at that stage can no longer be cancelled.                                                                                                                                                                                                                                                                              | Payment is initiated for case number %s. Hence the preauthorization can not be cancelled again. Only the cases with current status as preauthorization submitted or preauthorization approved can be cancelled                                                                                                                                                                                                                                                                                                                                                                                                                    | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit``/v1/task/on_submit``/v1/task/submit`                                                                                                                             |
| PAYR-1258       | **Payment already cleared for the case**Payment for this case is already complete. A paid case can no longer be cancelled.                                                                                                                                                                                                                                                                                         | Payment is accomplished/cleared for case number %s. Hence the preauthorization can not be cancelled again. Only the cases with current status as preauthorization submitted or preauthorization approved can be cancelled                                                                                                                                                                                                                                                                                                                                                                                                         | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit``/v1/task/on_submit``/v1/task/submit`                                                                                                                             |
| PAYR-1259       | **Newborn date of birth missing**A newborn case must carry the baby's date of birth. Your request did not. In PMJAY, a newborn with no Member ID yet is treated on a parent's card, as a child linked to the parent.                                                                                                                                                                                               | DOB is missing for new born for the case number (%s) with correlation id as (%s) at (%s)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1260       | **Newborn date of birth is in the future**The baby's date of birth in your request is in the future. In PMJAY, a newborn with no Member ID yet is treated on a parent's card, as a child linked to the parent.                                                                                                                                                                                                     | DOB cannot be a future date for the case number (%s) with correlation id as (%s) at (%s)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1261       | **Newborn details are not valid**The newborn details in your request are not valid. In PMJAY, a newborn with no Member ID yet is treated on a parent's card, as a child linked to the parent.                                                                                                                                                                                                                      | Invalid new born details for the case number (%s) with correlation id as (%s) at (%s)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1262       | **Newborn gender missing**A newborn case must carry the baby's gender. Your request did not. In PMJAY, a newborn with no Member ID yet is treated on a parent's card, as a child linked to the parent.                                                                                                                                                                                                             | Gender is mandatory for the new born beneficiary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1263       | **Newborn documents missing**A newborn case needs supporting documents, and one is missing from your request. In PMJAY, a newborn with no Member ID yet is treated on a parent's card, as a child linked to the parent.                                                                                                                                                                                            | Documents are mandatory for the new born beneficiary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1264       | **Newborn documents missing**A newborn case needs supporting documents, and one is missing from your request. In PMJAY, a newborn with no Member ID yet is treated on a parent's card, as a child linked to the parent.                                                                                                                                                                                            | Documents are mandatory for the new born beneficiary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1265       | **Newborn documents missing**A newborn case needs supporting documents, and one is missing from your request. In PMJAY, a newborn with no Member ID yet is treated on a parent's card, as a child linked to the parent.                                                                                                                                                                                            | Documents are mandatory for the new born beneficiary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1266       | **Newborn documents missing**A newborn case needs supporting documents, and one is missing from your request. In PMJAY, a newborn with no Member ID yet is treated on a parent's card, as a child linked to the parent.                                                                                                                                                                                            | Documents are mandatory for the new born beneficiary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1267       | **Active newborn preauthorisation at your hospital**The beneficiary already has an active preauthorisation for a newborn case at your hospital. Close it before you open another.                                                                                                                                                                                                                                  | Beneficiary is having an active preauthorization request for new born case at this hospital with reference number %s. Hence the request will not be processed. Kindly cancel the active preauthorization request or raise a claim to proceed with current preauthorization                                                                                                                                                                                                                                                                                                                                                        | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1268       | **Active newborn preauthorisation at another hospital**The beneficiary already has an active preauthorisation for a newborn case at another hospital. The payer refuses a second one while that stays active.                                                                                                                                                                                                      | Beneficiary is having an active preauthorization request for new born case at %s. Hence the request will not be processed. Kindly inform %s to cancel the active preauthorization request or raise a claim to proceed with current preauthorization                                                                                                                                                                                                                                                                                                                                                                               | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1269       | **Newborn is older than 6 years**A newborn case is only for a child aged 6 years or under. The date of birth you sent is more than 6 years ago.                                                                                                                                                                                                                                                                    | Date of birth received for new born beneficiary exceeds 6 years before the current date. New born cases can be raised only for the beneficiary whose date of birth is within 6 years of current date                                                                                                                                                                                                                                                                                                                                                                                                                              | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1270       | **Item LM100 sent on a preauthorisation**Your preauthorisation includes item LM100. LM100 belongs only on a claim, for a patient who leaves against medical advice.                                                                                                                                                                                                                                                | Item LM100 is not applicable for preauthorization request. This item is expected/mandated only during claim submission if the patient is discharged after/during surgery under LAMA/DAMA category for PMJAY cases.                                                                                                                                                                                                                                                                                                                                                                                                                | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1271       | **Consent questionnaire answer missing**Your request used the Authentication Consent Questionnaire in place of biometrics, but one of its questions has no answer.                                                                                                                                                                                                                                                 | No value received for link id %s for Authentication Consent Questionnaire for preauthorization request. This must be sent if the biometric authentication for patient is not available. For new preauthorization request, either biometric authentication for patient or response for Authentication Consent questionnaire must be sent. Please check/update the insurance plan for the policy for the details of the questionnaire. Please adhere to the response of the coverage eligibility for auth-requirements purpose to check the mandatory documents to be attached with the request.                                    | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1272       | **Biometric user token is not valid**The token that proves the patient's biometric authentication is not valid. A user token lasts 30 minutes after verification.                                                                                                                                                                                                                                                  | Invalid biometric user token received. Please try again with valid valid biometric details of the beneficiary. For any issues with biometric, please try with Authentication Consent Questionnaire, details for which has been received in response for coverage eligibliity auth-requirements.                                                                                                                                                                                                                                                                                                                                   | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1273       | **Questionnaire not found for the selection**A questionnaire response in your request points at a questionnaire the payer cannot find.                                                                                                                                                                                                                                                                             | No questionnaire found for the received selection. Please validate the questionnaire url from insurance plan/coverage auth-requirements response.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Preauthorisation                                                              | `/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                                                                  |
| PAYR-1301       | **A claim already exists for this case**The case you named already has a claim, so the payer will not accept a new claim for it. You receive this code when your system sends a second new claim for one case.                                                                                                                                                                                                     | Claim has already been raised for case number %s. Hence new claim request will not be accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1302       | **No approved preauthorisation for this case**A claim is paid against an approved preauthorisation. The payer found none for the case your claim names, so it will not accept the claim.                                                                                                                                                                                                                           | No preauthorization approved record found for case number %s. Hence new claim request will not be accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1303       | **No active claim to update for this case**A query response updates a claim that is still open. The payer found no active claim for the case you named, so it refused the update.                                                                                                                                                                                                                                  | No active claim record found for case number %s. Hence query updation request will not be accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1304       | **The claim for this case is not under query**You can answer a query only while the payer is waiting for your answer. The payer holds no queried claim for the case you named.                                                                                                                                                                                                                                     | No claim queried record found for case number %s. Hence query updation request will not be accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1305       | **The use case is not valid for this case**Every claim request declares what it is: a new claim or a resubmission. The payer did not accept the use case your request declared for this case.                                                                                                                                                                                                                      | Invalid usecase requested for case number %s. Please try again with valid usecase.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1306       | **The procedure is not in the preauthorisation request**A claim is checked item by item against the preauthorisation for the case. Your claim bills a procedure that the preauthorisation request did not contain.                                                                                                                                                                                                 | No item found in preauthorization request for procedure %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1307       | **The procedure quantity is not valid**The payer checked the quantity on a claimed procedure and did not accept it for this case.                                                                                                                                                                                                                                                                                  | Invalid quantity requested for procedure %s with item sequence %s for case number %s. Please try again with valid quantity.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1308       | **The procedure is not in the active claim**An update to an open claim, such as a query response, must refer to items already in that claim. Your request names a procedure the active claim does not contain.                                                                                                                                                                                                     | No item found in active claim request for procedure %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1309       | **The implant is not in the preauthorisation request**A claim is checked item by item against the preauthorisation for the case. Your claim bills an implant that the preauthorisation request did not contain.                                                                                                                                                                                                    | No item found in preauthorization request for implant %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1310       | **The implant quantity is not valid**The payer checked the quantity on a claimed implant and did not accept it for this case.                                                                                                                                                                                                                                                                                      | Invalid quantity requested for implant %s with item sequence %s for case number %s. Please try again with valid quantity.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1311       | **The implant is not in the active claim**An update to an open claim, such as a query response, must refer to items already in that claim. Your request names an implant the active claim does not contain.                                                                                                                                                                                                        | No item found in active claim request for implant %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1312       | **The investigation is not in the preauthorisation request**A claim is checked item by item against the preauthorisation for the case. Your claim bills an investigation that the preauthorisation request did not contain.                                                                                                                                                                                        | No item found in preauthorization request for investigation %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1313       | **The investigation quantity is not valid**The payer checked the quantity on a claimed investigation and did not accept it for this case.                                                                                                                                                                                                                                                                          | Invalid quantity requested for investigation %s with item sequence %s for case number %s. Please try again with valid quantity.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1314       | **The investigation is not in the active claim**An update to an open claim, such as a query response, must refer to items already in that claim. Your request names an investigation the active claim does not contain.                                                                                                                                                                                            | No item found in active claim request for investigation %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1315       | **The procedure was rejected at preauthorisation**When the payer decided the preauthorisation, it rejected one of the procedures. Your claim bills that procedure anyway, so the payer refused the claim.                                                                                                                                                                                                          | Rejected item found for preauthorization for procedure %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1316       | **The investigation was rejected at preauthorisation**When the payer decided the preauthorisation, it rejected one of the investigations. Your claim bills that investigation anyway, so the payer refused the claim.                                                                                                                                                                                              | Rejected item found for preauthorization for investigation %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1317       | **The implant was rejected at preauthorisation**When the payer decided the preauthorisation, it rejected one of the implants. Your claim bills that implant anyway, so the payer refused the claim.                                                                                                                                                                                                                | Rejected item found for preauthorization for implant %s with item sequence %s for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1318       | **The claim has no requested treatment plan**The payer looks for the treatment your hospital requested for the case. It found none in the claim.                                                                                                                                                                                                                                                                   | No requested treatment plan found for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1319       | **The claim has no requested investigation plan**The payer looks for the investigations your hospital requested for the case. It found none in the claim.                                                                                                                                                                                                                                                          | No requested investigation plan found for case number %s. Please try again with valid items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1320       | **The payer has no details for the requested investigations**The payer looked up the investigations in your claim and found no details for them in its system.                                                                                                                                                                                                                                                     | No details found for the requested investigations in the system. Hence request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1321       | **The workflow id is not valid for this step**Every request names its step in the claim cycle with a workflow id. The payer could not process the workflow id your request carried.                                                                                                                                                                                                                                | Error occurred while processing the request due to invalid workflow id as (%s)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1322       | **The case is not in a state that accepts this request**The payer refused your request because of the state of the case. You receive this code in two situations, and the message tells them apart.                                                                                                                                                                                                                | No active case found for the given case number.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1323       | **The beneficiary's wallet balance is too low**Each beneficiary has a wallet: the amount the scheme will still pay for them. The wallet does not hold enough to pay this claim.                                                                                                                                                                                                                                    | Insufficient wallet balance. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1324       | **The discharge stage is not valid**Every claim says at what stage the patient was discharged, relative to surgery. The stage in your claim is not a value the payer accepts.                                                                                                                                                                                                                                      | Invalid discharge stage received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1325       | **The admission date is not valid**The payer read the admission date in your claim but does not accept it for this case.                                                                                                                                                                                                                                                                                           | Invalid admission date received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1326       | **The discharge date is not valid**The payer read the discharge date in your claim but does not accept it for this case.                                                                                                                                                                                                                                                                                           | Invalid discharge date received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1327       | **The admission date is in the wrong format**The payer could not read the admission date in your claim. The date is not in the format it expects.                                                                                                                                                                                                                                                                  | Invalid admission date format received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1328       | **The discharge date is in the wrong format**The payer could not read the discharge date in your claim. The date is not in the format it expects.                                                                                                                                                                                                                                                                  | Invalid discharge date format received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1329       | **The registration date is not valid**The payer read the registration date in your claim but does not accept it for this case.                                                                                                                                                                                                                                                                                     | Invalid registration date received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1330       | **The registration date is in the wrong format**The payer could not read the registration date in your claim. The date is not in the format it expects.                                                                                                                                                                                                                                                            | Invalid registration date format received for case number %s. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1331       | **The receiver is not registered in NHCX**Every request names the participant that should receive it. The receiver in your request is not a registered NHCX participant.                                                                                                                                                                                                                                           | Receiver not registered in NHCX. Please try again with valid receiver details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1332       | **The Claim Review Committee request is not valid**A rejected claim can be sent for review by the Claim Review Committee (CRC). The payer did not accept your request for that review.                                                                                                                                                                                                                             | Invalid CRC request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1333       | **The claim type is not valid**Every claim says whether the care was in-patient or out-patient. The payer did not accept the claim type in your claim.                                                                                                                                                                                                                                                             | Invalid claim type (in-patient/out-patient) received. Hence the request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1334       | **The payer has no configuration for your hospital**The payer could not find a configuration for your hospital in its system. The fix is on the payer's side.                                                                                                                                                                                                                                                      | Hospital configuration not found. Please contact support team.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1335       | **The implant quantity is not valid**The payer checked the quantity on an implant in your claim and did not accept it.                                                                                                                                                                                                                                                                                             | Invalid implant quantity received as %s for implant %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1336       | **The implant unit price is not valid**The payer checked the unit price on an implant in your claim and did not accept it.                                                                                                                                                                                                                                                                                         | Invalid implant unit price received as INR %s for implant %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1337       | **The implant net amount is not valid**The payer checked the net amount on an implant in your claim and did not accept it.                                                                                                                                                                                                                                                                                         | Invalid implant net amount received as INR %s for implant %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1338       | **The implant attachment is not valid**The payer checked the attachment on an implant in your claim and did not accept it.                                                                                                                                                                                                                                                                                         | Invalid implant attachment received for investigation %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1339       | **The implant status is not valid**The payer checked the status on an implant in your claim and did not accept it.                                                                                                                                                                                                                                                                                                 | Invalid implant status received as %s for investigation %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1340       | **The investigation status is not valid**The payer checked the status on an investigation in your claim and did not accept it.                                                                                                                                                                                                                                                                                     | Invalid investigation status received as %s for investigation %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1341       | **The investigation attachment is not valid**The payer checked the attachment on an investigation in your claim and did not accept it.                                                                                                                                                                                                                                                                             | Invalid investigation attachment received for investigation %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1342       | **A case in progress blocks a new reimbursement request**A reimbursement claim is paid back to the hospital after treatment. The payer is still processing an earlier request on this case, so it refused the new one.                                                                                                                                                                                             | Existing case in progress found for case number %s. Hence new reimbursement request will not be accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1343       | **A reimbursement was already approved for this case**The payer already approved a reimbursement for this case. It will not process a second reimbursement request for the same case.                                                                                                                                                                                                                              | Previous reimbursement approved record found for the new reimbursement request for case number %s. Hence request will not be processed further.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1344       | **The payer has no details for the requested procedures**The payer looked up the procedures in your claim and found no details for them in its system.                                                                                                                                                                                                                                                             | No details found for the requested procedures in the system.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1345       | **The procedure status is not valid**The payer checked the status on a procedure in your claim and did not accept it.                                                                                                                                                                                                                                                                                              | Invalid procedure status received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1346       | **The procedure description is not valid**The payer checked the description on a procedure in your claim and did not accept it.                                                                                                                                                                                                                                                                                    | Invalid procedure description received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1347       | **The procedure type is not valid**The payer checked the type on a procedure in your claim and did not accept it.                                                                                                                                                                                                                                                                                                  | Invalid procedure type received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1348       | **The procedure factor is not valid**The payer checked the factor on a procedure in your claim and did not accept it.                                                                                                                                                                                                                                                                                              | Invalid procedure factor received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1349       | **The procedure quantity is not valid**The payer checked the quantity on a procedure in your claim and did not accept it.                                                                                                                                                                                                                                                                                          | Invalid procedure quantity received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1350       | **The procedure net amount is not valid**The payer checked the net amount on a procedure in your claim and did not accept it.                                                                                                                                                                                                                                                                                      | Invalid procedure net amount received as INR %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1351       | **The procedure speciality code is not valid**The payer checked the speciality code on a procedure in your claim and did not accept it.                                                                                                                                                                                                                                                                            | Invalid speciality code received as %s for procedure %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1352       | **The beneficiary and care plan do not fit this hospital**The payer checked the beneficiary and the care plan together for your hospital. The combination matches no criteria for handling the case there.                                                                                                                                                                                                         | Requested beneficary details and careplan details does not match any criteria for processing the case at this hospital. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1353       | **The care plan id is not valid**The care plan id in your claim is not one the payer accepts.                                                                                                                                                                                                                                                                                                                      | Invalid careplan id received. Please try again with valid careplan id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1354       | **The claim failed a payer rule**The claim broke one of the payer's rules. The message does not say which rule.                                                                                                                                                                                                                                                                                                    | Rule failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1355       | **The payer has no details for the requested implants**The payer looked up the implants in your claim and found no details for them in its system.                                                                                                                                                                                                                                                                 | No details found for the requested implants in the system. Hence request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1356       | **The wallet is short and the patient cannot pay the difference**The beneficiary's wallet does not cover the amount you claimed. Your hospital is not allowed to charge the patient the difference, so the payer refused the claim.                                                                                                                                                                                | Patient liability is not aplicable for the hospital and beneficiary do not have enough wallet balance with deficit amount INR %s for the requested preauthorization for case number %s.                                                                                                                                                                                                                                                                                                                                                                                                                                           | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1357       | **The admission date is after the discharge date**Your claim says the patient was admitted after they were discharged. The payer refused it.                                                                                                                                                                                                                                                                       | Admission date cannot be after the discharge date. Hence request will not be processed. Please correct the data and try again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1358       | **The patient was registered too long after admission**The scheme allows a patient to be registered only within a set number of days after admission. Your claim gives a registration date outside that window.                                                                                                                                                                                                    | Registration of the patient is allowed maximum upto %s days after admission. Hence request will not be processed. Please correct the data and try again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1359       | **The claim has no billable treatment plan**The payer found no treatment item it can bill in your claim for this case.                                                                                                                                                                                                                                                                                             | No billable treatment plan received for case number %s. Please try again with valid treatment plan data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1360       | **An item code is not valid**The payer did not accept the code on one of the items in your claim.                                                                                                                                                                                                                                                                                                                  | Invalid item code received as %s for item sequence %s case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1361       | **An item sequence is not valid**Each item in a claim has a sequence number. The payer did not accept one of yours.                                                                                                                                                                                                                                                                                                | Invalid item sequence received as %s for case number %s. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1362       | **A discharge against medical advice needs the LM100 procedure**Sometimes a patient leaves before or during surgery against medical advice. For PMJAY claims, the claim must then carry the LM100 procedure, and your claim did not.                                                                                                                                                                               | No procedure with code LM100 received with 'Requested' status for case number %s. Please try again with valid data. For PMJAY claims, if case comes under LAMA/DAMA scenario with beneficiary being discharged before surgery or during surgery, procedure with code LM100 is mandatory. Only this procedure code will be accepted for LAMA/DAMA case, and all other previous preauthorization approved items will get disqualified for the claim submission                                                                                                                                                                      | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1363       | **No biometric authentication and no consent questionnaire at discharge**A new claim needs proof that the patient was present at discharge. That proof is biometric authentication, or a response to the Authentication Consent Questionnaire. Your claim had neither.                                                                                                                                             | Response for Authentication Consent Questionnaire is missing for case number %s. This must be sent if the biometric authentication for patient is not available during discharge. For new claim request, either biometric authentication for patient during discharge, or response for Authentication Consent questionnaire must be sent. Please check/update the insurance plan for the policy for the details of the questionnaire.                                                                                                                                                                                             | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1364       | **A consent questionnaire answer is empty**Your claim carries an Authentication Consent Questionnaire response, but one question in it has no answer.                                                                                                                                                                                                                                                              | No value received for link id %s for Authentication Consent Questionnaire for claim request. This must be sent if the biometric authentication for patient is not available during discharge. For new claim request, either biometric authentication for patient during discharge, or response for Authentication Consent questionnaire must be sent. Please check/update the insurance plan for the policy for the details of the questionnaire.                                                                                                                                                                                 | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1365       | **The standard treatment guideline response is missing**Some procedures come with a standard treatment guideline (STG) questionnaire. A procedure in your claim needs one, and the claim did not include the response.                                                                                                                                                                                             | Response for STG Questionnaire id %s is mandatory for procedure code %s. Hence the preauthorization request will not be processed as the questionnaire response is not received for procedure code.                                                                                                                                                                                                                                                                                                                                                                                                                               | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1366       | **The biometric user token is not valid**Biometric authentication gives your system a user token for the patient. The token sent with your claim is not valid.                                                                                                                                                                                                                                                     | Invalid biometric user token received. Please try again with valid biometric details of the beneficiary. For any issues with biometric, please try with Authentication Consent Questionnaire for discharge, details for which has been received in insurance plan.                                                                                                                                                                                                                                                                                                                                                                | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1367       | **No biometric record for a cycle date**A cyclic procedure, such as dialysis, is given in repeated cycles. Each cycle needs its own biometric authentication, and the payer found none for one of your dates.                                                                                                                                                                                                      | No biometric records found for the beneficiary for %s. Please ensure correctness of biometric authentication date for the day for cyclic procedure %s.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1368       | **Cycle information is missing for some cycles**A cyclic procedure is claimed once, after the last cycle. The claim must describe every cycle, and yours describes fewer than it requests.                                                                                                                                                                                                                         | %s units of cycle information received for procedure code %s with item sequence %s. Cycle information should be sent for all the requested/processed cycles.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1369       | **Two biometric authentications on one date for a cyclic procedure**A cyclic procedure allows one cycle per day. Your claim gives two or more biometric authentications on the same date for one procedure.                                                                                                                                                                                                        | Biometric authentication cannot be performed more than once on the same date. Multiple biometric authentication information has been provided for same date for cyclic procedure %s. Hence case will not be processed. Please check and update biometric authentication execution dates and try again.                                                                                                                                                                                                                                                                                                                            | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1370       | **A supporting detail has an invalid start date**One entry in your claim's supporting information has a start date the payer does not accept.                                                                                                                                                                                                                                                                      | Received invalid start date as %s for supporting details with item sequence %s. Please try again with valid start date.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Claim                                                                         | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1401       | **The policy is not allowed for your hospital**You asked a payer, through NHCX, for the insurance plan of a policy. The policy is not applicable to your hospital, so the payer returns no plan.                                                                                                                                                                                                                   | \<policy\_code> policy not allowed for the hospital. Please reach out to technical support team.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Insurance plan                                                                | `/v1/insuranceplan/on_request``/v1/insuranceplan/request`                                                                                                                                                    |
| PAYR-1402       | **The payer has no policy with the code you requested**You asked a payer, through NHCX, for the insurance plan of a policy. The payer found no policy with that code in its system. It stops processing the request.                                                                                                                                                                                               | Requested policy \<policy\_code> found not be associated with any payer for insurance plan request. Hence request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Insurance plan                                                                | `/v1/insuranceplan/on_request``/v1/insuranceplan/request`                                                                                                                                                    |
| PAYR-1403       | **The renewal does not belong to the requested policy**You asked a payer, through NHCX, for the insurance plan of a policy and a renewal of it. The payer found no such renewal under that policy. It stops processing the request.                                                                                                                                                                                | Requested renewal \<renewal\_code> found not be associated with requested policy \<policy\_code> for insurance plan request. Hence request will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Insurance plan                                                                | `/v1/insuranceplan/on_request``/v1/insuranceplan/request`                                                                                                                                                    |
| PAYR-1404       | **No treatment is configured for the policy under any speciality**You asked a payer, through NHCX, for the insurance plan of a policy. The payer has no speciality configured for that policy. With no speciality there is no treatment to list, so it returns no plan.                                                                                                                                            | No treatment provided for policy \<policy\_code> under any speciality. Please reach out to technical support team.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Insurance plan                                                                | `/v1/insuranceplan/on_request``/v1/insuranceplan/request`                                                                                                                                                    |
| PAYR-1405       | **The payer has no enrolled hospital for your HFR id or sender code**You asked a payer, through NHCX, for an insurance plan. The payer looked your hospital up and found no enrolled hospital. It checked your HFR id and your sender code. With no hospital record, it cannot build a plan for you.                                                                                                               | No enrolled hospital found for HFR id \<hfr\_id> or sender id \<sender\_code>. Please reach out to technical support team.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Insurance plan                                                                | `/v1/insuranceplan/on_request``/v1/insuranceplan/request`                                                                                                                                                    |
| PAYR-1406       | **An earlier insurance plan request for the same policy is still running**Your hospital asked a payer, through NHCX, for the insurance plan of a policy. An earlier request from your hospital for the same policy is still in progress. The payer refuses the new one until the earlier one finishes.                                                                                                             | Existing request with correlation id %s is in progress with the payer. Hence this request will not be accepted until the execution for previous request is complete. Please wait for 15 - 60 minutes to allow the execution of previous requests. For further assistance, please reach out to technical support team.                                                                                                                                                                                                                                                                                                             | Insurance plan                                                                | `/v1/insuranceplan/on_request``/v1/insuranceplan/request`                                                                                                                                                    |
| PAYR-1501       | **The surgery date entry carries the wrong kind of value**Your preauthorisation or claim lists the surgery date as a supporting information entry. The PMJAY payer found that entry holding the wrong kind of value. It reads the surgery date only from a timing, meaning a date or a period, or from a string. It refused the request.                                                                           | Value type received as %s for category - ONS and code - PSP for item with sequence %s in supporting info in claim resource. In supporting info list, item with category - ONS and code - PSP combination is used to get the surgery date. So the surgery date should be sent as timing (date or period) or as a string value, adhering to the NRCES standards, with the category - ONS and code - PSP.                                                                                                                                                                                                                            | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1502       | **The admission date entry carries the wrong kind of value**Your preauthorisation or claim lists the admission date as a supporting information entry. The PMJAY payer found that entry holding the wrong kind of value. It reads the admission date only from a timing, meaning a date or a period, or from a string. It refused the request.                                                                     | Value type received as %s for category - ONS and code - ADDD for item with sequence %s in supporting info in claim resource. In supporting info list, item with category - ONS and code - ADDD combination is used to get the admission date. So the admission date should be sent as timing (date or period) or as a string value, adhering to the NRCES standards, with the category - ONS and code - ADDD.                                                                                                                                                                                                                     | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1503       | **The death date entry carries the wrong kind of value**Your claim lists the death date as a supporting information entry. The PMJAY payer found that entry holding the wrong kind of value. It reads the death date only from a timing, meaning a date or a period, or from a string. It refused the request.                                                                                                     | Value type received as %s for category - ONS and code - DTM for item with sequence %s in supporting info in claim resource. In supporting info list, item with category - ONS and code - DTM combination is used to get the death date. So the death date should be sent as timing (date or period) or as a string value, adhering to the NRCES standards, with the category - ONS and code - DTM.                                                                                                                                                                                                                                | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1504       | **The case remarks in your query response are not text**The payer queried your preauthorisation or claim, and your system answered. Your answer carries overall case remarks as a supporting information entry. The PMJAY payer reads those remarks only as a string. Your entry held another kind of value, so it refused the answer.                                                                             | Value type received as %s for category - NMI and code - CQD for item with sequence %s in supporting info in claim resource. In supporting info list, item with category - NMI and code - CQD combination is used to get the overall case remarks for query response. So the case remarks for query response should be sent as a string value, adhering to the NRCES standards, with the category - NMI and code - CQD.                                                                                                                                                                                                            | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1505       | **A questionnaire response is attached under the wrong category or code**Your preauthorisation or claim attaches a questionnaire response through a supporting information entry. The entry points at a QuestionnaireResponse resource in your bundle. The PMJAY payer accepts that link only under two category and code pairs. Yours used another pair, so it refused the request.                               | Category received as %s and code received as %s for item with sequence %s in supporting info in claim resource, where the reference value redirects to Questionnaire Response resource in the FHIR bundle. To include a policy/case level Questionnaire Response, in supporting info list there should be an entry with category - INF and code - ODN , and the value as reference. This reference value should refer to a resource of Questionnaire Response in the FHIR bundle. To include response for any STG questionnaire, in supporting info list there should be an entry with category - STG, and the value as reference | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1506       | **The newborn's gender is not valid**Your preauthorisation or claim is for a newborn under PMJAY. The newborn has no scheme membership of its own yet. The parent is the main patient, and the child is a separate, linked patient.                                                                                                                                                                                | Invalid gender received for new born patient. Please try agian with valid gender data as it is mandatory for PMJAY in new born case. Please refer to the valid gender values at https\://hl7.org/fhir/R4/valueset-administrative-gender.html                                                                                                                                                                                                                                                                                                                                                                                      | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1507       | **The newborn's date of birth is not valid**Your preauthorisation or claim is for a newborn under PMJAY. The newborn has no scheme membership of its own yet. The parent is the main patient, and the child is a separate, linked patient.                                                                                                                                                                         | Invalid date of birth received for new born patient. Please try agian with valid date of birth as it is mandatory for PMJAY in new born case.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1508       | **The newborn link does not lead to a Patient resource**Your preauthorisation or claim is for a newborn under PMJAY. The newborn has no scheme membership of its own yet. The parent is the main patient, and the child is a separate, linked patient.                                                                                                                                                             | Invalid resource received for new born patient for url %s. Please try agian with valid Patient resource for the link reference as linked Patient resource is mandatory for PMJAY in new born case                                                                                                                                                                                                                                                                                                                                                                                                                                 | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1509       | **The newborn's proof of birth attachment is not valid**Your preauthorisation or claim is for a newborn under PMJAY. The newborn has no scheme membership of its own yet. The parent is the main patient, and the child is a separate, linked patient.                                                                                                                                                             | Invalid attachment received for new born patient. Please try agian with valid attachment as attachment is mandatory for PMJAY in new born case                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/preauth/on_submit``/v1/preauth/submit`                                                                                                                           |
| PAYR-1510       | **A parameter code in your request is not valid**The PMJAY payer checked the parameters in your request and found a code it does not accept. The message does not say which parameter. Your system has to find it before it resends.                                                                                                                                                                               | Invalid parameter code received. Please check and try again with a valid parameter code                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Bundle structure                                                              | `/v1/insuranceplan/on_request``/v1/insuranceplan/request``/v1/task/on_submit``/v1/task/submit`                                                                                                               |
| PAYR-1511       | **A parameter value in your request is not valid**The PMJAY payer checked the parameters in your request and found a value it does not accept. The message does not say which parameter. Your system has to find it before it resends.                                                                                                                                                                             | Invalid parameter value received. Please check and try again with a valid parameter value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Bundle structure                                                              | `/v1/insuranceplan/on_request``/v1/insuranceplan/request``/v1/task/on_submit``/v1/task/submit`                                                                                                               |
| PAYR-1512       | **A patient reference does not lead to a Patient resource**A resource in your FHIR bundle refers to the patient. The PMJAY payer followed that reference and did not find a valid Patient resource. It refused the request.                                                                                                                                                                                        | Invalid resource received for patient for url %s. Please try agian with valid Patient resource for the reference                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1513       | **A diagnosis is not sent as a coded concept**Your FHIR bundle lists a diagnosis. The PMJAY payer accepts a diagnosis only as a coded concept: a code, its code system and a display text. Yours arrived in another form, so it refused the request.                                                                                                                                                               | Invalid diagnosis received in DiagnosisComponent. In DiagnosisComponent, diagnosis should be sent as CodeableConcept. Please try agian with valid data                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1514       | **The discharge information entry does not name a discharge stage**Your claim carries discharge information as a supporting information entry. The PMJAY payer reads it as text naming the discharge stage. Your entry held another kind of value, so it refused the claim.                                                                                                                                        | Value type received as %s for category - DIS for item with sequence %s in supporting info in claim resource. In supporting info list, item with category - DIS is used to get the discharge related information. So the discharge information should be sent as string value, with value representing discharge stage (After Surgery / Before Surgery / During Surgery), with the category - DIS and code - DTH/LAMA/DAMA/DTM                                                                                                                                                                                                     | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit`                                                                                                                                                                      |
| PAYR-1515       | **An organisation in your bundle has no name**Your FHIR bundle includes an Organization resource for a hospital or a payer. The PMJAY payer requires every organisation to carry a name. The organisation at the reference in the message had no valid name, so it refused the request.                                                                                                                            | Invalid name received for organization resource with url %s. Name is mandatory for organization resource. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Organization.html                                                                                                                                                                                                                                                                                                                                                                                                                               | Bundle structure                                                              | `/v1/claim/on_submit``/v1/claim/submit``/v1/coverageeligibility/check``/v1/coverageeligibility/on_check``/v1/preauth/on_submit``/v1/preauth/submit`                                                          |
| PAYR-1516       | **The payer cannot match your error response to any message**Your system sent an error response to the PMJAY payer through NHCX. The payer finds the message your error response answers by three identifiers. It found no message with that combination, so it refused your error response.                                                                                                                       | No event found for api-caller-id %s and correlation id %s for sender code %s. Hence error response willnot be accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Bundle structure                                                              | `/v1/communication/on_request``/v1/communication/request``/v1/error`                                                                                                                                         |
| PAYR-1517       | **Your error was sent encrypted instead of as a protocol response**Your system sent the PMJAY payer an error through NHCX. An error travels in the ProtocolResponse structure, with its details in clear headers. Yours arrived in the encrypted structure, typed JWEPayloadResponse. The payer does not read errors in that form.                                                                                 | Invalid error structure received for NHCX error. Protocol response structure is expected, but received JWEPayloadResponse.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Bundle structure                                                              | `/v1/communication/on_request``/v1/communication/request``/v1/error`                                                                                                                                         |
| PAYR-1518       | **Your Task resource carries no input parameters**Your request carries a Task resource. A Task tells the payer what you want, and names the policy or case through its inputs. Yours had no inputs, so the PMJAY payer refused it.                                                                                                                                                                                 | No input parameters received for task resource. Input parameters are expected for task resource, but not received. Please try again with valid data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Bundle structure                                                              | `/v1/communication/on_request``/v1/insuranceplan/on_request``/v1/insuranceplan/request``/v1/task/on_submit``/v1/task/submit`                                                                                 |
| PAYR-1519       | **A Task input parameter has no type**Your request carries a Task resource with inputs. Each input must say what kind of input it is, through a type code. At least one of yours had no type, so the PMJAY payer refused the request.                                                                                                                                                                              | No type found for task input parameters. Hence request will not be processed further. Please refer to https\://www\.nrces.in/ndhm/fhir/r4/StructureDefinition-Task.html                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Bundle structure                                                              | `/v1/communication/on_request``/v1/insuranceplan/on_request``/v1/insuranceplan/request``/v1/task/on_submit``/v1/task/submit`                                                                                 |
| PAYR-1520       | **The communication reference does not lead to a Communication resource**The payer asked your hospital for more information with a communication request, through NHCX. Your system answered with a Task that points at a Communication resource. The PMJAY payer followed that reference and did not find a valid Communication, so it refused the answer.                                                        | Invalid resource received for communication for url %s. Please try agian with valid Communication resource for the reference.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Bundle structure                                                              | `/v1/communication/on_request``/v1/communication/request`                                                                                                                                                    |


---

# Troubleshooting by layer and code

A symptom-first chapter. Everything else in this documentation is organised by what you are building; this one is organised by what has gone wrong, because that is the only thing you know at the moment you need it.

## Isolate the layer first

A message crosses five layers on its way to a decision, and each one refuses in a different way. Work out which layer stopped it before you look anything up, because the same symptom means different things at different layers.

| Layer           | What refuses                       | How you hear                                    | Code family                           |
| --------------- | ---------------------------------- | ----------------------------------------------- | ------------------------------------- |
| 1. Transport    | Your HTTP call to the gateway      | Synchronously, in the response to your own call | HTTP `4xx`, `5xx`                     |
| 2. Gateway      | The exchange, reading the envelope | Synchronously, or later on `/v1/error`          | `NHCX-1xxx`                           |
| 3. Encryption   | The recipient, opening the letter  | On your callback, as a protocol response        | `PAYR-1001`, `PAYR-1002`, `PAYR-1097` |
| 4. Bundle       | The recipient, validating FHIR     | On your callback, inside the sealed response    | `PAYR-10xx`                           |
| 5. Adjudication | The payer's rules                  | On your callback, inside the sealed response    | `PAYR-11xx` to `PAYR-14xx`            |

The layers are strictly ordered. Reaching a layer means every layer before it passed, which is why a scheme-rule refusal is good news about your bundle.

## The symptom table

| What you see                                            | Layer | Most likely cause                                                                | What to do                                                                                                            |
| ------------------------------------------------------- | ----- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `401` on the sessions call                              | 1     | Wrong client ID or secret                                                        | Check the credentials against onboarding                                                                              |
| `401` naming a header on the sessions call              | 1     | `REQUEST-ID` reused or absent, `TIMESTAMP` stale or malformed, `X-CM-ID` missing | Generate a fresh UUID per call; take the time from the system clock                                                   |
| `401 Sender is not authorized to execute the operation` | 1     | Token expired                                                                    | Fetch a new token and retry once. Never retry with the same token                                                     |
| `401` immediately after a fresh token                   | 1     | `Bearer `prefix missing, or the token sent on the wrong header name              | Send `bearer_auth: Bearer <token>`. NHCX reads `bearer_auth`, not `Authorization`                                     |
| `401` on policy link or de-link only                    | 1     | The client ID calling is not the one that created the participant                | Run the linking job under the credentials that created the record                                                     |
| `400` on a use-case call                                | 2     | Envelope failed validation                                                       | Check every `x-hcx-` field against Envelope Fields                                                                    |
| `NHCX-1005` invalid request header                      | 2     | A header missing, malformed or of the wrong type                                 | As above                                                                                                              |
| `NHCX-1006` duplicate request                           | 2     | A correlation ID reused, usually on a retry after a failure                      | Mint a fresh correlation ID. A failed correlation is retired                                                          |
| `NHCX-1011` invalid status                              | 2     | The status word does not match the leg of the message                            | Requests send `request.initiated`; responses send `response.partial`, `complete` or `error`                           |
| `NHCX-1018` invalid ABHA number                         | 2     | ABHA sent in the wrong shape                                                     | The gateway wants `XX-XXXX-XXXX-XXXX` on the `x-hcx-ben-abha-id` header, though the bundle carries it without hyphens |
| `NHCX-1010` no data with given correlation id           | 2     | You answered a request whose correlation the exchange had already retired        | Acknowledge every submission immediately, then send the decision on the same thread                                   |
| `NHCX-1002` or `NHCX-1003` not registered               | 2     | Sender or recipient is not active on the exchange                                | Check the participant record's status. Only `Active` can send or receive                                              |
| Nothing at all arrives on your callback                 | 2     | Address, firewall, routing, or no receipt sent                                   | See the callback checklist below                                                                                      |
| `PAYR-1001` decryption failed                           | 3     | You encrypted with a certificate that is not the one on the recipient's record   | Re-fetch the recipient's certificate and resend. Clear your cache                                                     |
| `PAYR-1002` encryption failed                           | 3     | The payer cannot encrypt for you: your registered certificate is stale or absent | Update your `encryption_cert` on your participant record                                                              |
| `PAYR-1097` no payload                                  | 3     | The ciphertext part of the JWE is empty                                          | Check you are serialising all five parts, compact                                                                     |
| `PAYR-1005` time limit exceeded                         | 3     | `x-hcx-timestamp` is more than 24 hours behind the current time                  | Send the current time. This is the only numeric tolerance the sources state                                           |
| `PAYR-1004` or `PAYR-1008` malformed or invalid bundle  | 4     | The bundle does not parse or fails profile validation                            | Run it through the NRCeS validator before anything else                                                               |
| `PAYR-1009` to `PAYR-1016` no identifier or type found  | 4     | A resource is missing its `identifier`, or an identifier is missing its `type`   | Every resource that names a party needs both                                                                          |
| `PAYR-1019` invalid sequence in supporting info         | 4     | A `supportingInfo` entry has no `sequence`                                       | Number the whole list once it is assembled, from 1, with no gaps                                                      |
| `PAYR-1027` invalid item id                             | 4     | `Claim.item` has no FHIR element `id`. Nothing to do with the package code       | Give each item `Item/n`, each procedure `Procedure/n`, each supporting-info entry `SupportingInformation/n`           |
| `PAYR-1028`, `PAYR-1029`                                | 4     | The same fault on the item sequence and the bundle id                            | As above                                                                                                              |
| `PAYR-1083` no HPR details                              | 4     | The `Practitioner` carries no identifier typed `HPIN`                            | Send the HPR id as `HPIN` as well as `HPID`                                                                           |
| `PAYR-1093`, `PAYR-1094` composition faults             | 4     | An embedded clinical document does not follow the NRCeS profile                  | Check the `Encounter` structure definition                                                                            |
| `PAYR-1095` invalid discharge information               | 4     | A claim with no discharge status                                                 | Send category `DIS` with a code among `DTH`, `DTM`, `LAMA`, `DAMA`                                                    |
| `PAYR-1096` invalid death date                          | 4     | Discharge type is death and no death date was sent                               | Send category `ONS`, code `DTM`                                                                                       |
| `PAYR-1008` invalid content type                        | 4     | A document outside PDF, JPG, JPEG, PNG and FHIR JSON                             | Convert it. `text/plain` is refused                                                                                   |
| `PAYR-1114`, `PAYR-1202` invalid speciality code        | 5     | `item.category` is not the master's category code for that package               | Read the specialty off the plan, not off your own list                                                                |
| `PAYR-1238` active preauthorisation exists              | 5     | The scheme allows one live preauthorisation per beneficiary per hospital         | Cancel the existing one, or raise its claim. The reference number names it                                            |
| `PAYR-1245` one conservative procedure                  | 5     | A second package typed `Conservative` on one case                                | An enhancement must add a `Medical` package or an allowed add-on                                                      |
| `PAYR-1256`, `PAYR-1363` consent questionnaire missing  | 5     | No biometric token and no authentication-consent response                        | Answer the plan's questionnaire, found by title in the master                                                         |
| `PAYR-1301` claim already raised                        | 5     | One case, one claim                                                              | Nothing to resubmit. Use a Task                                                                                       |
| `PAYR-1302` no approved preauthorisation                | 5     | The claim went out under a number of its own                                     | Send the claim under the pre-authorisation's number                                                                   |
| `PAYR-1321`                                             | 5     | A claim query answered under the wrong workflow id                               | Answer on 161, not 151, 19 or 16                                                                                      |
| `PAYR-1322` active instance found                       | 5     | Another request is already open on that case                                     | The scheme takes one at a time. Wait                                                                                  |
| `PAYR-1401` policy not allowed for the hospital         | 5     | The plan was asked for under a policy the hospital is not empanelled under       | Ask under the beneficiary's own policy from the eligibility answer                                                    |
| `PAYR-1406` existing request in progress                | 5     | A second plan request before the first was answered                              | Wait 15 to 60 minutes. Past 60, raise it with support                                                                 |
| `ERR-PYR-CLM-007` no prior record for case number       | 5     | As `PAYR-1302`                                                                   | As above                                                                                                              |

## When nothing arrives on your callback

The commonest report, and it is almost always one of six things. The portal lists the first five; the sixth is the one people miss.

1. **The address.** A domain name, not an IP address and not a port number.
2. **The location.** The server must be hosted in India.
3. **The firewall.** Allow the exchange's outbound addresses: `3.109.99.210`, `13.126.152.0`, `13.200.129.223`.
4. **The rules.** Check nothing else is dropping the inbound connection.
5. **Application routing.** The request reaches the server and is dispatched to the wrong handler by a mismatched route, a load balancer rule or a version prefix.
6. **The receipt.** You answered, but not with `202` and the receipt body within 30 seconds. A slow `200` is read as a failed delivery. After five attempts the exchange gives up and retires the correlation ID, and tells you on `/v1/error`, which you must also be hosting.

Test the whole path rather than the parts. Call your own registered public address from outside your network and confirm that what answers is the service you think it is.

## When a case has gone quiet

In order, and stop at the first that explains it.

1. **Did you get a receipt?** No receipt means the exchange never took the message. It is not a payer problem.
2. **Did anything arrive on `/v1/error`?** That is where an undeliverable request is reported. A system without the endpoint never learns.
3. **Ask the exchange.** The status exchange reports where a message got to. Status and Search in Getting Started has the shape.
4. **Under PMJAY, ask the payer service.** A case sits at `request.initiated` until someone acts on it in the scheme's own system. The role lookup says where it is. PMJAY Adjudication APIs has it.
5. **Only then treat it as slow.** The scheme decides on its own schedule. An enhancement approved in a minute on one run was still queued five minutes on in another, with the same bundle.

## Things that look like faults and are not

- **A queued acknowledgement.** Both live payers answer twice on one correlation: an interim response saying the request is with an adjudicator, then the decision. Treat the first as an acknowledgement, not as the answer.
- **`outcome: complete` on a rejection.** `complete` means the payer finished processing. The adjudication reason is what separates approval from rejection.
- **A reduced amount without `partial`.** The reference payer approves at a lower figure and still sends `complete` with no note. Reconcile amounts yourself.
- **Zero benefit on a query.** It means no benefit has been determined yet, not that the claim was refused.
- **A base rate of zero in the plan.** Some packages are priced entirely by the bed category chosen.
- **`PAYR-1238` on a preauthorisation.** It arrives only after the bundle has passed validation, so it is the first evidence the bundle is right.
- **A `SUBSETTED` meta tag.** Every payer-generated bundle carries it. It marks a projection of the payer's record, not an error.

## Service names in logs and URLs

A name in a log line, a Swagger address or a stack trace does not always match the exchange you think you are calling. Reprocess is served by `taskhcxservice`, notifications by `subscriptionhcxservice`, payment by `servicehcxpayment`. Read the name off this table before you look for a fault in the wrong service.

| Service name in a log or URL    | Exchange it serves                                            |
| ------------------------------- | ------------------------------------------------------------- |
| `coverageeligibilityhcxservice` | Coverage eligibility                                          |
| `insuranceplanhcxservice`       | Insurance plan                                                |
| `preauthhcxservice`             | Preauthorisation                                              |
| `claimhcxservice`               | Claim                                                         |
| `communicationhcxservice`       | Communication, including a request for additional attachments |
| `servicehcxpayment`             | Payment notice                                                |
| `statushcxservice`              | Status check                                                  |
| `taskhcxservice`                | Task: reprocess and cancel                                    |
| `searchhcxservice`              | Search                                                        |
| `participanthcxservice`         | Participant service: registry, certificates and policies      |
| `subscriptionhcxservice`        | Notifications                                                 |
| `abdmproxy`                     | Face authentication for PMJAY biometrics                      |
| `nhcxpayerservice`              | PMJAY payer service: the role lookup and acting on a case     |
| `dummyhcxpayer`                 | The sandbox dummy payer's test hooks                          |

Environments and Addresses has the full address of each.

## Before you raise it with support

Have these to hand. Every one of them is something the exchange or the payer will ask for, and a report without them cannot be traced.

- The correlation ID, and the API call ID of the specific message.
- The timestamp, and which environment.
- Your participant code and the recipient's.
- The workflow code and the status word you sent.
- The raw sealed message as sent, and the raw response as received. Store both before you interpret either; this is the only reason that instruction is repeated throughout this documentation.
- The error code and the payer's message verbatim, not your rendering of it.

Integration questions go to `hcx.integration@nha.gov.in`. FHIR profile and validation questions go to `nrc-help@cdac.in`.


---

# Registries

Nothing on NHCX can happen until two questions are answered: who am I sending this to, and which policy is it about. Neither is a claim exchange. Both are preconditions, and a system that skips them fails later with errors that look like claim problems but are not.

- [Participant registry](/docs/nhcx/v1/registries/participant): how a participant joins the network, registers its key and callback address, authenticates, and finds other participants.
- [Policy registry](/docs/nhcx/v1/registries/policy): how a beneficiary's policy is found, which participant code to address, and how a payer links a policy to ABHA.

## Why this comes first

A patient is not cashless simply because they hold insurance. Two things have to be true: the admission record must carry the scheme, payer, identifier and policy number, and the system must have resolved a valid processor code, product code and member ID. A patient can look correctly admitted as insured on screen while every NHCX call still fails, because the second condition was never met.

The order is fixed. Discover the payer, then discover the policy. Take the processor code, member ID and product from what came back, fetch the plan and its benefits, check eligibility, and only then submit a preauthorisation.

JWE, Status and Errors opens the envelope every one of those calls travels in. NHCX Use Cases lists the calls themselves.


---

# Participant registry

Every message on NHCX is addressed from one participant to another. This page covers how a participant joins the network, how it makes itself reachable, and how participants find and address each other. The [Policy registry](/docs/nhcx/v1/registries/policy) covers the other precondition: which policy a claim is about.

## Becoming a participant

Every entity on the exchange is a registered participant with three identifiers that do different jobs.

- **Participant ID.** The address on the exchange, written as `1518@hcx`. The part after the `@` names the exchange. This is what goes on the envelope as sender and recipient.
- **Client ID and secret.** The login used to get an access token. They are the client ID and secret issued when you register on the ABDM sandbox. There is no separate NHCX login.
- **Registry ID.** Proof of who you are, issued by a registry the exchange trusts. For a hospital it is the Health Facility Registry (HFR) ID. For an insurer or TPA it is the IRDAI registry ID, sent without leading zeros, so 0123 becomes 123. For a patient app it is the app's own client ID.

When a participant is created, its role and its registry are given as numbered codes.

| Role                  | Code  |   | Registry       | Code  |
| --------------------- | ----- | - | -------------- | ----- |
| Provider              | 10001 |   | HFR            | 10001 |
| Payer                 | 10002 |   | NIN            | 10002 |
| TPA                   | 10003 |   | ROHINI         | 10003 |
| Regulator             | 10004 |   | Payer registry | 10004 |
| Research              | 10005 |   |                |       |
| Insurance marketplace | 10006 |   |                |       |
| Scheme sponsor        | 10007 |   |                |       |
| Another exchange      | 10008 |   |                |       |
| Patient app           | 10009 |   |                |       |

A hospital group with several facilities holds one participant ID per HFR ID, all created with the same credentials.

Each role comes with a fixed list of what it may send and receive, and the exchange checks every call against it. Access Control and Roles in the Reference section has that list.

**The registry ID must match at both layers.** The HFR ID sent inside a FHIR bundle has to be the same as the registry ID recorded against that sender on the exchange. A mismatch is rejected by the gateway, and it is a common failure for integrators who take the registry entry and the bundle content from different places.

## Registering

Registration is a short sequence of calls to the participant service. Each is confirmed by a one-time passcode sent to the mobile number the registry holds, so nobody can register a hospital they do not control.

1. **Create.** Send the registry type, registry ID, role, mobile number and email. The mobile number must be the one on the HFR record, or for a payer the one NHA holds. The exchange returns a participant ID and a transaction number, and sends a passcode to that phone. The participant now exists but is pending.
2. **Confirm.** Send the transaction number and passcode. The participant becomes active.
3. **Configure.** Send the participant's public certificate and the address the exchange should call back on, which the portal calls the bridge URL. A second passcode arrives.
4. **Confirm again.** The address and certificate go live. The exchange can now reach you.

A participant record also carries a status the exchange maintains: created but not yet verified, active, inactive, or blocked. Only an active participant can send or receive.

Passcodes and transaction numbers last 24 hours. Lose one and you repeat that step. A certificate can be replaced later without a passcode, through a dedicated certificate-update call. The sandbox offers a simpler create, update and delete without the passcode steps.

## Your own key

How Claims Move on NHCX said the letter is sealed with the receiver's key. That means every participant needs a key of its own and has to publish the public half.

Make a 2048-bit RSA key, sign your own X.509 certificate with it (the portal gives the three openssl commands), encode the certificate in base64, and register it in the configure step above. The private half stays with you; it is what opens every letter addressed to you. NHA recommends replacing the key once a year and expects a participant to report a key that may have leaked.

## Where the exchange calls you

The callback address registered during configuration is where every answer arrives, so it comes with rules.

- A domain name, not an IP address or a port number.
- HTTPS, with TLS 1.2 or newer.
- Hosted in India.
- Reachable from the exchange's outbound addresses, which must be allowed through your firewall: `3.109.99.210`, `13.126.152.0` and `13.200.129.223`.
- Answering within 30 seconds with an acceptance receipt, otherwise the exchange assumes delivery failed and tries again.

The portal lists one further cause that is not about the address at all: application routing. The request reaches the server but is dispatched to the wrong handler by a mismatched route, a load balancer rule or an endpoint version.

## Finding a participant

A Provider does not hard-code the payers it deals with. It asks the registry.

The participant list call takes a role, so a Provider asks for everyone registered as a Payer, and can narrow by date range and by whether the entity is government or private. The calling system then filters by name if the user is looking for a specific insurer.

What matters downstream is the chosen payer's participant code, because it is one half of the address on every subsequent envelope. The other half, which is not always the same code, comes from the policy lookup below.

## Authenticating

Every call carries a bearer token. The token comes from the ABDM gateway's sessions endpoint, not from NHCX itself, using your ABDM sandbox client ID and secret.

A token lasts 1200 seconds (20 minutes). Refresh it automatically before the 20 minutes run out, and treat a `401` as "get a new token and retry" rather than as a failure.

Sandbox addresses:

- Sessions: `https://dev.abdm.gov.in/api/hiecm/gateway/v3/sessions`
- Participant service: `https://apisbx.abdm.gov.in/pmjay/sbxhcx/participanthcxservice`
- Use cases: `https://apisbx.abdm.gov.in/hcx/v1`

The production participant service is at `https://apisprod.nha.gov.in/pmjay/hcx/participanthcxservice`. The production use-case address is `https://apisprod.nha.gov.in/hcx`.

## Certificates and encryption

Before sending anything to a participant, the sender needs that participant's public key.

The certificate fetch takes a participant ID and returns its key material, as a PEM-encoded X.509 certificate or, for shorter keys, an SPKI public key. Try the X.509 import first and fall back to SPKI.

**Cache certificates.** Fetching a payer's key before every request is a round trip that buys nothing, since keys change rarely. A 24-hour cache is the practical default.

## From sandbox to production

Joining the network is a certification, not a form. The path for a hospital runs:

1. **Register the facility** in the Health Facility Registry.
2. **Apply on the ABDM sandbox**, choosing Providers and Payers with Milestone 1 as the intent. This yields the client ID and secret.
3. **Complete Milestone 1**, which is ABHA creation and verification, then functional testing, the WASA security audit and the HTC demo. NHCX requires M1 to be in place first.
4. **Register on the NHCX sandbox** with the same credentials and create a participant for each facility.
5. **Integrate and test** against the sandbox, using the dummy payer described in NHCX Use Cases.
6. **Get certified.** Email sample FHIR bundles to `hcx.integration@nha.gov.in` for NRCeS validation, give an internal demo to the NHA team, then the HTC demo before NRCeS, IRDAI, TCS and NHA.
7. **Go to production.** NHA confirms, adds the provider role to the production client ID, and the participant is created there through the registration steps above.
8. **Pilot, train, go live.** NHA recommends a small pilot and staff training before switching fully.

Payers follow the same shape but enrol through the NHA or IRDAI portal, which registers them after scrutiny and asks the ABDM gateway team to issue credentials with the payer or TPA role.

A participant can also leave. Voluntarily, when a business shuts, merges or moves exchange. Involuntarily, when a regulator suspends it, when it repeatedly breaches service levels, or when it misuses the network. Involuntary removal comes with warnings and a right of appeal through the grievance process.


---

# Policy registry

Before any claim-side call, the beneficiary has to be matched to a policy, and the policy tells you which participant to address. This page covers the lookup and the link that makes it work. The [Participant registry](/docs/nhcx/v1/registries/participant) covers how to find the payer in the first place.

## Finding a policy

Once the payer is known, the beneficiary has to be matched to a policy with that payer. The lookup accepts three identifiers, and a system that does not know which will work should try them in order of reliability.

- **ABHA number.** The strongest, and the one to try first.
- **Member ID.** The policy or member number captured at admission.
- **Mobile number.** The weakest, since a number may be shared or out of date.

What comes back, for each policy, is the insurer, who processes claims for it, the member ID, and the product. Two of those are participant codes and they are not always the same.

**Send claims to the processor, not the insurer.** An insurer may handle its own claims, in which case its `payerid` and `processingid` are the same code. Or it may use a TPA, in which case `processingid` is the TPA's participant code and that is where every request must go. The policy lookup tells you which. Put `processingid` on the envelope as the recipient. Pointing at `payerid` instead is the portal's seventh most common mistake, and the request goes nowhere useful.

A lookup that succeeds is worth keeping. The policy set for a patient does not change between one department and the next, so cache against the patient and provide a way to force a refresh. If the lookup returns no processor code, stop; no claim-side call can be addressed.

## Linking a policy to ABHA

The reason an ABHA number works as a policy identifier at all is that someone linked it earlier.

Linking is a Payer-side action, performed when the policy is created. The insurer links the beneficiary's ABHA number, mobile and member ID to the policy's products, naming itself as the payer and its TPA, or itself, as the processor. Only the party named as payer or processor can de-link it later; the exchange checks the caller's credentials against the link. If an insurer changes TPA, every affected policy is de-linked and re-linked with the new processor.

The effect is felt at the point of care. A beneficiary who walks in with only an ABHA number can be resolved to a policy without a card or a member ID, which is the whole point of linking it in the first place.


---

# Adjudicating claims

The claim is where money is decided. The payer receives the finalised bill and the full document set, and checks them against the approved preauthorisation and the discharge evidence. It then issues a decision that, once final, cannot be reopened except through the appeal Task.

## What the adjudicator sees

The claim queue, opened against the approved preauthorisation, side by side: what was approved, what is now claimed, and the difference highlighted. The discharge type and stage, the dates, the discharge summary as a record, the bill, the post-operative evidence. The four evaluation dimensions the handbook names, as a checklist: within cover and limits, clinically appropriate, documents complete and consistent, amounts within package rates and financial rules.

Actions: approve, approve at a reduced amount with a note per item, query, reject with a denial code. And two interim states that are not decisions: in process, and forwarded to another entity.

## What the system hosts

```text
/v1/claim/submit      answer on /v1/claim/on_submit
```

Workflow 15 is the claim; 151 is an answer to your query. Under PMJAY there is no separate discharge submission; the claim asserts the discharge and carries its details. On the general network a provisional discharge submission (14) may arrive first, answered with 261, 262 or 263.

Acknowledge receipt with 25 and `response.partial`. A claim may receive several interim answers before the final one; each is `response.partial` on the same correlation ID, and only the final carries `response.complete`.

## Validate before queueing

- An approved preauthorisation exists for the case number; no claim already raised against it.
- Every item, implant and investigation on the claim was on the preauthorisation, was not rejected there, and is not claimed at a higher quantity.
- Registration, admission, surgery and discharge dates present and well-formed; a discharge stage present, from the allowed set.
- Amount within the preauthorisation's approved amount and the wallet.
- Under PMJAY, the discharge biometric token. For a LAMA or DAMA before surgery, only `LM100`, with a quantity equal to the stay. For a death, a death date. For a newborn, the parent's card and the child's documents.

## What goes in the answer

The same `ClaimResponse` as for preauthorisation with `use = claim`.

| Decision          | `outcome`  | `adjudication.reason` | Workflow               |
| ----------------- | ---------- | --------------------- | ---------------------- |
| Approved          | `complete` | `approved`            | 26                     |
| Approved, reduced | `partial`  | `approved`            | 26, with `processNote` |
| Queried           | `partial`  | `queried`             | 27                     |
| In process        | `partial`  |                       | 28                     |
| Forwarded         | `partial`  |                       | 29                     |
| Rejected          | `complete` | `cancelled`           | 291                    |

A rejection closes the claim number. Nothing further arrives against it except a Task. Use the scheme's denial codes so the provider's appeal screen can show a reason. Less than 24 hours of hospitalisation, package reserved for public hospitals, incomplete documents after multiple queries, bed category misrepresented. Then outside scope of cover, fraudulent, package does not match diagnosis, hospital not empanelled for the specialty, and the rest of the `ClaimError` list.

Each final approval carries the totals accounts will pay from: submitted, eligible, benefit, tax deducted, incentive, patient-liable. Those figures reappear on the payment notice; keep them consistent.

## The arithmetic on every final approval

Accounts pays from these figures and the provider reconciles against them, so they have to agree with the payment notice that follows.

| Category    | What it is                                                           |
| ----------- | -------------------------------------------------------------------- |
| `submitted` | What the hospital asked for, per item and in total                   |
| `eligible`  | What is within cover before deductions                               |
| `copay`     | The patient's share. Zero under PMJAY, which is fully cashless       |
| `benefit`   | What you will pay. This is the number the provider shows as approved |

Then at claim level, the tax deducted, any incentive, and the patient-liable amount where the scheme has them. The payment notice's `TDS` and `Payment` lines should sum to the approved amount here; a provider that finds they do not will raise a query or a shortfall.

## Appeals

Rejections and shortfalls come back as a `Task` on `/v1/task/submit`, workflow 36, code `reprocess`, reason `claimrejected` or `partialpayment`, with a document attached and, for a shortfall, the amount. Route both to the Claim Review Committee.

Acknowledge with 37, then answer on `/v1/task/on_submit` with a `Task` whose `status` is `completed` and whose output references a `ClaimResponse` inside the same bundle. The `ClaimResponse` is read by the provider's ordinary parser, so build it with the same outcome and reason fields: 252 approved, 253 rejected, 254 queried.

Under PMJAY the payer enforces four rules. One appeal per claim. A shortfall claim only after payment 33 has been sent and acknowledged. The amount never above the difference. The Committee's decision final, with no shortfall claim allowed after it. A cancellation Task, code `cancel`, is answered with PC02 and refused once payment has begun.

## Search

Regulators, and the scheme sponsor, can search claims across payers with a `Task` of code `search` on `/v1/search/submit`. Answer on `/v1/search/on_submit` with the matching `ClaimResponse`s. A provider may only search its own cases; a regulator may search any.


---

# Adjudicating preauthorisation

The preauthorisation queue is where a payer's clinical judgement meets the exchange. The system's job is to get a case in front of the right doctor with everything they need, and to turn their decision into a `ClaimResponse`. It also enforces the sequencing rules that keep one case from becoming several.

## What the adjudicator sees

A queue, ordered by turnaround-time remaining, because a scheme with TAT-based auto-approval pays for every case the doctor does not reach in time. Opening a case shows:

- The beneficiary, the policy, the wallet balance now and after this request.
- Diagnosis, packages with rates and add-ons, care team, dates.
- Every document, structured ones rendered as records rather than opened as files, and the STG questionnaire answers beside the package they belong to.
- The plan's flags for each package: auto-approvable, enhanceable, reserved, standalone.
- History on the case: earlier preauthorisations, enhancements, queries and answers.

Four actions: approve, approve at a reduced amount with a note, query, reject with a reason from the scheme's denial list. Item by item, then a total.

## What the system hosts

```text
/v1/preauth/submit      answer on /v1/preauth/on_submit
```

The workflow code says which kind of request it is: 12 new, 121 resubmission, 13 enhancement, 19 an answer to your query. Acknowledge receipt at once with code 20 and `response.partial`, so the provider knows it is in the queue.

## Validate before queueing

The reference payer's preauthorisation errors are the checklist. Run them on arrival and refuse with a protocol response rather than wasting a doctor's time:

- Amount above zero and within the wallet balance.
- Specialty code and display, package code and display, exactly as the plan has them; quantity at least one; net above zero.
- Registration and admission dates present and well-formed.
- Sequencing. No case already in progress for this number. An enhancement or resubmission only where an approved record exists. A new preauthorisation refused where an approved one exists. No preauthorisation once a claim is raised, and nothing at all on a cancelled case.
- One active preauthorisation per beneficiary across all hospitals; tell the provider which hospital holds it.
- Every STG questionnaire the plan demands answered; a biometric token or the consent questionnaire present.
- Under PMJAY, `LM100` never on a preauthorisation; investigations mandatory for private hospitals; newborn cases with date of birth, gender and documents, and within six years.

## Deciding automatically

Two rules let a case skip the queue, and both come from the plan:

- **Auto-approve** when this is the first preauthorisation for the case and every package carries `ApprovalNotRequired`.
- **TAT approve** when the policy allows it and no doctor has acted within the configured window.

Log which rule fired. The provider sees an approval; the audit sees why.

## What goes in the answer

A collection bundle with the `ClaimResponse`, the `Patient`, the `Coverage` and the `Organization`s. `use = preauthorization`. The provider reads `outcome` and the adjudication reason together, so set both deliberately.

| Decision                       | `outcome`  | `adjudication.reason` | Workflow  | Also set                                                                     |
| ------------------------------ | ---------- | --------------------- | --------- | ---------------------------------------------------------------------------- |
| Approved                       | `complete` | `approved`            | 21        | `preAuthRef`, every item's four amounts equal                                |
| Approved, reduced              | `partial`  | `approved`            | 21        | `processNote` explaining the reduction, linked from the item by `noteNumber` |
| Queried                        | `partial`  | `queried`             | 24        | Query text; totals zero; `eligpercent` zero                                  |
| Rejected                       | `complete` | `cancelled`           | 23        | `disposition` and the denial code                                            |
| Enhancement approved or denied | as above   |                       | 22 or 231 |                                                                              |

Per item, four adjudication lines: `submitted`, `eligible`, `copay` (zero under PMJAY), `benefit`. Totals at the claim level with the same categories, plus tax, incentive and patient-liable amounts where the scheme has them.

The `preAuthRef` you issue is what the provider will quote on the claim. Make it unique and durable.

## What the provider reads from your answer

Three fields on the response decide what the hospital's screen shows, and getting them wrong misstates the decision rather than failing loudly.

| What you set                                            | What the provider does with it                                                                                                                                 |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outcome` plus the adjudication reason                  | Reads them as a pair. `complete` alone means approved or rejected, so the reason is the difference                                                             |
| The `benefit` adjudication, per item and at claim level | Shows it as the approved amount. The `submitted` category alongside is what was asked for, and showing that as the decision is the classic provider-side error |
| `processNote`, linked from the item by `noteNumber`     | Shows it verbatim as the reduction reason                                                                                                                      |
| `preAuthRef`                                            | Quotes it on the claim. Make it unique and durable                                                                                                             |

Note what the published PMJAY responses do **not** carry: no `ClaimResponse.request` pointing back at the `Claim`, no `ClaimResponse.type`, and no `preAuthRef` at all. The case number in `identifier[0].value` is what actually travels forward. If your system issues a real `preAuthRef`, you are ahead of the samples, and you should say so to integrators rather than assume they read it.

## Writing a query

Under PMJAY the query travels in `item.adjudication.reason.coding.display` as a pipe-delimited audit trail, `USER~datetime~type~comment~actor`, where `actor` is whoever wrote the entry: `PPD-Trust` on a preauthorisation, `CPD-Trust` on a claim, or the hospital's name, with multiple entries separated by `|`. The provider shows the comment. Keep it specific: name the document or the clarification, and the package it concerns. A vague query costs a full round trip and a day of TAT.

Under PMJAY the provider answers on the same endpoint with code 19. On the general network a payer may instead raise a Communication with reason `additionalinfo`; the provider answers on the communication endpoint. Do not use both for the same question.

## Approval letters

The value set includes form codes for letters: `preauthapproval`, `preauthdenial`, and later `claimapproval`, `claimdenial`, `dischargeapproval`. Where the scheme issues them, attach the letter as a `DocumentReference` referenced from the response.


---

# Eligibility response

The eligibility check is the one exchange a payer should answer without a human. It is asked at every registration and before every submission, and a provider that waits on it is a front desk that waits.

## What the system hosts

```text
/v1/coverageeligibility/check      answer on /v1/coverageeligibility/on_check
```

Read `CoverageEligibilityRequest.purpose` and answer accordingly. Four purposes, four answers.

| Purpose             | The question                                                                 | What to return                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `validation`        | Is this coverage in force, and what is left?                                 | `inforce`, and one benefit entry per wallet with allowed (balance) and used money                                           |
| `discovery`         | What coverages does this beneficiary have with you?                          | Every active coverage, so the provider can pick a policy code                                                               |
| `benefits`          | For these packages, what is covered?                                         | Per item: excluded or not, benefit type, allowed money, including stratification amounts                                    |
| `auth-requirements` | For these packages, is preauthorisation required and what must come with it? | Per item: `authorizationRequired`, and `authorizationSupporting` listing every mandatory document and questionnaire by code |

Auth-requirements is the one that saves the most rework downstream. The `MAND` codes it returns are what the provider's document checklist is built from; the more precise they are, the fewer queries the adjudicator raises later.

## What to validate first

The reference payer refuses, with a named error, before it looks at coverage:

- An invalid purpose, or an invalid identifier.
- Multiple beneficiary records for one identifier.
- No hospital configuration, or a hospital not authorised for the policy.
- Items or stratifications it has no master data for.
- A quantity below one, an unknown payer ID, or a duplicate reference ID. Each becomes a protocol response with `response.error`, and each is cheaper to catch here than at preauthorisation.

Under PMJAY, also validate the biometric user token in the header. A request with neither a valid token nor the matching authentication-consent questionnaire response is not evidence of presence, and the payer's own error codes distinguish the two cases.

## What the four answers actually carry

The published samples show how much the four purposes differ. Only one of them carries money.

| Purpose             | `insurance[].item[]`             | Carries money                       | Carries `authorizationRequired`     |
| ------------------- | -------------------------------- | ----------------------------------- | ----------------------------------- |
| `validation`        | One item per wallet              | Yes: `allowedMoney` and `usedMoney` | Yes                                 |
| `discovery`         | Every active coverage            | No                                  | No                                  |
| `benefits`          | One item per package asked about | Per package                         | Per package                         |
| `auth-requirements` | One item per package asked about | Per package                         | Yes, with `authorizationSupporting` |

The two money fields are a subtraction the provider has to make. A published sample carries 463,730 allowed against 36,270 used on a 500,000 family wallet, and the plan's `generalCost` reconciles with it exactly. Send both figures; do not send only the balance.

**One warning about the auth-requirements answer.** It is specified to return the mandatory documents, and the one published sample does not. That sample carries no benefit detail and no supporting-information requirements, and is indistinguishable from the plain benefits answer. A provider building its checklist from your answer alone will show an empty checklist. Populate `authorizationSupporting` properly, with the `MAND` codes and a display, and you save the adjudicator a query per case.

## What goes in the answer

A collection bundle: the `CoverageEligibilityResponse`, the `Patient` as the payer knows them, the `Coverage`, and the `Organization`s.

| Element                                    | Set it to                                                                                            |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `status`                                   | `active`                                                                                             |
| `purpose`                                  | Echo the request's                                                                                   |
| `outcome`                                  | `complete`                                                                                           |
| `disposition`                              | One sentence a desk can read: "Policy is currently in-force"                                         |
| `request`                                  | Reference back to the request                                                                        |
| `insurance.coverage`                       | The coverage found                                                                                   |
| `insurance.inforce`                        | `true` or `false`                                                                                    |
| `insurance.item[]`                         | Per wallet for validation; per package for benefits and auth-requirements                            |
| `item.benefit[].allowedMoney`, `usedMoney` | Balance and consumption                                                                              |
| `item.authorizationRequired`               | Whether preauthorisation is needed                                                                   |
| `item.authorizationSupporting[]`           | The mandatory document and questionnaire codes, with a display and a text saying whether pre or post |

Business refusals, "not a covered member", "policy expired", "coverage insufficient", go inside the sealed response as a `PAYR-10xx` reason, not in the envelope; the exchange never sees them. Protocol refusals go in the envelope.

## The forward instruction

The coverage eligibility specification gives it one sentence: a payer might respond with a forward instruction asking NHCX to submit the same request to another payer. No fields or flow are published for it, so there is nothing to build against. Until they are, a request for a coverage you do not hold is a business refusal inside the sealed response, as described above. Governance and Audit lists the question to ask at onboarding.

## What to log

Every eligibility answer is a promise the provider will rely on when it registers the patient. Keep the request, the answer, the wallet figures at that moment and the plan version they came from, so that when a claim arrives against them, the adjudicator sees what was said.


---

# Payer overview

A payer system is the insurer's, TPA's or scheme's side of the exchange. Where a provider mostly calls and waits, a payer mostly hosts and answers: it receives eligibility checks, plan requests, preauthorisations and claims, decides, and sends the decision back. It initiates only three things of its own: policy links, payment notices, and communications.

This section assumes the base framework from Getting Started: token, participant record with the payer role, own key, and a callback endpoint that opens messages. A payer's "callback" endpoints are the `check`, `request` and `submit` sides that providers call.

## What the payer's staff see

```mermaid
flowchart LR
  E[Eligibility auto-answer] --> P[Preauth queue]
  P --> Q[Query composer]
  Q --> P
  P --> C[Claim queue]
  C --> Q
  C --> M[Payment run]
  C -. appeal .-> A[Appeals]
  A --> M
```

Under PMJAY the decisions are taken by named roles: the Preauthorisation Processing Doctor at admission, the Claim Processing Doctor at settlement, the Claim Review Committee on appeal, and accounts on payment. A payer UI is a set of work queues for those roles.

| Screen             | Who         | What they do                                                                     | Exchange behind it            |
| ------------------ | ----------- | -------------------------------------------------------------------------------- | ----------------------------- |
| Policy admin       | Operations  | Link and de-link beneficiaries to products; name the processor                   | Link and de-link ABHA         |
| Plan configuration | Scheme team | Maintain specialties, packages, rates, add-ons, flags, documents, questionnaires | Insurance plan response       |
| Eligibility        | System      | Answer automatically from policy and wallet data                                 | Coverage eligibility response |
| Preauth queue      | PPD         | Open a case, see items and documents, approve, reduce, query or reject           | Preauthorisation response     |
| Claim queue        | CPD         | Same, against the approved preauthorisation and the discharge evidence           | Claim response                |
| Query composer     | PPD, CPD    | Write the query the provider will see                                            | Queried response              |
| Appeals            | CRC         | Reprocess and shortfall requests                                                 | Task response                 |
| Payment run        | Accounts    | Initiate, process and settle; record UTR and deductions                          | Payment notice                |
| Communications     | Any         | TAT alerts, grievances, wallet and policy changes                                | Communication request         |

## What the system hosts and calls

From the Overview's catalogue, a payer hosts the C-series callbacks and calls the shared A-series plus three of its own.

Hosts, as the receiving half of each exchange:

```text
/v1/coverageeligibility/check      answer on /v1/coverageeligibility/on_check/v1/insuranceplan/request          answer on /v1/insuranceplan/on_request/v1/preauth/submit                 answer on /v1/preauth/on_submit/v1/claim/submit                   answer on /v1/claim/on_submit/v1/task/submit                    answer on /v1/task/on_submit/v1/search/submit                  answer on /v1/search/on_submit/v1/communication/on_request       the provider's acknowledgement/v1/paymentnotice/on_request       the provider's acknowledgement/v1/on_status, /v1/error
```

Calls of its own:

```text
/participant/link/abha/policy, /participant/delink/abha/policy/v1/paymentnotice/request/v1/communication/request
```

## The rules for every answer

The payer exit checklist states four validations on every response a payer sends, and the sandbox certification checks them:

1. The payload validates against the NRCeS profiles.
2. `api_call_id` and `correlation_id` on the response are different values.
3. `correlation_id` on the response is the request's `correlation_id`, echoed. The checklist words it as the request's `api_call_id`, which is the same value, because a request sets its `correlation_id` to its own `api_call_id`.
4. `recipient_code` on the response equals the `sender_code` of the request.

The correlation rule is the same everywhere. On a request you initiate, such as a payment notice or a communication, set `correlation_id` to that message's own `api_call_id`. On a response, echo the request's `correlation_id` and give the response a fresh `api_call_id`. On a status enquiry, set `correlation_id` to the `api_call_id` of the message you are asking about. Envelope Fields has the full rule.

And the status word: `response.complete` for a final answer, `response.partial` for an interim one or a query, `response.error` with a protocol response when the request could not be opened or failed validation. The exit checklist names the type field on a good answer `JWEPayloadResponse`; the sandbox collection uses `JWEPayload`. Accept both when reading, and confirm which to send.

## Build it in this order

A payer's work is mostly hosting, and the hosting has a dependency order of its own.

| Order | Build                                                          | Because                                                                                             |
| ----- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| 1     | The base framework, and the four validations on every response | Nothing you send is accepted without them, and certification checks them on every use case          |
| 2     | Policy linking                                                 | Until a policy is linked, no provider can find the beneficiary and nothing else is reachable        |
| 3     | The eligibility answer, by rule                                | Asked at every registration. A provider waiting on it is a front desk waiting                       |
| 4     | The insurance plan response                                    | It drives every provider screen, so its correctness decides how many malformed requests you receive |
| 5     | The preauthorisation queue and its response                    | The first exchange needing a human                                                                  |
| 6     | The claim queue and its response                               | Reuses the same `ClaimResponse` shape                                                               |
| 7     | Payment notices, all three                                     | The provider cannot close a case without 33                                                         |
| 8     | Communication, and the Task answer for appeals                 | Needed for sandbox exit                                                                             |

Getting 4 right early pays for itself. Most of what a provider sends wrong, it sends wrong because your plan did not tell it otherwise.

## What the system must keep

- The policy master: beneficiaries, products, wallets, family limits, and which participant processes each policy.
- The plan master, versioned, because a rate change with no version bump looks like tampering from the provider's side.
- Every case as a state machine driven by what the payer itself sent: received, queried, approved, rejected, claimed, in process, settled, appealed.
- Every raw message received and sent, with its correlation ID, because arbitration is settled on the record.
- Adjudication detail per item: submitted, eligible, co-pay, benefit, and the reason, because that is what a `ClaimResponse` is made of.

The chapters that follow take each queue in turn, the payer UI Guide turns them into the screens each desk works from, and Payer Checklist is the checklist you have to demonstrate to leave the sandbox.


---

# Payer checklist

What a payer has to demonstrate to leave the sandbox, the validations the certification checks on every response, the test cases to run, and how to test without a real provider.

## The sandbox exit list

NHA's payer exit process names fifteen use cases.

1. Link ABHA with policy, `/participant/link/abha/policy`.
2. Get policy, `/participant/get/policies`.
3. De-link ABHA from policy, `/participant/delink/abha/policy`.
4. Get participant list, `/fetch/participants/list`.
5. Get public key, `/fetch/certs`.
6. Get auth token, `/get/session`.
7. Respond to coverage eligibility, received on `/v1/coverageeligibility/check`, answered on `/v1/coverageeligibility/on_check`.
8. Respond to insurance plan request, received on `/v1/insuranceplan/request`, answered on `/v1/insuranceplan/on_request`.
9. Respond to preauthorisation, received on `/v1/preauth/submit`, answered on `/v1/preauth/on_submit`.
10. Raise a communication request, `/v1/communication/request`, acknowledged on `/v1/communication/on_request`.
11. Respond to claim, received on `/v1/claim/submit`, answered on `/v1/claim/on_submit`.
12. Respond to search, received on `/v1/search/submit`, answered on `/v1/search/on_submit`.
13. Send payment notice, `/v1/paymentnotice/request`, acknowledged on `/v1/paymentnotice/on_request`.
14. Respond to a task, received on `/v1/task/submit`, answered on `/v1/task/on_submit`.
15. Get status, `/v1/status`, answered on `/v1/on_status`.

Plus `/v1/error` and, where the payer is a scheme, the biometric token validation.

## The four validations on every response

The checklist repeats them for every answering use case, so the certification will check them on every one:

1. Payload validates against the NRCeS profiles.
2. `api_call_id` and `correlation_id` are different values.
3. `correlation_id` matches the request being answered.
4. `recipient_code` equals the request's `sender_code`.

And each answer is prepared one of two ways: a sealed bundle when the request was processed, or a protocol response when it could not be opened or failed validation.

## Testing without a provider

There is no dummy provider on the sandbox. The practical route is to build the provider's calling half from Getting Started and the provider section, point it at your own participant code, and drive your queues from it. The sample bundles on the portal give you real PMJAY-shaped requests to feed in: every eligibility purpose, a preauthorisation and its query answer, an enhancement, a cancellation, a claim and its query answer.

## Test cases

One id per case, by family: `ELG` coverage eligibility, `PLN` insurance plan, `PRE` preauthorisation, `CLM` claim, `TSK` tasks, `PAY` payment, `COM` communication, `ENV` envelope and queue. Cases marked PMJAY apply to the scheme only. The workflow codes named are the ones the payer's answer must carry.

### Coverage eligibility

#### T-ELG-01 Validate the policy

A request by ABHA with purpose `validation`. Answer on `/v1/coverageeligibility/on_check` with `inforce: true` and the wallet balance, after checking the ABHA linkage and that the member is active.

#### T-ELG-02 Auth-requirements

Purpose `auth-requirements` for a package. Answer with `authorizationRequired: true` and the mandatory documents and STG codes, after checking wallet adequacy and the specialty constraints.

#### T-ELG-03 Every purpose and the refusals

`discovery` and `benefits` answered; an exhausted family wallet and a hospital not authorised for the policy refused inside the sealed response, not in the envelope.

### Insurance plan

#### T-PLN-01 Publish the plan

Answer on `/v1/insuranceplan/on_request` with the collection bundle: empanelled packages, claim-condition flags, STG questionnaires and the rate master, carrying a version.

### Preauthorisation

#### T-PRE-01 Acknowledge, then approve

Acknowledge on `20` as `response.partial`, then approve on `21` as `response.complete` with `preAuthRef`, after STG validation and biometric token verification.

#### T-PRE-02 Query and its answer

Raise the query on `24`, on the case thread under PMJAY or over communication otherwise. Take the answer on `19`, clear the hold, then decide on `21`.

#### T-PRE-03 Reject with a denial code

Decide on `23` with the denial reason inside the `ClaimResponse`.

#### T-PRE-04 Reduce with a note

Approve on `21` for less than asked, with the adjudication note that says why.

#### T-PRE-05 Auto-approval and TAT approval (PMJAY)

A first preauthorisation whose packages all carry `ApprovalNotRequired` is approved without a desk action. A package flagged `ScheduledTATApproval` is approved by the system when the window lapses, with the disposition "Auto approved by system".

#### T-PRE-06 Enhancement approved and denied

Approve on `22`; deny on `231`; query on `241`.

#### T-PRE-07 Resubmission and cancellation

A resubmission on `121` treated as the new base request. A cancel Task on `PC01` answered `PC02` before payment, and refused after payment has been initiated.

### Claim

#### T-CLM-01 Acknowledge, then approve

Acknowledge on `25`, then approve on `26`, after verifying the discharge biometric token, matching the preauthorisation, and calculating incentives and tax.

#### T-CLM-02 Query and its answer

Raise the query on `27`; take the answer on `151`, or `161` under PMJAY; then decide on `26` or `291`.

#### T-CLM-03 Reduce, in process, forward, reject

`26` for less than claimed with the deduction reason per item; `28` in process; `29` forwarded; `291` rejected.

#### T-CLM-04 Every discharge type (PMJAY)

`DTH`, `DTM`, `LAMA` and `DAMA` each priced as the scheme rules say, with `LM100` per day for LAMA or DAMA before surgery.

#### T-CLM-05 Unusual cases (PMJAY)

An unspecified procedure; a cyclic procedure with per-visit biometrics; a newborn on the parent's card; twins; implants within their maximums.

### Tasks

#### T-TSK-01 Reprocess

A reprocess Task on `36` acknowledged on `37` with the Task `accepted`, then re-adjudicated on `252` or `253`, the `ClaimResponse` in the Task's output.

#### T-TSK-02 Shortfall

A `partialpayment` Task accepted after payment notice `33` has been acknowledged, and refused before it.

#### T-TSK-03 The Committee's answer

The Claim Review Committee's decision returned inside a Task, not as a bare `ClaimResponse`.

### Payment

#### T-PAY-01 Three notices

`30`, `31` and `33` in turn, with the UTR and the TDS line on `33`, and the provider's acknowledgement recorded. Net plus deductions equals the approved amount.

#### T-PAY-02 Return payment

`RP1` intimation, `RP2` acknowledged, `RP3` failed.

### Communication

#### T-COM-01 Each reason

`additionalinfo`, `tatquery`, `grievance`, `walletupdate`, `policychange` and `claimArbitration`, each acknowledged by the provider within thirty seconds; `tatquery` sent when a preauthorisation or claim has passed the payer's own turnaround threshold.

### Envelope and queue

#### T-ENV-01 Duplicate request on one correlation id

The second delivery is recognised and not processed twice.

#### T-ENV-02 A request while another is in progress

Refused, with `PAYR-1322` under PMJAY, until the first is decided.

#### T-ENV-03 A malformed bundle

Answered with a protocol response, not a sealed bundle.

#### T-ENV-04 Queue ordered by time remaining

Preauthorisation and claim queues indexed by `received_at` plus the turnaround window, so the case with the least time left comes first and the breach alert fires before the window lapses. No window values are published. The plan's `ScheduledTATApproval` flag says only that the system approves the case after "a specified time period (varies with policy)", and the FAQ's answer on reprocess is "No fixed TAT as of now". Agree the windows at onboarding; Governance and Audit lists the question.

## Where payers go wrong

- Answering with `outcome = complete` and no adjudication reason, so the provider cannot tell approval from rejection.
- Reusing the request's `api_call_id` as the response's.
- Sending business refusals in the envelope, where the exchange logs them, instead of inside the sealed response.
- Rates changed in the plan master without a version bump, so every provider's next claim looks tampered.
- Sending `33` before the bank has confirmed, which opens the shortfall window early.
- TAT auto-approval firing because the queue was not ordered by time remaining.

## Exchanges this documentation does not cover

The workflow families that no NHA document describes beyond their codes are listed once, under the same heading in Provider Checklist. A payer may receive one too; log it and escalate rather than ignore it.

## Before going live

- Enrolment through the NHA or IRDAI portal with the payer or TPA role, the IRDAI registry id without leading zeros, and the production certificate and callback address.
- Every policy linked with the correct processor.
- The plan master versioned and published for every empanelled hospital.
- FHIR bundles validated by NRCeS; internal demo; HTC demo.


---

# Payment notice and communication

The two exchanges a payer starts. Payment tells the provider money has moved; communication tells the provider something has changed or is wanted.

## Payment notices

### What accounts do

A payment run screen, built from approved claims: select the claims, initiate the transfer, and record the bank's confirmation and UTR as it comes back. Each stage becomes a notice. Deductions, TDS and any scheme adjustments are entered per claim, and the net is what the bank receives.

### What the system calls

```text
POST /v1/paymentnotice/request      workflows 30, 31, 33receive /v1/paymentnotice/on_request   the provider's acknowledgement, workflow 17
```

Three notices per claim as the money moves: 30 initiated, 31 processed by the bank, 33 settled with the UTR. Each is a separate message with its own correlation ID. Send 33 only when the bank has confirmed; under PMJAY it is the gate that lets the provider raise a shortfall claim.

### What goes in the bundle

A collection bundle: a `Task` with code `deliver` and an input referencing the notice, a `PaymentNotice`, a `PaymentReconciliation`, and the two `Organization`s.

#### Task

`status = requested`, `intent = order`, `code = deliver`. `requester` is the payer, `owner` the provider, and `input[0].valueReference` points at the PaymentNotice.

#### PaymentNotice

The claim number as an identifier of type `CLN`, `recipient` the provider, `amount` the net, `paymentStatus` `paid` or `cleared`, and `payment` referencing the reconciliation.

#### PaymentReconciliation

The same claim number, `paymentDate`, `paymentAmount` as the net, a `paymentIdentifier` of type `UTR` carrying the bank reference, and `detail[]` with one line per money type: `TDS`, `Payment`, and any of `approvedamount`, `claimedamount`, `servicetax`, `advance`, `recovered`, `penality`.

The provider will check that net plus deductions equals the approved amount. Make it so.

### The acknowledgement

Arrives as a `Task` with `status = completed`, code `status`, and an output whose value is `paymentack`, with the claim number as a second output. It confirms receipt, not agreement. Record it against the claim and consider the payment lifecycle closed once the acknowledgement of 33 is in.

A return payment, where money has to come back, has its own codes: RP1 intimation, RP2 acknowledged, RP3 failed.

## Communication requests

### What the user does

A composer, usually opened from a case: choose the reason, write the message, set a priority, send. Some are generated by the system rather than a person. A TAT alert when a provider has not answered a query within the window, a wallet update when a beneficiary's balance changes, a policy change when the plan master is versioned.

### What the system calls

```text
POST /v1/communication/requestreceive /v1/communication/on_request   the provider's acknowledgement
```

Reasons, on `Task.reasonCode`: `tatquery`, `grievance`, `walletupdate`, `policychange`, `additionalinfo`, `claimArbitration`. The last is sent automatically when an appeal Task is received, so the provider knows it is in the Committee's queue.

On the general network, `additionalinfo` is how a payer asks for documents outside a formal query. Under PMJAY, document queries go through the queried `ClaimResponse` instead, and this channel is for the other five.

### What goes in the bundle

A collection bundle of three parts.

#### Task

Code `poll`, `intent = proposal`, `reasonCode` set, and an input of type `include` referencing the Communication.

#### Communication

The case number as identifier, `status = completed`, a `category` (reminder, notification, instruction, questionnaire), a `priority` (routine, urgent, asap, stat), a `topic` (progress-update for anything about a live case), and the payload.

#### The two Organizations

Both organisations, each typed by `Organization.type` (`pay` and `prov`). Entry order carries no meaning: read each party's role from its type, never from its position in the bundle.

The acknowledgement comes back as the same shape with the same correlation ID; you know it is the answer because it arrives from the provider's sender code on that correlation ID with `Task.status = completed`, not because of where the `Organization` entries sit. It means received, not resolved; track resolution in the case, not in the exchange.

## What a provider does with each notice

Sending all three matters more than it looks, because the provider's case state and its shortfall window both hang off them.

| Workflow | What you have done                                      | What the provider does                                                                  |
| -------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| 30       | Initiated the transfer                                  | Shows the case as payment started. Does not close it                                    |
| 31       | The bank has processed it                               | Updates the same panel. Still does not close it                                         |
| 33       | The bank has confirmed settlement, and you send the UTR | Marks the case settled, reconciles the UTR against the bank statement, and acknowledges |

Send 33 only when the bank has actually confirmed. Under PMJAY the acknowledgement of 33 is the gate that opens the provider's shortfall window, so sending it early opens that window against a payment that has not landed.

## Notifying the beneficiary

Where a beneficiary's app has subscribed, the exchange itself pushes a human-readable message on each event: "Preauthorisation approved for Rs. 50,000, valid until…". The payer does nothing extra; its normal responses feed it. The payer's own notifications carry workflow N01.


---

# Policies and plans

Before a payer can answer a single claim question, two things have to be true on the network: the beneficiary has to be findable, and the policy has to be readable as data. The first is linking. The second is the insurance plan.

## Linking beneficiaries

### What the user does

A policy-admin screen. When a policy is written or renewed, the operator records the holder's ABHA number, mobile and member ID against the products on the policy, and names who will process claims for it. In most payers this should be automatic from the policy system, with the screen kept for corrections.

The processor is the decision that matters. An insurer that adjudicates its own claims names itself. One that uses a TPA names the TPA's participant code. Get it wrong and every provider will send the case to the wrong place.

### What the system calls

```text
POST /participant/link/abha/policyPOST /participant/delink/abha/policy
```

Bodies and rules are in Getting Started. Two operational points. Only the participants named as payer or processor on the link can change it, and the exchange checks the caller's token against them. So the linking job must run under the same credentials that created the participant. And a change of TPA is a batch: de-link every affected policy with the old processor, link again with the new; there is no edit.

## Publishing the plan

### What the scheme team does

A plan-configuration screen that maintains, per policy and per empanelled hospital:

- The specialties, and the packages under each with their rate.
- The add-ons allowed, meaning implants, bed-category stratification, high-end medicines and investigations, with their maximums.
- The flags that govern each package.
- The mandatory documents at policy and package level, and the questionnaires. Every change bumps a version.

The flags are the scheme's rules made machine-readable, and the provider's screen is built from them. The set the handbook lists is government-reserved, auto-approval, enhancement allowed, scheduled TAT approval, quantity allowed and day care. Then implant applicable and maximum implants, stratification allowed and maximum, standalone, parent procedure, unspecified, and cyclic with maximum cycles. Then LAMA/DAMA procedure and its stages, procedure type (surgical, medical, conservative), length of stay, and GST.

### What the system hosts

```text
/v1/insuranceplan/request      answer on /v1/insuranceplan/on_request
```

The request is a `Task` with code `poll` and inputs `policyNumber` and `providerId`. The answer is scoped to that provider: only the specialties and packages its empanelment allows. That scoping is a validation as much as a filter. The payer's own error codes reject a policy not allowed for the hospital, a renewal code that does not match, a policy with no specialty configured, and an HFR ID it has no enrolment for.

Answer with a collection bundle: one `InsurancePlan`, the `Organization`s, and one `Questionnaire` per requirement. The reference sample carries 2,215 questionnaires and is 21 MB; that is what a real PMJAY plan looks like. Build the bundle from the plan master, never by hand.

### The two shapes

The Insurance Plan guide gives two ways to structure benefits, and a payer picks one per plan.

**Package-based**, the PMJAY shape: `plan → specificCost → category → benefit → cost → qualifiers`. Specialty is the category, package is the benefit, the rate is the cost, and add-ons are qualifiers on the cost. Claim conditions, exclusions and document requirements hang off the plan as extensions.

**Coverage-based**, the private-insurer shape: `coverage → benefit → limit`. Coverage types such as in-patient, benefits such as ICU charges and room rent, and a limit per benefit with its own conditions and required documents.

Element tables for both are in the FHIR Reference.

### Keeping it honest

- Refresh is the provider's job, but a `policychange` communication from the payer is what tells providers to do it early. Send one whenever a rate or package changes.
- Concurrency: a second plan request while the first is still being answered is refused by the reference payer with a wait-and-retry error. Design the request handler to be idempotent per correlation ID.


---

# Payer UI guide

A payer system is operated from queues. Cases arrive, sit until a person or a rule acts on them, and leave with a decision. This chapter describes those queues and the screens around them, who works each one, what they see, what they decide, and how the decision becomes a message. It follows the same order as the rest of the section.

Two rules run through every screen.

**A decision is not made until it is sent.** The adjudicator's action on screen produces a response that goes to the exchange. The case state changes when the receipt comes back, not when the button is clicked. The screen shows the difference.

**The payer never types what the provider sent.** Amounts submitted, items, documents, dates and biometric evidence are shown as received and are not editable. What the payer adds is the decision, the eligible and approved amounts, the reason, and the note.

## Who works which queue

```mermaid
flowchart LR
  IN[Inbound messages] --> E[Eligibility: answered by rule]
  IN --> PQ[Preauth queue]
  IN --> CQ[Claim queue]
  IN --> AQ[Appeals queue]
  PQ --> PPD[Preauthorisation doctor]
  CQ --> CPD[Claim doctor]
  AQ --> CRC[Review committee]
  CPD --> PAY[Payment run: accounts]
  CRC --> PAY
  OPS[Operations] --> POL[Policy admin]
  OPS --> PLAN[Plan configuration]
  ANY[Any desk] --> COM[Communications]
```

| Screen              | Role                       | Input                                                                   | Output message            |
| ------------------- | -------------------------- | ----------------------------------------------------------------------- | ------------------------- |
| Policy admin        | Operations                 | Holder identifiers, products, processor                                 | Link, de-link             |
| Plan configuration  | Scheme team                | Specialties, packages, rates, flags, documents, questionnaires, version | Insurance plan response   |
| Eligibility monitor | System, watched by support | None                                                                    | Eligibility response      |
| Preauth queue       | Preauthorisation doctor    | Decision per item, note, query text                                     | Preauthorisation response |
| Claim queue         | Claim doctor               | Decision per item, note, query text                                     | Claim response            |
| Appeals             | Review committee           | Decision                                                                | Task response             |
| Payment run         | Accounts                   | Claims to pay, deductions, bank confirmation                            | Payment notices           |
| Communications      | Any desk                   | Reason, message, priority                                               | Communication request     |
| Case audit          | Anyone                     | None                                                                    | None                      |

## Policy admin

**Screen.** A search by member, ABHA or mobile, showing the holder's linked products and who processes each. Link and de-link actions, and a bulk tool for moving every policy from one processor to another.

**What the UI enforces.** The processor field is a pick from the payer's own participants, never typed. A de-link names only products already on the link. A change of processor is a batch with a preview of how many policies it will touch. Because only the two participants on a link may change it, the screen must run under the credentials that created the participant, and should say so when a change is refused.

**Data flow.** Policy system writes a policy; a job links it on the exchange; the screen shows the exchange's record, not the policy system's, so a link that failed is visible.

## Plan configuration

```mermaid
sequenceDiagram
  participant T as Scheme team
  participant S as Plan screen
  participant M as Plan master
  participant B as Backend
  participant X as NHCX
  participant H as Hospital
  T->>S: change a rate, add a flag
  S->>M: save as pending
  T->>S: publish
  S->>M: new version
  B->>X: communication, reason policychange
  X->>H: hospitals refresh their plan
  H->>X: plan request
  X->>B: request for this hospital
  B->>M: build plan for this hospital's empanelment
  B->>X: sealed plan response, current version
```

**Screen.** A tree: policy, specialty, package. Per package: the rate, the add-ons allowed with their maximums, the flags, the documents required at preauthorisation and at claim, and the questionnaires attached. A version stamp on the plan with a publish action that bumps it. A per-hospital view showing what an empanelled hospital will receive.

**What the UI enforces.** A rate change without publishing is shown as pending, because an unpublished rate is exactly what makes a provider's next claim look tampered with. Every flag is a control, not a text field. The per-hospital preview is what the plan response will actually contain, generated from the same master.

## Eligibility

No screen for the decision; it is answered by rule from the policy master and the wallet. What operations needs is a monitor: volume by hospital, refusals by reason, and the requests that failed validation with the payer's own error code. That is how a hospital sending a malformed request gets told which field. The monitor should also show the requests answered with "not a covered member" by hospital, because a spike there is a linking problem on the payer's side, not the hospital's.

## The preauthorisation queue

```mermaid
stateDiagram-v2
  [*] --> Received: request validated
  Received --> AutoApproved: rule fires
  Received --> InQueue: needs a doctor
  InQueue --> Deciding: opened
  Deciding --> Approved: approve
  Deciding --> Reduced: approve at lower amount
  Deciding --> Queried: query sent
  Deciding --> Rejected: reject with reason
  Queried --> Answered: provider replies
  Answered --> InQueue
  InQueue --> TATApproved: window lapsed
```

**Screen.** A queue ordered by turnaround time remaining, with cases that a rule will auto-approve marked so the doctor can skip them. Opening a case shows, in the payer's order: beneficiary and wallet before and after, diagnosis, and packages with rate, add-ons and the plan's flags. Then care team and dates, documents rendered as records with questionnaires beside the package they belong to, and the case history.

**The decision panel.** Per item: approve, approve at a lower amount with a note, query, reject with a reason picked from the scheme's preauthorisation denial list. Then a claim-level decision that the system derives from the items and the doctor confirms.

**What the UI enforces.** A reduction needs a note. A rejection needs a reason code. A query needs text and names the item. The eligible and approved amounts are computed from the items and shown, not typed. Under PMJAY the biometric or consent evidence is shown as a badge on the case before anything else.

The doctor sees InQueue cases ordered by how long until TATApproved fires. Get that ordering wrong and the window lapses on cases nobody has looked at.

## Writing a query

**Screen.** A composer opened from an item or from the whole case. Under PMJAY the text becomes the pipe-delimited audit trail the provider will see, so the composer shows the comment field prominently and fills user, time and type itself. A picker of the documents the plan lists, so the doctor asks for a named document rather than "more documents".

**What the UI enforces.** A query cannot be sent empty. On the general network the query goes out as a communication with reason additional information; under PMJAY as a queried response on the case. The composer knows which and the doctor does not have to.

## The claim queue

**Screen.** The claim opened side by side with the approved preauthorisation, differences highlighted: items added, quantities changed, amounts above approval. Discharge type and stage, dates, discharge summary as a record, bill, post-operative evidence. The four checks the handbook names shown as a checklist the doctor ticks: within cover and limits, clinically appropriate, documents complete and consistent, within package rates.

**The decision panel.** As for preauthorisation, with two interim actions that are not decisions: mark in process, forward to another entity. And the claim denial list rather than the preauthorisation one.

**What the UI enforces.** Nothing above the approved amount is approvable without a reduction note. A rejection shows the doctor that it closes the case permanently and that the provider's only route is appeal. Under PMJAY a LAMA or DAMA claim before surgery is shown with the stay line only and the approved packages struck through.

## Appeals

**Screen.** A committee queue of reprocess and shortfall requests, each opened against the original claim, its decision, its payment, and the document the provider attached. Decision: uphold, revise with amounts, reject. A note that the decision is final and closes the case to further appeal.

**What the UI enforces.** A shortfall request that arrived before the settlement notice was acknowledged is shown as premature and is not adjudicated. A second appeal on a case already decided is shown as refused. The decision goes out as a Task carrying a claim response, and the screen shows it as sent only on receipt.

## The payment run

```mermaid
sequenceDiagram
  participant A as Accounts
  participant S as Payment screen
  participant B as Backend
  participant X as NHCX
  participant H as Hospital
  A->>S: select approved claims, enter deductions
  S->>S: net + deductions = approved?
  A->>S: initiate
  B->>X: payment notice, initiated
  X->>H: notice
  H->>X: acknowledgement
  X->>B: acknowledged
  A->>S: bank confirms, enter UTR
  B->>X: payment notice, settled, with UTR
  X->>H: notice
  H->>X: acknowledgement
  B-->>S: claim closed
```

**Screen.** Approved claims not yet paid, selectable into a run. Per claim: approved amount, deductions itemised (tax deducted at source and any scheme adjustment), net. Actions: initiate, then record the bank's confirmation and UTR. Each action becomes a notice to the provider; the screen shows the three notices per claim and whether the provider acknowledged each.

**What the UI enforces.** Net plus deductions equals the approved amount, or the run does not proceed. The settlement notice is sent only when the bank confirmation is entered, because under PMJAY that notice opens the provider's shortfall window. A failed transfer is recorded as a rejected notice, not left silent.

## Communications

**Screen.** A composer with a reason picker: information request, turnaround alert, grievance, wallet change, policy change, arbitration acknowledgement. Message, priority, and the case it concerns. Most of these should be generated by the system rather than a person. A turnaround alert when a query has gone unanswered past the window, a wallet change when a balance moves, a policy change on every plan publish, an arbitration acknowledgement when an appeal arrives.

**What the UI enforces.** A message about a case carries the case number. Priority is a pick, and only a fraud or safety message may be marked as the highest. The acknowledgement from the provider is shown against each message; it means received, and the screen says so.

## The case audit trail

**Screen.** Every case, every message in and out, in order, with the correlation ID, the workflow code, the status word, the raw message and its decrypted content, and who acted on the payer's side. Read only. Exportable.

This is the screen arbitration is settled on, and every other screen is a view over the same record. Build it early.

## Errors the adjudicator should see

A request refused by validation never reaches the queue. It should still reach a support view with the payer's own error code and the hospital that sent it, so that a hospital repeatedly sending a wrong package code can be told. The queues themselves show only cases that passed validation; the doctor's time is for decisions, not for malformed messages.


---

# Biometric authentication

PMJAY requires proof that the beneficiary was physically present. A hospital proves it by authenticating them against their ABHA, biometrically, at registration, during treatment and at discharge. What comes back is a user token, and that token rides on the eligibility check, the preauthorisation and the claim. A request without it, and without the consent form that stands in for it, is refused by name.

These are not NHCX APIs. They belong to ABDM and were built for the PMJAY payer, so nothing in Getting Started applies to them: different hosts, a different authorisation header, no JWE, no callbacks. PMJAY Provider covers when to authenticate and what the scheme does with the result. This chapter is the calls.

## What you have to build

```mermaid
flowchart TD
  A[Patient at the desk] --> B{Method}
  B -- fingerprint or iris --> C["auth/init, then auth/verify<br/>one host"]
  B -- face --> D["faceauth/init, QR, capture/pid,<br/>v2/auth/verify, a different host"]
  B -- none possible --> E["Aadhaar exemption consent<br/>plus the plan's questionnaire"]
  C --> F[User token, 30 minutes]
  D --> F
  F --> G[Token on the header of eligibility, preauth, claim]
```

All three methods. Fingerprint, iris and face are each mandatory to implement, because any one of them may be the only one that works for a given patient, and a case authenticated by fingerprint at admission can be authenticated by face at discharge. The methods do not have to match across a case.

## Two hosts, and this is the first thing to get right

| Method                           | Base                                                                |
| -------------------------------- | ------------------------------------------------------------------- |
| Fingerprint, iris, token refresh | `https://apisbx.abdm.gov.in/hcx/abha/biometric/`                    |
| Face                             | `https://apisbx.abdm.gov.in/pmjay/sbxhcx/abdmproxy/abha/biometric/` |

A client written against one base path will fail on the other, and the failure looks like a routing problem rather than a configuration one.

## Headers

Every call carries the ABDM session token on `Authorization`. The other headers depend on the call.

| Call                           | Headers besides `Authorization`                                                         |
| ------------------------------ | --------------------------------------------------------------------------------------- |
| `auth/init`, `auth/verify`     | `process`, `payerid`, `Content-Type: application/json`, `Accept: */*`                   |
| `auth/refresh/token`           | `process`, `payerid`, `R-token: Bearer <refresh token>`                                 |
| `faceauth/init`, `capture/pid` | `REQUEST-ID`, `TIMESTAMP`, `Content-Type: application/json`, `Accept: application/json` |
| `v2/auth/verify`               | The same four, plus `process` and `payerid`                                             |

No source puts `process` or `payerid` on `faceauth/init` or `capture/pid`. The face rows follow Biometric Authentication Implementation Steps. The FaceAuth Postman collection sends less: `Authorization` alone on `faceauth/init`, and no `REQUEST-ID` or `TIMESTAMP` on any face call.

Three points that cost time.

**`Authorization`, not `bearer_auth`.** The exchange's own endpoints in this documentation read the token from `bearer_auth`. These read it from `Authorization`. Sending only the habitual header gets a `401` that looks like an expired token.

**`process` is a header, and it is the scheme's process type.** `Preauth` at admission, `Discharge` at discharge and, on a cyclic case, at every visit. The rules elsewhere in this documentation say "process type Discharge" without saying it is an HTTP header. This is it.

**`payerid` names the payer** the authentication is being performed for.

## Fingerprint and iris

A two-call pair. Initiate, capture on the device, verify.

### Initiate

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/hcx/abha/biometric/auth/init' \  --header 'Accept: */*' \  --header 'Content-Type: application/json' \  --header 'Authorization: Bearer <access token>' \  --header 'process: Preauth' \  --header 'payerid: <payer code>' \  --data-raw '{    "scope": [      "abha-login",      "aadhaar-bio-verify"    ],    "loginHint": "abha-number",    "loginId": "91-XXXX-XXXX-1234",    "otpSystem": "aadhaar",    "authMode": "FINGERPRINT"  }'
```

[Biometric auth init in the API reference](/docs/nhcx/v1/api/biometric/endpoints/biometric-hcx-abha-biometric-auth-init)

| Field                               | Fingerprint                            | Iris                                    | Face                                    |
| ----------------------------------- | -------------------------------------- | --------------------------------------- | --------------------------------------- |
| `scope`                             | `["abha-login", "aadhaar-bio-verify"]` | `["abha-login", "aadhaar-iris-verify"]` | `["abha-login", "aadhaar-face-verify"]` |
| `authMode`                          | `FINGERPRINT`                          | `IRIS`                                  | `FACE_AUTH`                             |
| `authMethods`, on verify            | `bio`                                  | `iris`                                  | `face`                                  |
| Capture, under `authData` on verify | `bio.fingerPrintAuthPid`               | `iris.irisAuthPid`                      | `face.faceAuthPid`                      |

The face column is on this host, not the proxy. The NHCX-PMJAY-HMIS Integration Guide and the Biometric Authentication APIs Postman collection list it beside fingerprint and iris, as alternatives in comments on the fingerprint sample. Neither shows a face request made this way or says where its capture comes from. Biometric Authentication Implementation Steps takes face through the separate flow on the proxy host, below, which is the only face path documented end to end. No published source says when to use one rather than the other; confirm with NHA before building on this one.

`loginId` is the ABHA number **with** hyphens here, which is the opposite of the envelope convention.

The response carries the transaction ID the verify call quotes:

```json
{  "txnId": "8c8a12e3-xxxx-4278-xxxx-10acffa44f07",  "authMode": null,  "message": "FingerPrint authentication request successfully sent.",  "status": null}
```

### Verify

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/hcx/abha/biometric/auth/verify' \  --header 'Accept: */*' \  --header 'Content-Type: application/json' \  --header 'Authorization: Bearer <access token>' \  --header 'process: Preauth' \  --header 'payerid: <payer code>' \  --data-raw '{    "scope": [      "abha-login",      "aadhaar-bio-verify"    ],    "authData": {      "authMethods": [        "bio"      ],      "bio": {        "txnId": "<txn id>",        "fingerPrintAuthPid": "<pid block>"      }    },    "authMode": "FINGERPRINT"  }'
```

[Biometric auth verify in the API reference](/docs/nhcx/v1/api/biometric/endpoints/biometric-hcx-abha-biometric-auth-verify)

`authMethods` and the key the capture goes under follow the method, as the table above gives them.

On success:

```json
{  "txnId": "d21b3db9-478a-xxxx-xxxx-8f75e7f86b9f",  "authResult": "success",  "message": "… verified successfully",  "token": "eyZhx….",  "refreshToken": "eyZhx….",  "expiresIn": 1800,  "refreshExpiresIn": 1296000,  "accounts": [ { "ABHANumber": "91-XXXX-XXXX-1234", "name": "…", "status": "ACTIVE", "…": "…" } ]}
```

### The WADH, and error K-547

The device capture needs a wrapped Aadhaar data hash, and the portal records one wrong value as the cause of a specific error. If the biometric APIs return **K-547**, the `lr` parameter was sent as `N` and must be `Y`.

```text
ra  = deviceType        // 'F' for fingerprintrc  = 'Y'lr  = 'Y'               // the one that is usually wrongde  = 'N'pfr = 'N'text = '2.5' + ra + rc + lr + de + pfrwadh = Base64(SHA-256(text))
```

This is the only device-level detail the published material gives, and it is the one failure an integrator cannot reason their way out of.

## Face authentication

A four-step flow on the other host, because the capture happens on the patient's own phone rather than on a hospital device.

**1. Initiate.**

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/abdmproxy/abha/biometric/faceauth/init' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'Authorization: Bearer <access token>' \  --header 'REQUEST-ID: <uuid>' \  --header 'TIMESTAMP: <iso timestamp>' \  --data-raw '{    "scope": [      "abha-enrol",      "face-auth"    ]  }'
```

[Face auth init in the API reference](/docs/nhcx/v1/api/biometric/endpoints/biometric-pmjay-sbxhcx-abdmproxy-abha-biometric-faceauth-init)

Returns a `txnId`.

**2. Show a QR code.** Render `https://phrsbx.abdm.gov.in/face-auth?txnId=<txnId>` as a QR code. The patient scans it with the ABHA app and completes the face scan there.

**3. Poll for the capture.**

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/abdmproxy/abha/biometric/capture/pid' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'Authorization: Bearer <access token>' \  --header 'REQUEST-ID: <uuid>' \  --header 'TIMESTAMP: <iso timestamp>' \  --data-raw '{    "txnId": "<txn id>"  }'
```

[Face auth capture PID in the API reference](/docs/nhcx/v1/api/biometric/endpoints/biometric-pmjay-sbxhcx-abdmproxy-abha-biometric-capture-pid)

Answers `{"status": "PENDING", "message": "Awaiting PID capture"}` until the patient finishes, then `{"status": "COMPLETE", "message": "PID capture successful"}`. Poll this; there is no callback.

**4. Verify with the encrypted Aadhaar number.**

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/abdmproxy/abha/biometric/v2/auth/verify' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'Authorization: Bearer <access token>' \  --header 'REQUEST-ID: <uuid>' \  --header 'TIMESTAMP: <iso timestamp>' \  --header 'payerid: <payer code>' \  --header 'process: Preauth' \  --data-raw '{    "authData": {      "authMethods": [        "face_auth"      ],      "face": {        "txnId": "<txn id>",        "aadhaar": "<encrypted aadhaar>",        "mobile": "<aadhaar mobile>"      }    },    "authMode": "FACE_AUTH"  }'
```

[Face auth verify in the API reference](/docs/nhcx/v1/api/biometric/endpoints/biometric-pmjay-sbxhcx-abdmproxy-abha-biometric-v2-auth-verify)

**The Aadhaar number is encrypted, not sent in the clear.** Use the X.509 public key the portal publishes with the transformation `RSA/ECB/OAEPWithSHA-1AndMGF1Padding`. The ciphertext is roughly 680 base64 characters for a 4096-bit key. Never log it, never store it, and never attempt to validate it as a twelve-digit number.

The response carries the same token pair plus a full ABHA profile: name, date of birth, gender, photo, address, state and district. Take from it only what your record needs.

## The tokens

| Token         | Life                       | Header it is sent on later    |
| ------------- | -------------------------- | ----------------------------- |
| User token    | 1,800 seconds, 30 minutes  | The PMJAY claim-event header  |
| Refresh token | 1,296,000 seconds, 15 days | `R-token` on the refresh call |

```bash
curl --location --request GET 'https://apisbx.abdm.gov.in/hcx/abha/biometric/auth/refresh/token' \  --header 'R-token: Bearer <refresh token>' \  --header 'Authorization: Bearer <access token>' \  --header 'payerid: <payer code>' \  --header 'process: Preauth'
```

[Biometric auth refresh token in the API reference](/docs/nhcx/v1/api/biometric/endpoints/biometric-hcx-abha-biometric-auth-refresh-token)

Refreshing returns a **new refresh token** whose 15 days run from that moment. The portal's advice is to call the refresh endpoint once within every ten days and store the new token, which keeps a chain alive indefinitely.

Two rules the scheme enforces on top of the lifetimes.

- **Refresh automatically for the duration of a transaction cycle.** If the user token lapses mid-case, start a fresh biometric authentication. It is not enough to have authenticated once at some point.
- **A refresh token is not a capture.** On a cyclic procedure the payer pays only for cycles with a live biometric, and a refresh token is accepted only at the final claim. Every visit needs a real capture, with `process` set to `Discharge`.

## When biometrics are not possible

Two separate situations, and they are handled differently.

**The beneficiary's ABHA is not linked to their PMJAY card.** Biometric authentication does not apply at all. Follow the scheme's existing KYC protocols.

**Biometrics are possible in principle but fail in practice.** Capture an Aadhaar exemption consent document, signed by both the patient and a hospital representative, store it digitally against the beneficiary record, and answer the scheme's authentication-consent questionnaire in the bundle.

There are two such questionnaires and they come from different places:

| Form                   | Where it comes from                                                               | Used at          |
| ---------------------- | --------------------------------------------------------------------------------- | ---------------- |
| Authentication Consent | The coverage eligibility response, purpose auth-requirements, and the plan master | Preauthorisation |
| Discharge Consent      | The insurance plan                                                                | Claim            |

Both are the plan's own forms, found by title in the package master, so read the URL and the link ids off the master rather than writing them into code. The answers travel as a `QuestionnaireResponse` referenced from a supporting-info entry of category `INF`, code `ODN`. The payer refuses a request with neither a valid token nor the matching response, and names which is missing: `PAYR-1256` at preauthorisation, `PAYR-1363` at the claim.

The consent has a prescribed format that the payer's fraud engine checks, and the exemption undertaking is submitted to the payer at claim time.

**The one case with no fallback is a cyclic procedure**, where live biometrics are required at every step and a consent form cannot stand in.

## What to store

- The user token and its expiry, against the case rather than the session.
- The transaction ID of every authentication, the method used and the moment it succeeded. On a cyclic case the payer checks each cycle's recorded start and end against the biometric timestamp, and a mismatch voids the cycle.
- The exemption consent document, linked to the beneficiary record, where one was used.
- Nothing else from the ABHA profile beyond what the encounter needs, and never the encrypted Aadhaar value.

## What to test

- Each of the three methods end to end.
- Token expiry mid-case, and automatic refresh.
- A refresh token older than fifteen days.
- The consent fallback at preauthorisation and again at discharge.
- A case authenticated by one method at admission and another at discharge.
- A cyclic case with a capture at every visit, and one deliberately missing, to confirm the payer pays only for captured cycles.


---

# Discharge and claim

On the general network the claim is two submissions. A provisional one goes before the patient leaves, so the payer can object while corrections are still cheap. The final one goes after discharge, with the finalised bill, and is the one adjudicated for settlement. Both are the same `Claim` resource with `use = claim`, told apart by workflow code.

## What the user does

**Discharge.** The user records the discharge type, from the NRCeS set: to home, to mortuary, left against medical advice, discharged against medical advice. Discharge date, and surgery date where there was one. The documents available at this point are attached and the provisional submission goes.

**Final claim.** After the payer's answer to the provisional submission, the finance section: hospital bill number and date, the bill itself, the amount claimed. Post-operative evidence and anything the payer flagged on the provisional review are attached. The claim amount may not exceed the preauthorisation's approved amount; enforce it before submit.

## What the system calls

```text
POST /v1/claim/submit      workflow 15, the final claimcallback /v1/claim/on_submit
```

The provisional discharge submission carries workflow 14 and the same `Claim` bundle. The workflow sheet defines the code and the handbook describes the stage, but neither names the endpoint it travels on; `/v1/claim/submit` is the natural home, and the sample bundles do not include one. Confirm with the payer before building the provisional step. No discharge path is published, so workflow 14 in `x-hcx-workflow_id` is the only thing that tells a discharge from a claim. The envelope marks that field optional. On a discharge submission, always send it.

Same recipient, same reference as the preauthorisation, a new correlation ID each time. The handbook's advice is to build the claim from the preauthorisation bundle. Same diagnosis and procedures unless treatment deviated, estimated amounts replaced with the bill, the full document set added, and the `preAuthRef` from the approval carried in.

## What goes in the bundle

The same `Claim` as the preauthorisation with `use = claim`. That single field is the difference the payer keys on. What changes in practice:

- Supporting-info dates grow from two to four, plus the discharge status:

| Field                | Category          | Code                           |
| -------------------- | ----------------- | ------------------------------ |
| Registration date    | `OTH`             | `EDT`                          |
| Admission date       | `ADMD`, or `ONS`  | `ADDD`                         |
| Surgery date         | `SURD`, or `ONS`  | `ADDD`, or `PSP`               |
| Discharge date       | `DSCHD`, or `ONS` | `ADDD`, or `DSDE`              |
| Discharge status     | `DIS`             | `DTH`, `DTM`, `LAMA` or `DAMA` |
| Death date, if `DTM` | `ONS`             | `DTM`                          |

**Two forms exist for those three dates and they are not interchangeable.** The payer's own error codes describe the `ONS` form with distinct codes per date. Every one of the twenty-two published sample bundles uses the other: category `ADMD`, `SURD` or `DSCHD`, all three carrying the code `ADDD`, so the category is what tells them apart and the code is noise. Send what the samples send, keep the `ONS` form behind a switch, and settle it with your payer before certification. The Codes and Value Sets chapter sets out both.

- The discharge summary as a document under category `HDS`.
- The bill under category `MB`, and the remaining mandatory documents the plan lists for claim rather than preauthorisation.

## Reading the answers

The provisional submission is answered with 261 approved, 262 rejected or 263 queried. A rejection here means fix and resend before the final claim; nothing is closed.

The final claim uses the same decision table as preauthorisation, with two additions. The payer may send several interim answers on the same correlation ID before a final one: `28` in process, `29` forwarded, each with `response.partial`. Keep listening until `response.complete`. And a rejection, `291` with reason `cancelled`, closes the claim permanently; nothing further can be submitted against that claim number except a Task.

The claim is only closed once payment code 33 arrives with a UTR. Adjudication closes the decision; settlement closes the money.

## What the payer checks on a claim

On top of the preauthorisation checks, a claim is refused for these.

| Check                                                                                                   | Why it exists                                                                                                                |
| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| An approved preauthorisation exists for the case number                                                 | `ERR-PYR-CLM-007` under PMJAY, where the claim goes out under the pre-authorisation's number rather than a number of its own |
| No claim already raised against it                                                                      | One case, one claim                                                                                                          |
| Every item was on the preauthorisation, was not rejected there, and is not claimed at a higher quantity | The claim cannot grow past what was approved                                                                                 |
| The discharge status and the discharge date are present                                                 | They are what tell the payer the episode ended, and when. The gateway checks for them before the payer sees the bundle       |
| The amount is within the approved amount and the wallet                                                 | Enforce it before enabling submit                                                                                            |
| Under PMJAY, the discharge biometric token or the discharge consent questionnaire                       | `PAYR-1363` names the missing form                                                                                           |

## After a decision

| Situation           | What the user does                              | What the system sends                                                                    |
| ------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Query               | Attaches what was asked, replies from the inbox | Communication response, or claim bundle with workflow 151 where the payer takes it there |
| Rejected or reduced | Appeals, with a document                        | Task, code `reprocess`, workflow 36                                                      |

The Task names the case by claim number and carries a reason: `claimrejected` for a rejection, `partialpayment` for a shortfall, and the value set also allows `erroneousclaim`. The payer's answer comes on `/v1/task/on_submit` as a Task wrapping a `ClaimResponse`, read with the same parser as any other: 252 approved, 253 rejected, 254 queried. NHCX publishes no workflow code for answering a 254 reprocess query; the handbook's workflow 19 is the preauthorisation query response code, not a reprocess one. Until NHA allocates a code, confirm with the payer how it wants the answer sent. Map the payer's denial reasons, `ClaimError-1` onward, into the appeal screen so the user sees why before deciding whether to appeal.


---

# Provider overview

A provider system is the hospital's side of the exchange. It takes a patient from the front desk to a settled claim without anyone leaving the HMIS. It does that by making a fixed set of calls to the exchange and hosting a fixed set of callbacks for the payer's answers.

This section assumes the base framework from Getting Started is working: you have a token, a participant record, your own key, and a callback endpoint that opens messages. Everything here is what goes on top.

Registration and Eligibility, Insurance Plan, Preauthorisation, Discharge and Claim, and Payment and Communication describe the flow as NHCX defines it for any payer. PMJAY runs the same endpoints with different rules around them; those rules are collected in PMJAY Provider so the generic flow stays readable and the scheme's additions are in one place, and Biometric Authentication covers the scheme's proof that the beneficiary was present. UI Guide turns all of it into screens, for whoever is designing the hospital's interface rather than its integration. Provider Checklist is the checklist you have to demonstrate to leave the sandbox.

## What the hospital sees

```mermaid
flowchart LR
  S[Patient search] --> R[Registration]
  R --> T[Treatment plan]
  T --> P[Preauthorisation]
  P --> Q[Query inbox]
  Q --> P
  P --> E[Enhancement]
  E --> P
  P --> D[Discharge]
  D --> C[Claim]
  C --> Q
  C --> M[Payments]
  C -. rejected or short .-> X[Reprocess]
```

The user-facing shape is a handful of screens that map one-to-one onto exchange calls. The mapping is worth fixing early, because it decides where each API is called from.

| Screen           | What the user does                                                                 | Exchange call behind it                                                          |
| ---------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Patient search   | Finds the beneficiary by ABHA, member ID or mobile; picks the payer                | Participant list, policy lookup                                                  |
| Registration     | Confirms cover and sees the remaining limit                                        | Coverage eligibility, purpose validation                                         |
| Treatment plan   | Picks the service or package, sees what is covered and what documents are required | Insurance plan (cached), eligibility with purpose benefits and auth-requirements |
| Preauthorisation | Fills clinical and financial sections, attaches documents, submits                 | Preauthorisation submit                                                          |
| Enhancement      | Adds procedures or days against an approved case                                   | Preauthorisation submit, enhancement code                                        |
| Query inbox      | Reads a payer request for more, attaches what was asked, replies                   | Communication request and response                                               |
| Discharge        | Records discharge and sends a provisional claim before the patient leaves          | Claim submit, discharge code                                                     |
| Claim            | Confirms the final bill, submits                                                   | Claim submit                                                                     |
| Reprocess        | Appeals a rejection or a reduced approval                                          | Task submit                                                                      |
| Payments         | Sees notices, UTR and deductions; acknowledges                                     | Payment notice callback, acknowledgement                                         |
| Case status      | One line per case with its current state                                           | Driven by callbacks and status check                                             |

## What the system calls

From the Overview's use-case catalogue, a provider calls the B-series and the shared A-series, and hosts the callbacks for each. In sequence for one admission:

1. `/fetch/participants/list` and `/participant/get/policies`, to find the payer and the policy.
2. `/v1/insuranceplan/request`, once per policy, refreshed on a schedule.
3. `/v1/coverageeligibility/check`, at registration and again before each submission.
4. `/v1/preauth/submit`, for the first request and every follow-up on it.
5. `/v1/claim/submit`, for the provisional discharge submission, the final claim, and query answers.
6. `/v1/task/submit`, to cancel a preauthorisation or appeal a claim.
7. `/v1/status`, whenever a case has gone quiet.

And hosts `on_check`, `on_request`, `on_submit` for each of those, plus `/v1/communication/request`, `/v1/paymentnotice/request`, `/v1/on_status` and `/v1/error`.

## What the system must keep

A provider integration is as much a data model as an API client. Persist, per case:

- The payer's participant code, the processor code, member ID, product and policy number from the lookups.
- Every correlation ID sent, with the workflow code and what it was for, so callbacks can be matched.
- Every raw callback as received, before it is interpreted.
- The case state, derived from callbacks. The handbook's mapping is a good starting point: approved, partially approved, pending on a query, rejected, cancelled, and then settled once payment code 33 arrives.
- The insurance plan, versioned, with the version used on each submission.

## Build it in this order

The exchanges depend on each other, and building them out of order means testing against answers you cannot yet get.

| Order | Build                                    | Because                                                                                      |
| ----- | ---------------------------------------- | -------------------------------------------------------------------------------------------- |
| 1     | The base framework from Getting Started  | Nothing below works without a token, a key, a participant record and a callback that answers |
| 2     | Participant list and policy lookup       | They produce the processor code every later message is addressed to                          |
| 3     | Coverage eligibility, purpose validation | The cheapest exchange to get right, and the one that proves the whole round trip             |
| 4     | Insurance plan, cached                   | The treatment screen is built from it, and preauthorisation validation depends on it         |
| 5     | Preauthorisation, then its query answer  | The first bundle with clinical content, and the one payers scrutinise hardest                |
| 6     | Claim, then its query answer             | Reuses the preauthorisation bundle with one field changed                                    |
| 7     | Payment notice and acknowledgement       | Closes the case, and under PMJAY gates the shortfall                                         |
| 8     | Task: cancel and reprocess               | Needed for sandbox exit, rarely needed on day one                                            |

Provider Checklist is the checklist you demonstrate to leave the sandbox, and it names all thirteen use cases NHA asks for.

## Error families, and which desk they belong to

Errors arrive from two places and they go to two different people.

| Family                              | Where it arrives                        | Who acts                                                                       |
| ----------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------ |
| `PAYR-10xx`, `PAYR-11xx`            | Inside the sealed response              | The desk. Show the payer's own sentence                                        |
| `PAYR-102x` structural block        | Inside the sealed response              | The integration team. It means an id or sequence is missing, not a wrong value |
| `ClaimError-n`, `PreauthError-n`    | Inside the sealed response, on a denial | The desk, on the appeal screen, so the user sees why before deciding to appeal |
| `ERR-PYR-CLM-007`                   | Inside the sealed response              | The integration team. The claim was sent under the wrong case number           |
| Protocol response, `response.error` | On the callback, in the clear           | The integration team. The message could not be opened                          |
| `NHCX-1010`                         | From the exchange                       | The integration team. A verdict was sent after the correlation was retired     |

A protocol response is never a claims-desk problem. Route it away from the queue and toward whoever owns the integration.

## Where the rules live

Two rulebooks shape what a provider may send, consulted in this order:

1. **The insurance plan** says what the policy covers, at what limits, with which documents required.
2. **The eligibility response** says whether this patient is covered right now, how much remains, and which of the plan's requirements apply to the services chosen.

A scheme adds a third: its own rules for how a case is built. For PMJAY those are in PMJAY Provider.


---

# Insurance plan

The plan is the policy as data. It tells the hospital system what a policy covers, at what limits, under what conditions, and with which documents. So the treatment screen is built from the payer's own rules rather than from a PDF someone once read. Nothing on that screen should be typed in by hand if the plan already knows it.

## What the user does

The user never asks for the plan. It is fetched in the background and the treatment screen is built from it.

**Choose what is being treated.** The specialties, services or packages offered are the ones the plan lists for this hospital. Nothing else is shown.

**See the terms.** The limit for each benefit, any waiting period or exclusion that applies, and whether preauthorisation is required for it.

**See the requirements** as a checklist: the documents the plan lists as mandatory at policy level and per benefit, and any questionnaire the payer attaches to a benefit. Render the questionnaire from the plan's Questionnaire resource rather than hard-coding it.

## What the system calls

```text
POST /v1/insuranceplan/request     Task, code poll, inputs policyNumber and providerIdcallback /v1/insuranceplan/on_request
```

Fetch once per policy the hospital deals with, and refresh on a schedule and whenever a payer communication with reason `policychange` arrives. The handbook's guidance is to fetch at registration or admission, before treatment planning, and alongside eligibility.

## What comes back, and how to store it

A collection bundle with one `InsurancePlan`, the `Organization`s, and one `Questionnaire` per requirement.

**Two shapes exist, and they are not layout variants.** A payer picks one per product, and which one arrives decides how the treatment screen works. A system that handles both needs two code paths behind one screen.

|                             | Package-based                                                                               | Coverage-based                                                     |
| --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Sent by                     | Government schemes. PMJAY throughout                                                        | Private insurers and their TPAs                                    |
| Structure                   | `plan → specificCost → category → benefit → cost`, with the rules on `coverage[]` alongside | `coverage → benefit → limit`                                       |
| The unit                    | A named package at a fixed all-inclusive rate                                               | A benefit with a money cap, such as ICU charges or room rent       |
| What the user picks         | A specialty, then a package. The rate is fixed and not editable                             | A service, then bills against it                                   |
| Where the amount comes from | The plan's `Procedure` or `Stratification` cost line                                        | The hospital's own bill, checked against the benefit limit         |
| Rules arrive as             | Sixteen `Claim-Condition` flags per package                                                 | `benefit.requirement` strings such as "Pre-authorisation required" |
| What blocks submission      | A code or display differing from the plan, character for character                          | An amount over the limit, or a missing mandatory document          |
| Sampled                     | Yes, one 21 MB payload                                                                      | No sample in the published corpus                                  |

PMJAY Provider covers what the package flags do. The FHIR Reference has a chapter for each shape.

### Storing it

Store the plan as data, not as a blob. Both shapes need the same five things pulled out and indexed.

| What to extract        | Package-based                                                      | Coverage-based                                                |
| ---------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------- |
| The pickable list      | Specialties from `coverage[].type`, packages from `benefit[]`      | Cover types from `coverage[].type`, services from `benefit[]` |
| The money              | `specificCost` cost lines, joined to the rules on the package code | `benefit.limit[].value`                                       |
| The rules              | The sixteen flags per package                                      | The `requirement` string                                      |
| The document checklist | `Claim-SupportingInfoRequirement`, package level plus plan level   | The benefit's required documents                              |
| The forms              | `Questionnaire` resources the requirements point at                | As published by the insurer                                   |

A scheme plan is large. The published PMJAY plan is 21 MB with 2,217 entries, and it cannot be handled by a naive JSON parser inside a request-response cycle. Stream it, or parse it once on a worker and store the result.

Store the plan as data, not as a blob: benefits with their limits or rates, the conditions and exclusions from the plan's extensions, the document requirements, and the questionnaire URLs. Keep a version stamp on every stored plan, and record which version each submission used. A rate that changed on the payer's side without a refresh on yours is the commonest cause of a reduced approval.

## What to validate before submitting

The plan is also the first line of validation, run on the server, not only in the browser:

- Codes and displays exactly as the plan has them, character for character, **including its misspellings**. The published PMJAY plan carries `Opthalmology` and `Transegender Procedure`, and a preauthorisation whose display differs from the plan's is rejected on the display.
- Amounts within the benefit's limit; quantities within what the plan allows.
- Every document the plan marks mandatory attached before submit is enabled.
- Under a package plan, implant and stratification counts within their maxima, and a standalone package with nothing else beside it.

A base rate of zero is not an error. In the published plan, package `MG004A` has a base limit of 0 INR and stratification limits of 1,800 to 4,500, meaning the payable amount is decided entirely by the bed category chosen. Do not treat 0 as missing data, and do not submit a zero-value item line.

## When the plan goes stale

Refresh on a `policychange` communication, on whatever periodic schedule operations accepts, and before treatment planning if the cached copy has no version stamp. The FRD says weekly; the scenario sheet says every fifteen days. Under PMJAY an outdated tariff version causes a rate mismatch and automatic rejection on suspicion of tampering.

Stamp the cache with the plan's scheme revision, and record on every preauthorisation and claim which revision it was built against. A rate that changed on the payer's side without a refresh on yours is the commonest cause of a reduced approval. The revision stamp is what turns that into a diagnosable event rather than a mystery.


---

# Payment and communication

Two exchanges arrive unasked. The payer initiates both, and the provider's job is to receive, act, and acknowledge.

## Payment notices

### What the user sees

A payments screen, per case, showing the sequence as it happens: initiated, processed, settled. On settlement, the UTR number, the gross amount, the TDS and other deductions, and the net. A button to acknowledge. Reconciliation staff will match the UTR against the bank statement, so print it as text they can read and select. Copyable means a copy control next to the printed value, not the value tucked inside an input box in its place.

### What the system hosts

```text
callback /v1/paymentnotice/request     workflows 30, 31, 33
```

Three notices can arrive for one claim, and each is a fresh delivery to acknowledge: 30 when the payer initiates, 31 when the bank processes, 33 when it settles. Only 33 carries the UTR. Mark the case settled on 33, not before.

### What comes in

A collection bundle: a `Task` with code `deliver` wrapping a `PaymentNotice` and a `PaymentReconciliation`, plus the two `Organization`s.

- `PaymentNotice.amount` is the net paid; `paymentStatus` is `paid` or `cleared`.
- `PaymentReconciliation.paymentIdentifier.value` is the UTR on the settled notice, 33. On 30 and 31 the same field can carry a scheme reference, so reconcile against the bank only on 33.
- `PaymentReconciliation.detail[]` itemises the money: one line with type `TDS`, one with type `Payment`, and any others the payer uses (approved amount, service tax, advance, recovered, penalty). Net plus deductions should equal the approved amount; if it does not, flag it.

### The acknowledgement

A `Task` with `status = completed`, code `status`, and an output of type `status` whose value is `paymentack`, plus the claim number as a second output. Workflow 17. Send it to the payer.

Where it goes is stated two ways on the portal: the Payment document and exit checklist say `/v1/paymentnotice/on_request`; the handbook says `/v1/task/submit`. Build to send to `on_request` and make the path configurable per payer.

## Communication requests

### What the user sees

An inbox. Each message has a reason, a priority and a body, and needs a different response. A request for additional information needs documents attached; this is how a payer asks for more on a case. A turnaround-time alert goes to the claims desk to chase. A grievance needs a reply and possibly a corrective action. A benefit update should refresh the balance shown on the case. A policy change should trigger a plan refresh. An arbitration acknowledgement just tells the desk the appeal has been received.

### What the system hosts

```text
callback /v1/communication/requestreply    /v1/communication/on_request
```

Switch on `Task.reasonCode`: `additionalinfo`, `tatquery`, `grievance`, `walletupdate`, `policychange`, `claimArbitration`. Build the `additionalinfo` path first; it is the query channel on the general network. Then `tatquery`, which the handbook reports as the most common reason in live traffic.

### What comes in, and what goes back

A collection bundle: a `Task` with code `poll` and an input of type `include` pointing at a `Communication`, plus the `Organization`s. On the `Communication`: `category` (reminder, notification, instruction or questionnaire), `priority` (routine, urgent, asap, stat), `topic` (usually progress-update), and the case reference as its identifier.

The answer is the same bundle shape sent back with the same correlation ID and `Task.status = completed`. Keep both `Organization` entries, typed `prov` and `pay`; their order in the bundle carries no meaning, and the payer tells the answer from the request by your sender code, the correlation ID and the Task status. For a plain acknowledgement, send it within the 30-second window regardless of whether the underlying issue is resolved. For an `additionalinfo` request, the answer carries the requested documents as well.

## What to reconcile

The reconciliation is what accounts works from, so store its lines rather than only the net.

| Line type                                        | What it is                                                                                |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `Payment`                                        | The net amount the bank moved                                                             |
| `TDS`                                            | Tax deducted at source                                                                    |
| `approvedamount`, `claimedamount`                | What was granted and what was asked                                                       |
| `servicetax`, `advance`, `recovered`, `penality` | Other adjustments the payer applies. Note the spelling of the last one; it is the payer's |

Net plus deductions should equal the approved amount. When it does not, flag it rather than silently accepting the difference, because that is the only place a short payment shows up before the shortfall window opens.

A return payment, where money has to come back, has its own codes: RP1 intimation, RP2 acknowledged, RP3 failed.

## Two acknowledgements, and they are different things

The screen should not confuse them, and neither should the code.

|                         | Transport acknowledgement                                        | Business acknowledgement                            |
| ----------------------- | ---------------------------------------------------------------- | --------------------------------------------------- |
| What it is              | The `202` and receipt your callback returns                      | A `Task` on workflow 17 sent back to the payer      |
| When                    | Automatically, within 30 seconds of the notice arriving          | When the notice has been recorded against the claim |
| Who sees it             | Nobody. It is protocol                                           | The desk, as a button and a sent state              |
| What it means           | The message was taken in                                         | The provider has recorded the payment               |
| What happens without it | The exchange retries five times, then retires the correlation ID | Under PMJAY, the shortfall window never opens       |

## Notifications for patients

If the hospital also runs a patient app, it can subscribe on the beneficiary's behalf and receive the same events as human-readable messages. That is a separate participant role, covered under the E-series in the Overview.


---

# PMJAY adjudication APIs

A PMJAY case is not decided over NHCX. The exchange carries the submission to the scheme and carries the verdict back, but the decision itself is taken in the State Health Agency's own Transaction Management System, by a named role, on that system's schedule. Between the two sits the NHCX Payer Service, which is how an external integrator reads and drives that queue.

The previous chapter, PMJAY Sandbox Run, records what one case did; this one is the interface.

The source for the endpoints, the roles and their action names is the NHCX Payer Service API Workflow Guide for External Integrators, a supporting document on the portal's NHCX-PMJAY-HMIS Integration page, and it remains the authority on them. What the service did beyond the guide, the case id it insists on, its refusals and its pace, is from that sandbox run.

It matters to two audiences. A scheme payer building its own side needs to know what shape the exchange expects a role-based queue to present. An integrator testing against the sandbox needs it because there is no other way to make a PMJAY case move.

## Two endpoints, two hosts

| What               | Where                                                                              |
| ------------------ | ---------------------------------------------------------------------------------- |
| Who holds the case | `POST https://apisbx.abdm.gov.in/pmjay/sbxhcx/nhcxpayerservice/v1/get/user-role`   |
| Act on the case    | `POST https://apisbeta.nha.gov.in/pmjay/hcx/nhcxpayerservice/wrapper/process/case` |

Both take an ordinary ABDM session token on `bearer_auth`, with `Content-Type: application/json` and `Accept: application/json`. The token is the same one every other call uses, minted from the participant's client ID and secret at the sessions endpoint. In the sandbox it lives 1,200 seconds.

Note that the two endpoints sit on different hosts. That is not a documentation error; it is how the service is deployed.

Both addresses are sandbox addresses. `apisbeta.nha.gov.in` is the only published address for acting on a case, and no production host is published for either call. Ask for both production hosts at onboarding and keep them configurable, as Base URLs advises for every other service.

## Who holds the case

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/nhcxpayerservice/v1/get/user-role' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "caseid": "<case number>",    "payerid": "<payer code>"  }'
```

[Adjudicator: get the user role for a case in the API reference](/docs/nhcx/v1/api/adjudicator/endpoints/adjudicator-pmjay-sbxhcx-nhcxpayerservice-v1-get-user-role)

```json
{ "currentuserrole": "PPD-Trust", "errormessage": null }
```

**`caseid` is the scheme's case id, not the hospital's claim number.** It is the digits at the end of the case reference the payer issues. Asked about a hospital's own number the service answers that no data was found and tells you to use the current active case id.

A hospital therefore has to learn the scheme's case id for every preauthorisation it raises. The sandbox gives it out in two places: inside the `PAYR-1238` refusal of the next request for that beneficiary, and, once a request is accepted, in the payer's acknowledgement and status answers on the case. Store it beside your own claim number the moment it appears.

**Read the role before every action.** The service moves cases on its own schedule, and the role that answers is the only one whose action names are legal. A cycle that assumes the next step in the table will be refused.

**A preauthorisation role on a claim means "not yet".** If the role lookup still answers `PPD-Trust` while you are asking about a claim, the case has not left the preauthorisation queue. The role names where the case is, not what you are asking about.

## Acting on the case

One endpoint, one body shape, with the action spelled exactly as the table gives it for the role that currently holds the case.

```bash
curl --location --request POST 'https://apisbeta.nha.gov.in/pmjay/hcx/nhcxpayerservice/wrapper/process/case' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "casenumber": "<case number>",    "action": "Approve",    "receivercode": "<payer code>",    "usecase": "PREAUTH",    "correlationid": "<correlation id>",    "sendercode": "<participant code>",    "memberid": "<member id>",    "remarks": "ok"  }'
```

[Adjudicator: act on a case in the API reference](/docs/nhcx/v1/api/adjudicator/endpoints/adjudicator-pmjay-hcx-nhcxpayerservice-wrapper-process-case)

| Field           | What it carries                                     |
| --------------- | --------------------------------------------------- |
| `casenumber`    | The scheme's case id, as above                      |
| `action`        | Exactly as the role's row gives it. Case-sensitive  |
| `usecase`       | `PREAUTH`, `CLAIM`, or the committee's own name     |
| `receivercode`  | The payer's registry id, without the `@hcx` suffix  |
| `sendercode`    | The provider's participant code, without the suffix |
| `memberid`      | The beneficiary                                     |
| `correlationid` | **A fresh UUID for every call**                     |
| `remarks`       | Free text the desk records                          |

## The role walk

| Step             | Role                    | Actions                              | `usecase`                 |
| ---------------- | ----------------------- | ------------------------------------ | ------------------------- |
| Preauthorisation | `PPD-Trust`             | `Approve`, `Reject`, `Query`         | `PREAUTH`                 |
| Claim 1          | `CEX-Trust`             | `Forward`                            | `CLAIM`                   |
| Claim 2          | `CPD-Trust`             | `cpdApprove`, `cpdReject`, `Pending` | `CLAIM`                   |
| Claim 3          | Medical Audit Committee | `Approve`, `Reject`, `iQuery`        | `Medical Audit Committee` |
| Claim 4          | `ACO-Trust`             | `Approve`, `Reject`, `Pending`       | `CLAIM`                   |
| Claim 5          | `SHA-Trust`             | `Approve`, `Reject`, `Pending`       | `CLAIM`                   |
| Claim 6          | Claim Review Committee  | `Approve`, `Reject`, `Pending`       | `Claim Review Committee`  |

Four things about that table.

**A preauthorisation is one decision. A claim walks a queue.** The roles map onto the scheme's own staff: the Preauthorisation Processing Doctor, the claim executive, the Claim Processing Doctor, the audit and accounts roles, the State Health Agency and, on appeal, the Claim Review Committee.

**The action names are not consistent between roles.** `CPD-Trust` takes `cpdApprove` and `cpdReject`; every other role takes `Approve` and `Reject`. Sending `Approve` to `CPD-Trust` is refused.

**`usecase` changes at the two committees** and carries the committee's full name with spaces, not a code.

**Not every case walks all six.** On the run recorded in PMJAY Sandbox Run the claim was forwarded by `CEX-Trust`, approved by `CPD-Trust`, then by `ACO-Trust` and `SHA-Trust`, after which the role lookup answered with no role at all. Neither committee held the case. The six steps are the roles a case *may* pass through, not a queue every case walks.

## How the decision comes back

The desk call and the NHCX callback are two halves of one step. Acting on the case makes the scheme issue its verdict, and that verdict arrives at the provider over NHCX as an ordinary `ClaimResponse` on the original request's correlation id.

So a provider system driving this in a sandbox has to hold both threads: the payer service call it just made, and the callback it is waiting for. They are correlated by the case, not by the correlation id of the desk call, which is fresh every time.

## What it refuses, and what those refusals mean

- **`No Data found with the caseid <id>. Please use the current active case id.`**

  You asked with the hospital's claim number instead of the scheme's case id.

- **`Event Meta Log not found for correlationId`**

  The exchange has not finished delivering the request you are acting on. Try again shortly.

- **`Case not found for caseId`**

  The case is mid-filing. Try again shortly.

- **An action refused for the current role**

  Read the role again. It has moved, or it never was what you assumed.

The first is a modelling error and needs a fix. The second and third are timing and are safely retried.

## What it will not do

**It is not a status API over NHCX.** A `Task` coded `status` sent to the scheme is refused, first with `PAYR-1018` for a missing reason code and then with `PAYR-1008` for a code and reason combination the scheme does not accept. Where a case stands is read here, not asked for over the exchange.

**It re-queues rather than answering immediately.** The scheme acknowledges an enhancement it has been asked to approve by answering `queued` again, and decides in its own time. On one run the enhancement was approved a minute after the ask; on another it was still queued five minutes on, with the same bundle. Nothing in what you send changes that, and a test suite has to report the scheme's pace rather than assert it away.

**One request at a time on a case.** `PAYR-1322`, which the sandbox sends as "active instance found" although the error sheet gives it another message, is the rule behind most of the timings above. A claim raised while an enhancement is still queued is refused, and the role lookup still answers with the preauthorisation role because the case has not left that queue.

## What a scheme payer should take from this

If you are building the payer side rather than testing against it, the shape worth copying is the separation. The exchange carries messages; the queue decides cases; the two are joined by a case id the payer issues and the provider stores. Three consequences follow for your own build.

- **Issue a case number on the first answer and repeat it on every later one.** The provider files the case under it and every subsequent action names it. A desk asked about a case by the hospital's own number should still find it, but the published reference implementation does not, which is why the provider has to learn yours.
- **Acknowledge before you decide.** Answer every submission at once with an interim response, or the exchange retires the correlation before your adjudicator gets to it. Error Codes covers `NHCX-1010`.
- **Expose where a case is.** Whatever your equivalent of the role lookup is, a provider needs it, because your queue is invisible from the exchange.


---

# PMJAY provider

The chapters before this one describe the flow NHCX defines for any payer. When the payer is PMJAY the endpoints do not change, but the rules around every screen do. This chapter collects them, in the same order as the generic chapters, so that a hospital building for the scheme reads the generic chapter for the shape and this one for the differences.

The Overview's PMJAY chapters explain why these rules exist. This chapter is about what to build.

## What changes, in one table

| Generic flow                                       | Under PMJAY                                                                                                                           |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Patient found by ABHA, member ID or mobile         | Also by Ayushman ID; a member card is shown; the patient is biometrically verified before registration                                |
| Plan is coverage-based or package-based            | Always package-based, with flags on every package that drive the screen                                                               |
| Documents are attached as scans                    | Clinical documents must be structured ABDM health-information types                                                                   |
| Payer queries arrive as a communication request    | Payer queries arrive inside the queried `ClaimResponse`; the answer goes on the preauthorisation or claim endpoint                    |
| Provisional discharge submission, then final claim | No discharge submission; the claim asserts the discharge and carries its details                                                      |
| Appeal once the decision arrives                   | Reprocess after rejection at once; shortfall only after payment 33 is acknowledged; each once; the Committee is final                 |
| Communication channel carries document requests    | Communication channel carries TAT alerts, grievances, wallet and policy changes, arbitration acknowledgements; never document queries |
| Go live when production credentials arrive         | Go live when NHA maps the hospital's HEM ID to its participant ID; in-flight TMS cases finish in TMS                                  |

## Registration

**Search** by Ayushman ID, mobile or ABHA. Show the member card once found.

**Verify the patient biometrically** before registering. Build all three methods, fingerprint, iris and face; any may be the one that works for a given patient, and the scheme requires all three to be available. Fingerprint and iris are an init-then-verify pair. Face is a separate flow: initiate, show a QR code the patient scans in the ABHA app, poll until capture completes, verify with the Aadhaar number encrypted under the key the portal supplies.

On success the system holds a **user token**, valid 30 minutes, with a refresh token. It goes in the header of the eligibility check and the preauthorisation. Refresh it automatically through the transaction; if it lapses, authenticate again. A fresh authentication is required at discharge, and that token rides on the claim. It need not use the same method as the preauthorisation; a case authenticated by fingerprint at admission can be authenticated by face at discharge. And where biometrics fail at discharge, the discharge authentication-consent questionnaire from the plan stands in, exactly as at registration.

**Where biometrics are not possible**, capture the Aadhaar exemption consent, signed by patient and hospital representative, as a document on the record, and answer the authentication-consent questionnaire. There are two of them and they come from different places: the one for a preauthorisation arrives in the coverage eligibility response with purpose auth-requirements, the one for discharge is in the insurance plan. The payer refuses a request that has neither a valid biometric token nor the matching consent response, and names which is missing. The FRD adds that the exemption undertaking is submitted to the payer at claim time. The consent has a prescribed format that the payer's fraud engine checks. The one case with no fallback is a cyclic procedure, where live biometrics are required at every step.

**Applicability.** Biometric verification applies to beneficiaries whose ABHA is linked to their PMJAY card; others follow the scheme's existing KYC.

**Cover.** Eligibility with purpose validation returns the wallet: one benefit entry per wallet, allowed and used. The whole family shares one annual limit; show what remains, and refuse registration when it is exhausted.

**Capture** communication address, care plan and attendant details, and upload the authentication consent.

## Insurance plan

Package-based, and large: the reference response is 21 MB with over two thousand questionnaires. Store it as data, versioned.

**The flags drive the screen.** Every package carries claim-condition flags, and the treatment screen must obey them:

| Flag                               | What the screen does                                                                                  |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `GovtReserved`                     | Hide from private hospitals                                                                           |
| `ApprovalNotRequired`              | Tell the user the case will auto-approve if it is the first preauthorisation and every package has it |
| `ScheduledTATApproval`             | Tell the user the payer's silence within the window means approval                                    |
| `EnhancementAllowed`               | Only these packages may be added during an enhancement                                                |
| `QuantityAllowed`                  | Cap the quantity field                                                                                |
| `ImplantApplicable`                | Show the implant picker                                                                               |
| `MaximumImplantsAllowed`           | Cap the number of implants                                                                            |
| `MultipleImplantsAllowed`          | Allow more than one implant on the package                                                            |
| `StratificationAllowed`            | Show the bed-category picker                                                                          |
| `MaximumStratificationAllowed`     | Cap the number of bed categories                                                                      |
| `MultipleStratificationAllowed`    | Allow more than one bed category on the package                                                       |
| `Standalone`                       | Refuse any other package alongside it                                                                 |
| `ParentProcedure`                  | Require one of the listed parents                                                                     |
| `Unspecified`                      | Free-text name and free-entry amount, validated on the server against the wallet                      |
| `CyclicProcedure`                  | Ask the number of cycles                                                                              |
| `MaximumCyclesAllowed`             | Cap the number of cycles                                                                              |
| `LamaDamaProcedure`                | Offer only on a LAMA or DAMA discharge                                                                |
| `DischargeStagesLamaDamaProcedure` | Offer only at the discharge stages it lists                                                           |
| `IsDayCare`                        | Day-care handling                                                                                     |
| `ProcedureType`                    | Medical and surgical packages cannot be combined, and one medical package per episode                 |
| `LengthOfStay`                     | Maximum length of stay for the package; bounds the days claimed, including the `LM100` day count      |
| `GstApplicable`                    | Whether tax applies to the package                                                                    |
| `GstPercentage`                    | The tax rate when it does                                                                             |
| `IncentiveApplicable`              | Whether a hospital incentive applies                                                                  |
| `IpOpFlag`                         | In-patient or out-patient                                                                             |
| `RulesApplicable`                  | Whether further rules attach to the package                                                           |

That table is the specification. The one published plan payload carries sixteen of these flags and not the rest: `Standalone`, `Unspecified`, `LamaDamaProcedure`, `LengthOfStay`, the tax pair, `IncentiveApplicable`, `IpOpFlag` and `RulesApplicable` appear nowhere in it. Do not read that as proof they are unused, because the sample is one scheme's plan at one moment. Read it as a warning to code defensively:

- **`GstApplicable` and `GstPercentage`**: The handbook describes the first as whether GST is applicable for the benefit and the second as the "GST % applicable for the given benefit". No published source gives a rate or says which packages carry tax. In the handbook's worked claim response the tax is a claim-level total, `ClaimResponse.total` with category `tax`: 100 on a claim of 13,700.
- **`IncentiveApplicable`**: Described only as whether an incentive to the hospital is applicable for the benefit. No published source gives the criteria or the rate. The same worked response carries a claim-level total with category `incentive` of 137 on 13,700, and the handbook's approved reprocess example repeats both figures.
- **`LengthOfStay` (Maximum Length of Stay)**: Specifies the ceiling on inpatient days for the procedure. Stays extending beyond `LengthOfStay` require clinical justification or an approved enhancement request (workflow 13); for LAMA/DAMA discharges, procedure `LM100` daily quantity cannot exceed `LengthOfStay`.

There is a second trap in the same payload, and it will cost a day if you meet it unprepared. The flags and the money live in two different places. The claim-condition flags, the document requirements and the rate limits hang off the plan's coverage benefits, while the costs hang off the plan's own cost list. Both structures carry the same package codes, and neither is complete on its own, so building the treatment screen means joining them on the package code. The Insurance Plan Response chapter in the FHIR Reference sets out both shapes.

**Refresh** weekly per the FRD, or every fifteen days per the scenario sheet, and immediately on renewal, amendment or a `policychange` communication. An outdated tariff version causes a rate mismatch and automatic rejection on suspicion of tampering; keep the version on every submission.

**Add-ons** come from the package's cost qualifiers: implant, stratification, high-end medicine, investigation, each with its own code from the plan master, each a separate item on the bundle.

## Preauthorisation

The four sections of the generic form, with these additions:

- Medical information comes from the HMIS record as structured documents: general findings, personal and family history.
- The STG questionnaire for each package is rendered from the plan and answered here; a missing response for a package that demands one is refused by name.
- Documents and questionnaires required for preauthorisation are those the eligibility call with purpose auth-requirements returns. The rest are mandatory at claim.
- Amounts are the plan's rates and are not editable, except on an unspecified package.
- A preauthorisation cannot be raised more than one day before admission.
- The biometric user token, or the consent questionnaire, must be present.
- `LM100` is never valid here.

**Documents and size limits.**

- Clinical documents (`DIA`, `HDS`, `CD`, `INF`) go as a reference: a `DocumentReference` whose `attachment.data` is a base64 FHIR bundle, content type `application/json` or `application/fhir+json`.
- Scans (`POI`, `POA`, `DOB`, `DEF`, `FIR`, `ATT`) go as attachments.
- One document per item, 2 MB at most.
- A preauthorisation or claim message is capped at 20 MB.
- The scheme's `InsurancePlan` response is bigger, 21 MB to 25 MB, because it embeds over 2,200 questionnaires. HTTP clients and reverse proxies must accept 25 MB for plan fetches.

**Auto-approval** applies when this is the first preauthorisation for the case and every package carries `ApprovalNotRequired`, or when the policy allows turnaround-time approval and the payer has not acted in its window. Show the user which rule applied.

**Queries arrive inside the response.** A queried `ClaimResponse`, workflow 24, carries the query text in `item.adjudication.reason.coding.display` as a pipe-delimited audit trail, `USER~datetime~type~comment~actor`, where `actor` is whoever wrote the entry: `PPD-Trust` on a preauthorisation, `CPD-Trust` on a claim, or the hospital's name. Treat it as display text: split it on `|` and `~` to show each entry and its comment, but never parse a timestamp from it, because the date formats vary. The answer is the same preauthorisation bundle, new correlation ID, original reference, workflow 19, on `/v1/preauth/submit`. Not a communication response, and not a resubmission.

**Enhancement** (13): only against an approved case, only after the previous request has closed, only for packages flagged enhanceable, unlimited until discharge within the wallet. **Resubmission** (121): revises an approved or rejected case for a different amount or package, and voids everything before it. **Cancel** (PC01): allowed until the claim is raised and refused once payment has started.

**Server-side checks** the payer will make and the screen should make first:

- Amount above zero and within the wallet.
- Specialty and package codes and displays exactly as the plan has them.
- Quantity at least one.
- Registration and admission dates present.
- One active preauthorisation per beneficiary across all hospitals.
- Investigations, mandatory for private hospitals.
- Newborn cases with date of birth, gender and documents, within six years.

## Discharge and claim

**There is no discharge submission.** Raising the claim asserts the discharge, so workflow 14 is not used and the discharge details ride on the claim.

**Discharge type** is one of the four, and each has a questionnaire in the plan found by title (Death, Life, LAMA, DAMA). Authenticate the patient again here. Download the feedback form, hand it over, and upload it back. Under `DIS` the value is the stage. The gateway's own rejection message lists three, Before Surgery, During Surgery and After Surgery; the FAQ lists two, Before and After, and says the transmitted value must stay within the NRCeS set. Send what the payer's validation accepts and confirm before building. The value is sent for medical cases as well as surgical ones. A death also sends the death date under `ONS` / `DTM`.

**LAMA or DAMA before or during surgery** voids every approved item. The claim carries the single line `LM100`, at the rate the package master gives it, with no ward tier on it; a claim that still carries the package is refused with `PAYR-1362`. After surgery the surgery items stand and `LM100` is not used.

**The claim** is built from the preauthorisation with `use = claim`, four dates plus discharge status, the discharge summary as a structured document, the bill, the discharge questionnaire response, and the discharge-stage biometric token in the header. Amount within the preauthorisation's approved amount. The documents mandatory at claim are the plan's list less those already sent at preauthorisation.

**Queries** on a claim arrive and are answered the same way as on a preauthorisation, with workflow 161 on `/v1/claim/submit`. The payer refuses 151, 19 and 16 with `PAYR-1321`.

**After the decision**, two Tasks, both on `/v1/task/submit` with workflow 36, code `reprocess`, and a document attached:

|            | Reprocess                     | Shortfall                                                      |
| ---------- | ----------------------------- | -------------------------------------------------------------- |
| When       | Claim rejected outright       | Claim paid, but short                                          |
| Reason     | `claimrejected`               | `partialpayment`                                               |
| Amount     | None                          | The difference, never more                                     |
| Gate       | None; raise on rejection      | Payment notice 33 received, verified, and acknowledged with 17 |
| Times      | Once                          | Once                                                           |
| Decided by | Claim Review Committee, final | Claim Review Committee, final                                  |

They do not chain; a shortfall cannot follow a Committee decision. The claim number in the Task is the preauthorisation number the hospital generated.

## Scheme cases that change the bundle

Five situations the treatment screen has to recognise before it builds anything. The Overview's PMJAY Scheme Rules chapter explains each; this is what the provider system does.

- **Unspecified procedure.** Offer the specialty's unspecified package only within the treating specialty, with a free-text name and amount, and validate the amount on the server. It is a single line item with nothing else beside it. Auth-requirements is still required. Take the code from the plan rather than building it: the FAQ says the specialty prefix plus `215` and a bare `U100`, while the plan carries the specialty prefix plus `U100`, such as `SGU100`.
- **Cyclic procedure.** Ask the cycles, capped by the plan. Take live biometrics at preauthorisation, at every visit with process type Discharge, and at claim. Enforce the 24-hour rolling gap between visits, and record each visit as a numbered structured document with start and end time. One claim goes after the last cycle, and payment comes only for captured cycles. A change of hospital means discharge and a new preauthorisation.
- **Medical package.** One per episode; never alongside a surgical package.
- **Newborn.** Used while the baby has no member ID of its own. Parent's card and wallet, with the parent as primary `Patient` and the child as a linked `Patient` with `link.type = refer`. Date of birth, gender and proof of birth under `DOB` as `BCF` or `DCB` are all mandatory. Twins are two preauthorisations. Bill as "Baby of" the parent with an attachment. A child older than that and under six draws on the parent's wallet as an ordinary case, without the linked-child construct.
- **Implants and stratification.** Separate items with the plan's codes, within the package's maximums; only where the flags allow.

## Payment and communication

The payment flow is the generic one. Two scheme points: the acknowledgement of 33 is the gate on a shortfall claim, and the `TDS` and `Payment` lines on the reconciliation should sum to the approved amount.

The communication channel never carries a document query under PMJAY. It carries `tatquery`, which the handbook reports as the most common reason in live PMJAY traffic, `grievance`, `walletupdate`, `policychange`, and `claimArbitration` when an appeal has been received. Host it regardless.

## Verified in the sandbox

PMJAY Sandbox Run records what the SHA HP sandbox actually did with these rules on 5 and 6 September 2026, from eligibility through to an approved claim. Its findings change what is written above in six places:

- The item needs a FHIR element id, and every supporting-info entry a sequence.
- The practitioner needs an `HPIN` identifier.
- The item's category is the master's specialty code.
- The consent questionnaires that stand in for biometrics are the **plan's**, found by title in the master.
- The claim goes out under the pre-authorisation's number and bills the package alone.
- Documents must be PDF, JPEG, PNG or FHIR JSON. The adjudication APIs, the case id they insist on, and the roles a claim actually walked are in PMJAY Adjudication APIs.

## Going live

The sandbox journey adds a PMJAY team demo to the internal and HTC demos, and the exit form. In production, after the participant is created and configured, the hospital raises a ticket with its HEM ID from TMS and its NHCX participant ID. NHA maps them by hand, and that mapping is the switch. Preauthorisations and claims raised before it finish in TMS; everything after goes through the HMIS. Plan for both running at once, and brief the desk.


---

# PMJAY sandbox run

Everything before this chapter was written from NHA's documents. This one is written from a full case run against the live NHCX sandbox with a State Health Agency (SHA) as the payer: policy lookup, coverage, package master, preauthorisation, adjudication, enhancement, claim and the claim's walk through the payer's roles, to approval. It records what the SHA accepted and refused, in the order a hospital meets it. Where this chapter and an earlier one disagree, this one is the evidence.

Identifiers, amounts and dates from the run are replaced by placeholders. Yours will differ; the rules will not.

## Before you start

- A provider participant on the sandbox, with its certificate and callback URL registered.
- The SHA payer's participant code, and the policy code and member id of a beneficiary it covers, from the policy lookup.
- A session token from the ABDM gateway. The same token is used for the NHCX calls and for the payer service that adjudicates the case.
- One beneficiary per deployment. The scheme allows one live preauthorisation per beneficiary per hospital, so two teams sharing a beneficiary block each other.

## The journey in order

### Find the policy

`/participant/get/policies` by ABHA, member id or mobile. Take the policy code and the `processingid` from the answer. Every later call is addressed to the processing id, and the package master is keyed on this policy code, not on any other the hospital knows of.

### Check coverage

`/v1/coverageeligibility/check` with each purpose: `discovery`, `validation`, `benefits`, `auth-requirements`. Validation returns the coverage period and the wallet; auth-requirements returns what the preauthorisation must carry, including the consent questionnaire when there is no biometric token. The reference coverage bundles pass unchanged.

### Fetch the package master

`/v1/insuranceplan/request` with a plan Task keyed on the beneficiary's own policy code and the provider id. A policy the hospital is not empanelled under is refused with `PAYR-1401`; ask again with the code from step 1. The master is large, over a thousand packages, so store it queryable and read every package attribute from it rather than from code.

### Raise the preauthorisation

`/v1/preauth/submit` on workflow `12`. The acknowledgement comes back on `20`, the decision later on `21`, `23` or `24`, on the request's own correlation id. The bundle passes only with all of the following, each learned from a refusal listed further down:

- A FHIR element `id` on the Claim and on every item, procedure and supporting-info entry.
- The practitioner identified by `HPIN` as well as `HPID`.
- The package code, display and specialty exactly as the master has them, the specialty being the code of the category the master files the package under.
- The ward tier from the master's stratification codes as `item.modifier`, where the package allows one.
- The plan's authentication consent questionnaire answered, when there is no biometric token.
- A `sequence` on every supporting-info entry, numbered from 1 with no gaps.

The SHA prices the package itself: the benefit approved is the master's rate for the tier, whatever amount was asked.

### Adjudicate on the payer service

A PMJAY case is not decided over NHCX. It sits at `request.initiated` until someone acts on it in the SHA's Transaction Management System. In the sandbox that someone is you, through two endpoints of the NHCX Payer Service. Both take the ordinary session token in `bearer_auth`.

First ask who holds the case:

```bash
curl --location --request POST 'https://apisbx.abdm.gov.in/pmjay/sbxhcx/nhcxpayerservice/v1/get/user-role' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "caseid": "<case number>",    "payerid": "<payer code>"  }'
```

[Adjudicator: get the user role for a case in the API reference](/docs/nhcx/v1/api/adjudicator/endpoints/adjudicator-pmjay-sbxhcx-nhcxpayerservice-v1-get-user-role)

```json
{ "currentuserrole": "PPD-Trust", "errormessage": null }
```

`caseid` is the SHA's case id, the digits at the end of its case reference. It is not the hospital's claim number; asked about that, the service answers that no data exists for the case id. The SHA hands the case id out in two places: inside a `PAYR-1238` refusal of a later request, and in its acknowledgement and status answers once a request is accepted. Store it beside the claim number the moment it is seen.

Then act, with the action spelled as the role that holds the case expects:

```bash
curl --location --request POST 'https://apisbeta.nha.gov.in/pmjay/hcx/nhcxpayerservice/wrapper/process/case' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'bearer_auth: Bearer <access token>' \  --data-raw '{    "casenumber": "<case number>",    "action": "Approve",    "receivercode": "<payer code>",    "usecase": "PREAUTH",    "correlationid": "<correlation id>",    "sendercode": "<participant code>",    "memberid": "<member id>",    "remarks": "ok"  }'
```

[Adjudicator: act on a case in the API reference](/docs/nhcx/v1/api/adjudicator/endpoints/adjudicator-pmjay-hcx-nhcxpayerservice-wrapper-process-case)

The roles a case may pass through, and the actions each takes:

- Preauthorisation, `PPD-Trust`: `Approve`, `Reject`, `Query`; `usecase` is `PREAUTH`.
- Claim, first desk, `CEX-Trust`: `Forward`; `usecase` is `CLAIM`.
- Claim, second desk, `CPD-Trust`: `cpdApprove`, `cpdReject`, `Pending`; `usecase` is `CLAIM`.
- Medical Audit Committee: `Approve`, `Reject`, `iQuery`; `usecase` is `Medical Audit Committee`.
- Claim, `ACO-Trust`: `Approve`, `Reject`, `Pending`; `usecase` is `CLAIM`.
- Claim, `SHA-Trust`: `Approve`, `Reject`, `Pending`; `usecase` is `CLAIM`.
- Claim Review Committee: `Approve`, `Reject`, `Pending`; `usecase` is `Claim Review Committee`.

Read the role before every action, use the exact spelling, and mint a new correlation id per call. The decision then comes back over NHCX as the `ClaimResponse` on the request's own thread, so the desk call and the callback are two halves of one step.

### Enhance

`/v1/preauth/submit` on workflow `13` with `x-hcx-use_case: Enhancement`, carrying the approved items and the ones now sought. Three rules:

- The acknowledgement carries no `preAuthRef`. The enhancement is decided on the case its parent opened, so carry the parent's case id onto it; the desk answers only for that case.
- Only one package of type `Conservative` per case. An enhancement on a conservative case adds a `Medical` package, or an add-on the master flags as enhanceable, or is refused with `PAYR-1245`.
- One request at a time on a case. A claim raised while the enhancement is still queued is refused with `PAYR-1322`, and the role lookup still answers `PPD-Trust` because the case has not left the preauthorisation queue.

The SHA may answer `queued` again when asked to approve an enhancement and decide it in its own time, a minute later or several. Report the scheme's pace; do not assert it away.

### Claim

`/v1/claim/submit` on workflow `15`. Beyond the preauthorisation rules:

- Send it under the preauthorisation's own number. A claim under a number of its own finds no case and is refused with `ERR-PYR-CLM-007`. The claim still owns its correlation id, so the answer lands on the right record.
- Bill the package alone, at the whole amount. A PMJAY rate is all-inclusive; room rent, consultations and investigations are not items and are refused as invalid item codes.
- Answer the plan's discharge consent questionnaire when there is no discharge biometric token, or meet `PAYR-1363`.
- Attach documents as `application/pdf`, `application/jpg`, `application/jpeg`, `application/png` or `application/fhir+json`. Anything else, `text/plain` included, is refused with `PAYR-1008`.

### Walk the claim through the roles

Read the role, act, read again. On the run the claim was forwarded by `CEX-Trust`, approved by `CPD-Trust` as `cpdApprove`, then by `ACO-Trust` and `SHA-Trust`, after which the role lookup answered with no role at all: the case was decided and the verdict arrived on the claim's own thread. Neither committee held the case. The seven roles are the ones a case may pass through, not a queue every case walks, and a cycle that assumes the next role in the list will be refused.

Two answers from the desk mean "try again shortly": no event found for the correlation id, while the exchange is still delivering the request, and case not found, while the case is mid-filing. Retry on both.

## Refusals you will meet

Each of these arrived on the run, in roughly this order. The message is the SHA's; the reading is what it turned out to mean.

### PAYR-1027 Invalid item id

The item has no FHIR element `id`. Not a package-code problem: the same bundle was refused with several valid codes until the ids were added. `PAYR-1028`, invalid item sequence, and `PAYR-1029`, invalid bundle id, are the same kind of fault.

### PAYR-1083 No HPR details for the practitioner

The SHA looks the doctor up by the identifier typed `HPIN` from the NRCeS identifier-type code system. Send the HPR id twice, as `HPID` and as `HPIN`, alongside the registration number typed `MD`:

```json
"identifier": [  { "type": { "coding": [{ "system": "https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code", "code": "HPID" }] }, "system": "https://nhcx.abdm.gov.in", "value": "<HPR id>" },  { "type": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "MD" }] }, "system": "https://nhcx.abdm.gov.in", "value": "<registration number>" },  { "type": { "coding": [{ "system": "https://nrces.in/ndhm/fhir/r4/CodeSystem/ndhm-identifier-type-code", "code": "HPIN" }] }, "system": "https://hpr.abdm.gov.in", "value": "<HPR id>" }]
```

The sandbox did not check the id against the registry; a well-formed one was enough. Production may not be as kind.

### PAYR-1238 An active preauthorisation exists

A scheme rule, not a bundle fault, and it arrives after the bundle has passed validation. The refusal names the SHA's case reference; its last digits are the case id the payer service wants. Clear it with a cancel Task on `PC01` from the hospital that raised it, or a `Reject` at `PPD-Trust`.

### PAYR-1256 and PAYR-1363 Consent questionnaire missing

No biometric token and no consent answer. The questionnaire is the plan's: its url and link ids come out of the package master and change per SHA, so read them off the master. The answer rides as a `QuestionnaireResponse` naming that url, referenced from a supporting-info entry of category `INF`, code `ODN`. `PAYR-1256` is at the preauthorisation, `PAYR-1363` at the claim.

### PAYR-1019 Invalid sequence in supporting info

An entry without a `sequence`, typically one appended after the rest were numbered. Number the list after it is complete.

### PAYR-1008 Invalid content type, or invalid code and reason

On an attachment: a content type outside the five the SHA reads. On a Task: a code and reason combination the scheme does not take, see below.

### ERR-PYR-CLM-007 No prior preauthorisation for the case

The claim was sent under a number of its own. Send it under the preauthorisation's number.

### PAYR-1245 Only one conservative procedure per case

The enhancement added a second `Conservative` package. Add a `Medical` package or an enhanceable add-on instead.

### PAYR-1322 Active instance found for the case

A second request while the previous one is still queued. Wait for the decision.

### PAYR-1401 Policy not allowed for the hospital

The package master was asked for under a policy the hospital is not empanelled for. Use the beneficiary's policy code from the eligibility answer.

## What the package master decides

Read every package attribute from the master; none of it belongs in code.

- Package code and display: `item.productOrService`, under the NDHM procedure-code system.
- Specialty: `item.category`, under the NDHM benefit-category system. Its value is the code of the category the master files the package under, exactly as `PAYR-1114` says. A generic category is wrong for every PMJAY package.
- `ProcedureType`: `Claim.procedure.type`, `conservative`, `medical` or `surgical`. Decides the one-conservative-per-case rule.
- `StratificationAllowed` and the tiers: whether a ward tier rides as `item.modifier`, code and display only, no system. A general, semi-private, private or deluxe bed is the routine ward tier, an HDU bed the HDU tier, an ICU bed the ICU tier without ventilator unless the record says otherwise. The tier's rate is what the SHA pays; the amount asked stays the hospital's own.
- `ApprovalNotRequired`: whether a preauthorisation is needed at all.
- `EnhancementAllowed`: whether the package may be added on an enhancement.

The master also says what the claim may carry: the package alone. The generic flow, where every bill line is an item, stays right for an indemnity payer.

## What the sandbox will not take

- A status enquiry as a `Task` coded `status`, refused with `PAYR-1018` without a reason code and `PAYR-1008` with one. Where a case stands is read from the payer service's role lookup, not asked for over NHCX.
- A reprocess `Task` with reason `partialpayment` before payment notice `33` has arrived and been acknowledged, refused the same way. The combination is validated before the case is looked at.

Both refusals cite a document of valid code-and-reason combinations that NHA does not publish with the rest of its material.

## What this changes in the earlier chapters

- Bundles and Conventions: element ids on every Claim bundle, and the `HPIN` identifier on every Practitioner.
- Preauthorisation Request: the sample's `factor: 0.5`, its `MP` category system and the SNOMED system on the package code are tolerated, not needed. `factor` 1, the master's category under the NDHM benefit-category system and the package under the NDHM procedure-code system pass.
- Building a Provider 07: the specialty is the master's category code, the ward tier the master's stratification code, the claim the package alone. The mandatory documents the sample carries were not demanded at submission; expect them to be queried for.
- Error Codes: `PAYR-1027`, `PAYR-1019` and `PAYR-1029` are structural, not code lookups. `PAYR-1008` is about a content type or a code-and-reason combination, depending on where it lands.
- Discharge and Claim: under PMJAY the claim carries the preauthorisation's number, the package alone at the whole amount, the discharge consent questionnaire, and documents in a content type the payer reads.


---

# Preauthorisation

The preauthorisation is the first bundle that carries clinical content, and the one the payer scrutinises hardest. Everything the treatment screen collected becomes a `Claim` resource with `use` set to `preauthorization`.

## What the user does

The form has five sections, and the order below is the order payers read them.

**Medical information.** Findings, history, the clinical picture that justifies admission.

**Admission information.** Registration date, admission date, admission details.

**Treatment.** Diagnosis as ICD-10 codes, the treatment plan as services or packages chosen from the plan, investigations, and the care team with each doctor's registration number.

**Finance.** The amount per line, from the plan where the plan fixes it. The total may not exceed what eligibility said remains; check it on the server before enabling submit.

**Documents.** The checklist comes from the eligibility call with purpose auth-requirements, made from this screen before submission. Each document is one file of at most 2 MB. Do not let the user submit with a mandatory item missing; the payer will query, and the round trip costs a day.

## What the system calls

```text
POST /v1/coverageeligibility/check     purpose: benefits, then auth-requirementsPOST /v1/preauth/submit                workflow 12callback /v1/preauth/on_submit
```

Send to the processor code. Store the correlation ID against the case; every follow-up on this preauthorisation will reuse the reference and carry a new correlation ID.

## What goes in the bundle

A collection bundle. The `Claim` is the spine; everything else is referenced from it by `urn:uuid`.

| Resource                         | Why it is there                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Claim`                          | `use = preauthorization`, `type` inpatient, patient, provider, insurer, coverage, billable period, diagnosis, procedure, items, care team, supporting info, total                                                                                                                                                                                                               |
| `Patient`                        | Member ID and ABHA number as identifiers                                                                                                                                                                                                                                                                                                                                        |
| `Organization` ×2                | Provider with its HFR ID as NPI; insurer with its registry ID as NIIP                                                                                                                                                                                                                                                                                                           |
| `Coverage`                       | The policy, with the product code                                                                                                                                                                                                                                                                                                                                               |
| `Practitioner` per doctor        | Name and medical registration number, referenced from the care team                                                                                                                                                                                                                                                                                                             |
| `Procedure`                      | One per procedure, referenced from `Claim.procedure`                                                                                                                                                                                                                                                                                                                            |
| `DocumentReference` per document | A PDF or image in `attachment.data`, or a structured FHIR bundle where the payer asks for one                                                                                                                                                                                                                                                                                   |
| `QuestionnaireResponse`          | Answers to any questionnaire the plan or the eligibility response attached, referenced from a supporting-info entry. A policy or case-level response uses category `INF` with code `ODN`; the FRD gives `INF` with code `AT` for questionnaire answers generally. The payer names `ODN` in its own rejection message, so send that for the case-level one and confirm the rest. |

The item is where most rejections originate. Each `Claim.item` carries the category, the service or package as `productOrService`, quantity, unit price and net, and points at the diagnosis, procedure, care team and supporting-info entries it relates to by sequence number. The codes and displays must match the plan exactly.

Two supporting-info entries carry the dates: registration date as code `EDT` under category `OTH`, admission date as code `ADDD` under category `ONS`. Full element tables are in the FHIR Reference.

## What the payer checks before a human sees it

The reference payer refuses these on arrival, with a named code, before the case reaches a doctor's queue. Every one of them is cheaper to catch on your own server.

| Check                                                                           | The code you get if you skip it                               |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Every `Claim.item` carries a FHIR element `id`                                  | `PAYR-1027`, "invalid item id". Structural, not a code lookup |
| Every `supportingInfo` entry carries a `sequence`, numbered from 1 with no gaps | `PAYR-1019`                                                   |
| The `Practitioner` carries an identifier typed `HPIN`                           | `PAYR-1083`                                                   |
| No preauthorisation already live for this beneficiary at this hospital          | `PAYR-1238`, which names the reference number holding it      |
| Documents in `pdf`, `jpg`, `jpeg`, `png` or `fhir+json`                         | `PAYR-1008`                                                   |
| The package code is in the plan's master                                        | `PAYR-1248`, which names the code                             |
| The policy is one the hospital is empanelled under                              | `PAYR-1401`                                                   |

Refusals arrive in order: the bundle is validated first, and scheme rules are applied only to a bundle that passed. So `PAYR-1238`, the one-live-preauthorisation rule, is perversely the first sign the bundle itself is right.

The `PAYR-102x` block is structural throughout. When you meet one, check ids and sequences before you go looking at values.

## Reading the answer

The callback carries a `ClaimResponse`. Read two fields together, never one:

| `outcome`  | Adjudication reason | Meaning                                                                             | Workflow |
| ---------- | ------------------- | ----------------------------------------------------------------------------------- | -------- |
| `complete` | `approved`          | Approved. `preAuthRef` is the reference for the claim.                              | 21       |
| `partial`  | `approved`          | Approved at a reduced amount. `processNote` says why.                               | 21       |
| `partial`  | `queried`           | The payer wants more. The case stays open.                                          | 24       |
| `complete` | `cancelled`         | Rejected. Reason in `disposition` and a denial code from the `PreauthError` family. | 23       |

`outcome = complete` alone does not mean approved; it also means rejected. The adjudication reason is the difference.

## When the payer wants more

On the general network, a query arrives as a **communication request** on `/v1/communication/request`, with reason `additionalinfo` and the case number. The provider attaches what was asked and answers on `/v1/communication/on_request`. The payer then issues the decision on `/v1/preauth/on_submit`. The queried `ClaimResponse` with workflow 24 tells the provider the case is waiting; the communication tells it what for.

Some payers instead take the answer on the preauthorisation endpoint itself with workflow 19. PMJAY does; PMJAY Provider covers it.

## Follow-ups on the same case

All reuse this screen's bundle with a new correlation ID, the original reference, and a different workflow code.

**Answering a query** adds one more entry wherever it is sent: the overall case remarks, under category `NMI` with code `CQD`, as a string. Send it. The handbook says an answer without it is rejected. The one sampled answer that the payer accepted and then approved carries no such entry, so treat it as required until a payer tells you otherwise.

- **Enhancement** (13). Against an approved case, for additional procedures or days. The bundle lists the already-approved items and the new ones.
- **Resubmission** (121). Revises a request after a query or rejection.
- **Cancel** (PC01). A Task, not a Claim: code `cancel`, the case number as input, a reason from the list (treatment plan changed, patient request, financial constraints, alternative treatment, duplicate, administrative error, other). Allowed until the claim is raised. Send it on PC01; the payer's answer comes on PC02, as the Workflow Status Sheet gives. Do not use 122, which the handbook mentions: it clashes with R122, the reimbursement claim reprocess.

The Task resource carries more codes than these two. The provider exit checklist names `reprocess`, `cancel`, `release` and `nullify`, and the value set adds `approve`, `search`, `poll` and `suspend`. `nullify` is described in Cancel, Reprocess and Shortfall in the FHIR Reference. `suspend` is not described in any source beyond its place in the value set.

Payers enforce sequencing and say so: no approved record for this enhancement, a case already in progress, a claim already raised. Surface their errors as they are.


---

# Provider checklist

What a provider has to demonstrate to leave the sandbox, the test cases to run before asking, and where the first week's failures come from.

## The sandbox exit list

NHA's provider exit process names thirteen use cases. Each must be shown working against the dummy payer in the internal demo, then in the HTC demo.

1. Get participant list, `/fetch/participants/list`.
2. Get policy, `/participant/get/policies`.
3. Get public key, `/fetch/certs`.
4. Get auth token, `/get/session`.
5. Check coverage eligibility, `/v1/coverageeligibility/check`, answered on `/v1/coverageeligibility/on_check`.
6. Request insurance plan, `/v1/insuranceplan/request`, answered on `/v1/insuranceplan/on_request`.
7. Preauthorisation submission, `/v1/preauth/submit`, answered on `/v1/preauth/on_submit`.
8. Respond to a communication request, received on `/v1/communication/request`, answered on `/v1/communication/on_request`.
9. Claim submission, `/v1/claim/submit`, answered on `/v1/claim/on_submit`.
10. Claim search, `/v1/search/submit`, answered on `/v1/search/on_submit`. A caution: the Technical Specifications route `/search/submit` from NHA through NHCX to the payer, a cross-payer search for NHA or a regulator, and a provider's search over its own cases is `/claim/search` under the access-control policy. No source confirms which of the two the sandbox accepts from a provider.
11. Acknowledge payment notice, received on `/v1/paymentnotice/request`, answered on `/v1/paymentnotice/on_request`.
12. Reprocess or cancel, `/v1/task/submit`, answered on `/v1/task/on_submit`.
13. Get status, `/v1/status`, answered on `/v1/on_status`.

Every callback must accept both a `JWEPayload` and a `ProtocolResponse`, and answer with the 202 receipt within 30 seconds. `/v1/error` is not on the list but is required: it takes a plain JSON report of an undeliverable request and must still be answered `202`.

Under PMJAY, add biometric authentication in all three modes and the structured health-information types, and expect the PMJAY team demo as an extra step.

## Test cases

One id per case, by family: `ML1` beneficiary authentication, `PLN` insurance plan, `ELG` coverage eligibility, `PRE` preauthorisation, `CLM` claim, `PAY` payment, `COM` communication, `CBK` callbacks, `SES` session and keys. Cases marked PMJAY apply to the scheme only. The workflow codes named are the ones each leg must carry; the dummy payer's `process/request` hook drives approve, reject and query on demand, and `paymentNotice/init` drives a payment notice. The full list of NHA's own numbered scenarios is in NHCX Use Cases and the harness bundles in `fixtures/reference/payer/`.

### Beneficiary authentication

#### T-ML1-01 Validate the policy by ABHA

`CoverageEligibilityRequest` with purpose `validation` for a valid ABHA with consent. Expect a `CoverageEligibilityResponse` with `inforce: true`.

#### T-ML1-02 Biometric authentication in each mode (PMJAY)

Fingerprint, iris and face, each yielding a user token that rides on the eligibility check and the preauthorisation.

#### T-ML1-03 Consent fallback (PMJAY)

No biometric device: the plan's authentication consent questionnaire is answered instead, at admission and again at discharge.

#### T-ML1-04 Token refresh and expiry (PMJAY)

A user token refreshed before the preauthorisation; an expired one refused and re-obtained.

### Insurance plan

#### T-PLN-01 Fetch the package master

`InsurancePlan` request keyed on the beneficiary's own policy code and the provider id. Expect the master with packages, inclusions, exclusions, claim conditions and document requirements. A policy the hospital is not empanelled under is refused with `PAYR-1401`.

### Coverage eligibility

#### T-ELG-01 Auth-requirements before a preauthorisation

Purpose `auth-requirements` for a package. Expect eligible, balance sufficient, and the mandatory documents the preauthorisation must carry.

#### T-ELG-02 Benefits and discovery

Purpose `benefits` for a package, and `discovery` with no policy to find what the beneficiary holds.

#### T-ELG-03 Refusals

A policy not in force; a limit exhausted. The refusal is read off the response, not off a transport error.

### Preauthorisation

#### T-PRE-01 Submitted and approved

Workflow `12`, acknowledged on `20`, approved on `21`. The payer's case number arrives in `preAuthRef`.

#### T-PRE-02 Queried, answered and approved

Workflow `12`, `20`, `24`, `19`, `21`. The query on the case thread under PMJAY or over communication with another payer, then a positive adjudication.

#### T-PRE-03 Rejected, resubmitted, cancelled

Workflow `12`, `23`, `121`, `PC01`, `PC02`. The rejection carries `preAuthRef`; the resubmission reuses it; the cancel Task withdraws the case.

#### T-PRE-04 Enhancement queried, answered and approved

Workflow `13`, `241`, `131`, `22`, with the header `x-hcx-use_case: Enhancement`. A longer stay or an added package on the same case.

#### T-PRE-05 Implant, stratification and STG (PMJAY)

A package with an implant line, a ward tier as `item.modifier`, and the STG questionnaire answered under `supportingInfo`.

#### T-PRE-06 Auto-approval (PMJAY)

A first preauthorisation on a case whose packages all allow it comes back approved without a desk action.

### Claim

#### T-CLM-01 Approved

Workflow `15`, acknowledged on `25`, approved on `26`, after an approved preauthorisation, with the discharge biometric token or consent.

#### T-CLM-02 Queried, answered and approved

Workflow `15`, `25`, `27`, `151`, `26`. Under PMJAY the answer goes on `161`. The documents asked for ride in `supportingInfo`.

#### T-CLM-03 Rejected and reprocessed

Workflow `15`, `291`, then a reprocess Task on `36` with the justification attached, acknowledged on `37`, decided on `252` or `253`.

#### T-CLM-04 Discharge in every mode (PMJAY)

`DTH`, `DTM`, `LAMA` and `DAMA`, with the amount each one allows: `LM100` per day for LAMA or DAMA before or during surgery, the full package after surgery, and the death date under `ONS/DTM` for `DTM`.

#### T-CLM-05 Shortfall after partial payment (PMJAY)

A Task with reason `partialpayment` after payment notice `33` is acknowledged; refused before it.

#### T-CLM-06 Unusual cases (PMJAY)

An unspecified procedure `SGU100`; a cyclic procedure across several visits; a newborn on the parent's card; twins.

#### T-CLM-07 Provisional discharge

Where the payer supports it: submitted on `14`, then approved, rejected and queried.

### Payment

#### T-PAY-01 Payment notices acknowledged

Notices on `30`, `31` and `33`, each acknowledged on `17` under PMJAY or with the notice's own code on the generic network. The UTR on `33` is stored.

### Communication

#### T-COM-01 A communication of each reason

`additionalinfo`, `tatquery`, `grievance`, `walletupdate`, `policychange`, `claimArbitration`, each acknowledged within thirty seconds without touching the case status.

### Callbacks

#### T-CBK-01 The same callback twice

The second delivery is recognised by `x-hcx-api_call_id` and answered `202` without acting twice.

#### T-CBK-02 Unknown correlation id

A callback for a thread this system never opened is answered `202` and logged, not processed.

#### T-CBK-03 A protocol response

A `ProtocolResponse` body, with its `x-hcx-error_details`, handled without attempting to decrypt.

#### T-CBK-04 The error endpoint

A report on `/v1/error` answered `202` and surfaced to the desk as a failed delivery, not a case under review.

### Session and keys

#### T-SES-01 Token expiry mid-flow

A `401` on any call leads to a fresh session token and one retry, never a retry with the same token.

#### T-SES-02 Certificate rotation on the payer side

A decrypt failure on the payer's side clears the cached certificate and fetches it again before resending.

## PMJAY HMIS test cases

The NHCX-PMJAY-HMIS test case workbook carries eight worked cases for a hospital system integrating PMJAY through NHCX. They are reproduced here as published.

| Id           | Scenario                                   | Precondition                     | API or resource                                           | Inputs                                                                | Validation                                               | Expected output                                                                                                    | Remark                     |
| ------------ | ------------------------------------------ | -------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| `TC-ABHA-01` | Validate the PMJAY policy using ABHA       | Valid ABHA, consent available    | `CoverageEligibilityRequest`, purpose `validation`        | ABHA `91-XXXX-XXXX-XXXX`, purpose `validation`                        | ABHA linkage and an active policy                        | `CoverageEligibilityResponse` with active coverage                                                                 | Happy path                 |
| `TC-HBP-01`  | Fetch the admissible HBP package           | Policy validated                 | `InsurancePlan`                                           | Plan id `PMJAY-TS-001`, provider id `HOSP123`, payer id `SHA-HARYANA` | Provider validated against the state's network hospitals | `InsurancePlan` with all HBP packages, their inclusions and exclusions, claim conditions and document requirements | State-specific HBP applied |
| `TC-CE-01`   | Coverage eligibility for auth-requirements | Wallet available                 | `CoverageEligibilityRequest`, purpose `auth-requirements` | Amount `25000`, package `HBP-123`                                     | Wallet balance and specialty rules                       | Eligible, balance sufficient                                                                                       | Preauth allowed            |
| `TC-PA-01`   | Submit a preauthorisation                  | Eligibility successful           | `/v1/preauth/submit`, `Claim`                             | Diagnosis `I10`, treatment plan, supporting documents, doctor details | Clinical and financial rules                             | Preauth id generated, status `PENDING`                                                                             | Sent to workflow           |
| `TC-PA-02`   | Submit a preauthorisation query update     | Preauthorisation submitted       | `/v1/preauth/submit`, `Claim`                             | Additional documents                                                  | Preauthorisation and treatment details match             | Query details accepted for adjudication                                                                            | Sent to workflow           |
| `TC-CL-01`   | Submit the claim after discharge           | Preauthorisation approved        | `/v1/claim/submit`, `Claim`                               | Approved amount `23000`, documents attached                           | Preauthorisation and treatment details match             | Claim accepted for adjudication                                                                                    | Sent to workflow           |
| `TC-CL-02`   | Submit a claim query update                | Claim submitted                  | `/v1/claim/submit`, `Claim`                               | Documents                                                             | Claim and treatment details match                        | Query details accepted for adjudication                                                                            | Sent to workflow           |
| `TC-CL-03`   | Submit a CRC claim                         | Claim rejected or partially paid | `/v1/task/submit`, `Task`                                 | Not given                                                             | Claim and treatment details match                        | Not given                                                                                                          | Not given                  |

`TC-CL-03` is incomplete in the workbook: it gives no inputs, expected output or remark. Both query updates go to the same endpoint as the first submission; the workflow code tells them apart, as PMJAY Provider sets out.

### The scenario list

The workbook's second sheet is a bare list of nineteen scenario names, with no steps, inputs or amounts. Many of them have no worked case above.

| No. | Scenario                                                            |
| --- | ------------------------------------------------------------------- |
| 1   | Registration                                                        |
| 2   | Wallet update                                                       |
| 3   | Registration cancel                                                 |
| 4   | Preauthorisation submission                                         |
| 5   | Preauthorisation query                                              |
| 6   | Preauthorisation submitted with the query response                  |
| 7   | Preauthorisation enhancement                                        |
| 8   | Preauthorisation with implant                                       |
| 9   | Preauthorisation resubmission                                       |
| 10  | Preauthorisation rejection                                          |
| 11  | Preauthorisation approval                                           |
| 12  | Preauthorisation cancel or delete                                   |
| 13  | Discharge in multiple modes, and the amount calculation for each    |
| 14  | Claim submission                                                    |
| 15  | Claim query                                                         |
| 16  | Claim rejection                                                     |
| 17  | Claim approval                                                      |
| 18  | Claim final paid, and update at the payer's bank transaction detail |
| 19  | CRC in case of claim rejection and partial payment                  |

The workbook does not give the amounts for scenario 13. The discharge modes and what each one allows are in T-CLM-04 above.

## Where the first week goes wrong

Roughly in the order the portal's own support list has them:

1. Wrong status word on a leg of the message.
2. No `/v1/error` endpoint.
3. Callback answering with something other than 202 and the receipt.
4. Envelope headers missing or malformed.
5. Registry id inside the bundle not matching the participant record.
6. `Accept: application/json` missing.
7. Sending to `payerid` instead of `processingid`.
8. Reusing a correlation id after an error.
9. Retrying a `401` with the same token.
10. Package code or display not matching the plan, character for character.

## Exchanges this documentation does not cover

The workflow sheet defines families that no NHA document describes beyond their codes. A participant may receive one; log it and escalate rather than ignore it.

- Final bill: `45` submitted, `46` approved, `47` queried, `181` query answered, `491` denied.
- Reimbursement claims: `R15`, `R151`, `R26`, `R27`, `R28`, `R291`, `R122`, `R252` to `R254`.
- Discharge correction: `DC01`, `DC02`.
- Preauthorisation arbitration: `41`, `42`.
- Wallet upgrade `34`, `35`; fraud alert `38`, `39`; grievance `G11`, `G12`, `G13`.
- `16`, for a preauthorisation resubmission.

## Before going live

- FHIR bundles emailed for NRCeS validation and passed.
- Internal demo with NHA, then the HTC demo.
- Production participant created through the passcode flow; certificate and callback URL registered; own certificate fetched back and checked.
- Under PMJAY, the HEM-to-participant mapping ticket raised, and staff briefed that in-flight TMS cases finish in TMS; see PMJAY Provider.
- A pilot on a few real cases before switching the whole hospital.


---

# Registration and eligibility

This chapter comes before the Insurance Plan chapter because registration comes first at the desk. The calls do not run in that order. The plan is fetched at registration or admission and cached, so by the time a treatment is planned it is already there, and the next chapter covers it. Read the two together.

The first screen decides whether the rest of the journey can happen. A patient who is registered without a confirmed policy and a confirmed processor code will fail at preauthorisation with errors that look like FHIR problems and are not.

## What the user does

**Search.** The front desk enters one identifier: ABHA number, member or policy number, or mobile. The system tries them in that order of strength and shows the matching policies with the insurer's name. The user picks the payer.

**Beneficiary Verification & KYC.** Before checking eligibility, the patient's identity is established:

- **Commercial / Private Insurance**: Uses the **Aadhaar Digital eKYC API**. The desk triggers an Aadhaar OTP or demographic validation, retrieving the beneficiary's verified ABHA profile (Name, DOB, Gender, Address, Photo) and unhyphenated ABHA ID for the envelope (`x-hcx-ben-abha-id`).
- **PMJAY Scheme**: Gated by **Mandatory Biometric Authentication**. The patient performs a live biometric verification (Fingerprint, Iris, or FaceAuth) via the ABDM biometric gateway (see Biometric Authentication), returning a user auth token (valid 1,800s). If the patient cannot be biometrically authenticated due to physical trauma, burns, or amputation, the hospital executes the signed **Aadhaar Exemption Consent Form** and submits the Authentication Consent Questionnaire.

**Confirm cover.** The screen calls eligibility with purpose validation and shows the result in words the desk can act on: policy in force or not, and what remains against the sum insured. Register the patient only once this comes back positive. If the limit is exhausted or the policy is not in force, say so and stop; do not let a registration proceed on a promise.

**Capture the rest.** Communication address, attendant details, and whatever the payer's plan lists as required at registration.

## What the system calls

```mermaid
sequenceDiagram
  box Provider side
    participant D as Front desk
    participant B as Provider backend
  end
  box Exchange
    participant X as NHCX
  end
  box Payer side
    participant Y as Payer
  end
  D->>B: identifier typed at the desk
  B->>X: participant/get/policies
  X-->>B: payerid, processingid, memberid, productid
  D->>B: user picks the policy
  B->>X: coverageeligibility/check, purpose validation
  X-->>B: 202 receipt, not the answer
  X->>Y: forwards
  Y->>X: coverageeligibility/on_check
  X->>B: sealed CoverageEligibilityResponse
  B-->>D: in force, balance remaining
  D->>B: register the patient
```

Two lookups from Getting Started, then one exchange:

```text
POST participant/get/policies          identifiertype + identifiervaluePOST /v1/coverageeligibility/check     purpose: validation
```

The eligibility request needs the beneficiary's identifiers, the coverage or plan code, the payer ID and the provider ID. Send it to the processor code from the policy lookup. Cache the policy result against the patient.

Call eligibility again, still with purpose validation, whenever a treatment is added later. The handbook's fallback: if the policy lookup returns nothing, call eligibility with purpose discovery first to learn the active policy code, then validation with it.

## The four purposes

One `CoverageEligibilityRequest` carries four different questions, and `purpose` decides which. Only `validation` is asked at the desk; the other three belong to the treatment screen in the next chapter.

| Purpose             | The question                                              | When you send it                                            | What comes back                                                                       |
| ------------------- | --------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `validation`        | Is this coverage in force, and what is left?              | At registration, and again whenever a treatment is added    | `inforce`, and one benefit entry per wallet with allowed and used money               |
| `discovery`         | What coverages does this beneficiary have with you?       | Only as a fallback, when the policy lookup returned nothing | Every active coverage, so you can pick a policy code                                  |
| `benefits`          | For these packages, what is covered?                      | On the treatment screen, once packages are chosen           | Per item: excluded or not, benefit type, allowed money                                |
| `auth-requirements` | Is preauthorisation required, and what must come with it? | Before submitting a preauthorisation                        | Per item: `authorizationRequired`, and the mandatory document and questionnaire codes |

`discovery` is defined in the specification and appears in no published sample. The other three do.

## What goes in the bundle

A `CoverageEligibilityRequest` in a collection bundle, alongside the `Patient`, the provider and insurer `Organization`s, the `Coverage`, and the `PractitionerRole` of the desk user who made the check.

| Element               | Set it to                                                                                                                                                                                                                                                                          |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `purpose`             | `validation` at registration; `discovery` as the fallback                                                                                                                                                                                                                          |
| `patient`             | Reference to the Patient, who carries the member ID and ABHA number as identifiers                                                                                                                                                                                                 |
| `insurer`, `provider` | References to the two Organizations                                                                                                                                                                                                                                                |
| `insurance.coverage`  | Reference to the Coverage carrying the policy code                                                                                                                                                                                                                                 |
| `servicedDate`        | Today                                                                                                                                                                                                                                                                              |
| `enterer`             | The desk user, as a `PractitionerRole` entry, which is what the handbook asks for and what the reference bundles carry. NHA's older sample bundles reference a bare `Practitioner`; FHIR allows either, but send the `PractitionerRole` so every page of this documentation agrees |

Element tables and a worked example are in the FHIR Reference. Two details from the samples save a day each. The `Patient` carries a `PI` identifier that is the hospital's own MRN, and a hospital with none yet sends the literal string `NA`. And `servicedDate` is the date of service, not the date of asking.

## Reading the answer

The response comes back on `/v1/coverageeligibility/on_check`. It is not a small message: the payer echoes your entire request back before answering it, so the bundle has eleven entries where you sent six.

| What you want                         | Where it is                                               |
| ------------------------------------- | --------------------------------------------------------- |
| The yes or no                         | `insurance[0].inforce`                                    |
| The payer's own sentence for the desk | `disposition`, for example `Policy is currently in-force` |
| Money allowed on the wallet           | `insurance[0].item[].benefit[].allowedMoney`              |
| Money already used                    | `insurance[0].item[].benefit[].usedMoney`                 |
| Whether preauthorisation is needed    | `item.authorizationRequired`                              |
| The match back to your request        | `CoverageEligibilityResponse.request.reference`           |

Three traps in that bundle, all of them real in the published sample.

**Index by `fullUrl`, not by resource type.** Entries 8 to 11 are the payer's own `Patient`, `Coverage` and `Organization`s, and they duplicate the resource types in your echoed request. A parser that finds the first `Patient` reads your own data back and reports it as the payer's answer.

**Do not match on the request id.** The payer splits `CoverageEligibilityRequest.id` on the last slash and returns only the tail, so an id you sent as `PMJAY/HP/S/G` comes back as `G`. Match on `request.reference`, which is intact.

**The balance is a subtraction.** `allowedMoney` alone reads as more cover than the patient has. Show allowed less used, and group the digits the Indian way.

## The forward instruction

The coverage eligibility specification gives it one sentence: a payer might respond with a forward instruction asking NHCX to submit the same request to another payer. No fields or flow are published for it, so there is nothing to build against. Ask about it at onboarding; Governance and Audit lists the question.

## Errors you will meet

Business refusals travel inside the sealed response as a `PAYR-` code; protocol refusals arrive on the envelope. Map each to something the desk can act on.

| Code                     | What it means                                          | What the desk should see                                                                                      |
| ------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `PAYR-1401`              | Policy not allowed for the hospital                    | The hospital is not empanelled under that policy. Ask again with the beneficiary's own policy from the lookup |
| `PAYR-10xx` family       | Not a covered member, policy not found, policy expired | The payer's own sentence, verbatim, and a stop on registration                                                |
| `PAYR-11xx` family       | The reference payer's eligibility-specific set         | The payer's sentence, plus which field it names                                                               |
| `401` on the call itself | Token expired                                          | Nothing. Fetch a new token and retry once                                                                     |

A refusal on this exchange is cheap. The same fault met at preauthorisation costs a round trip and a day, which is the argument for calling eligibility again whenever a treatment is added rather than trusting the answer from admission.

## What to show and store

- Show `disposition` verbatim; it is the payer's own sentence about the policy.
- Store the response with the case, because the auth-requirements version of this same call is what tells you which documents are mandatory later.
- Store the wallet figures and the moment they were read. When a claim is adjudicated against them months later, the adjudicator needs to see what was promised.
- Store the raw sealed message before you interpret it. Disputes are settled on what was actually received.
- Map the payer's error codes to desk-readable messages: not a covered member, policy not found, policy expired. The `PAYR-10xx` family covers these; the reference payer adds a `PAYR-11xx` set for eligibility specifically.


---

# Provider UI guide

This chapter is about the screens. Everything before it said what the provider system calls and what goes in the bundle. This says what the person at the desk sees, what they type, what they must not be allowed to type, and where each piece of data on the screen comes from. It is written for the product owner and the front-end engineer, and it is organised as seven flows across the same ground the rest of the section covers.

Two rules run through every screen.

**Nothing the exchange already knows is typed.** Payer names, policy numbers, package names, rates, add-on codes, document lists and questionnaire text all come from elsewhere. From the participant service, the policy lookup, the insurance plan or the eligibility response. A field the user can edit is a field the payer can reject.

**The screen never shows a decision the exchange has not sent.** Submitting is not approval. Every status on every screen is derived from a callback that was received, decrypted and stored, never from the fact that a request went out.

That rule has a consequence which is easy to miss. A case the payer has not answered yet exists nowhere in the callback inbox, because nothing has come back. So a system that builds its case list only from received callbacks cannot show a waiting case. The case vanishes between submission and answer, which is the one moment the user most needs to see it. **Keep a record of what you sent as well as what came back.** Store, per request, the action, the protected header, the bundle and the exchange's receipt. Build every case screen from the two halves together. Sent with nothing back is the waiting state, and it is a state you have to be able to render.

A case is keyed by its correlation ID, which the provider generates and which stays fixed for the whole conversation, so it is the only identifier available at the moment of submission. The payer's own case or preauthorisation number arrives later, on the answer. Show the payer's number to the user, since that is the number they will quote on the phone, but address the case internally by the correlation ID. Screen addresses are yours to choose; the chapter does not prescribe them.

## Where the data comes from

```mermaid
flowchart LR
  PS[Participant service] --> PL[Payer list]
  PS --> PO[Policy lookup]
  PL --> UI[Screens]
  PO --> UI
  IP[Insurance plan cache] --> UI
  EL[Eligibility response] --> UI
  CB[Callback inbox] --> UI
  UI --> BE[Provider backend]
  BE --> X((NHCX))
  X --> BE
```

| On screen                                        | Comes from                                            | Editable                        |
| ------------------------------------------------ | ----------------------------------------------------- | ------------------------------- |
| Payer name                                       | Participant list, filtered by role                    | Pick from list                  |
| Policy, member ID, product                       | Policy lookup                                         | Pick from list                  |
| Cover in force, balance remaining                | Eligibility response, purpose validation              | No                              |
| Approved amount, reduction note                  | Claim response on the answer                          | No                              |
| Specialty, package, rate                         | Insurance plan                                        | Pick from list; rate fixed      |
| Add-ons allowed and their limits                 | Insurance plan flags                                  | Pick within limits              |
| Required documents, questionnaires               | Eligibility response, purpose auth-requirements; plan | No; answer, do not edit         |
| Case status                                      | What was sent, plus the callback inbox                | No                              |
| Payer's query text, decision, reason             | Callback inbox                                        | No                              |
| UTR, deductions, net paid                        | Payment notice callback                               | No                              |
| Clinical findings, history, diagnosis, care team | The HMIS record                                       | Yes, in the HMIS                |
| Bill number, date, amount claimed                | Hospital billing                                      | Yes, within the approved amount |

## Find the patient and register

```mermaid
sequenceDiagram
  participant U as Desk user
  participant S as Screen
  participant B as Backend
  participant X as NHCX
  participant Y as Payer
  U->>S: enter ABHA number
  S->>B: find policies
  B->>X: participant list, policy lookup
  X-->>B: policies with insurer and processor
  B-->>S: list, insurer names
  U->>S: pick policy
  S->>B: confirm cover
  B->>X: eligibility, purpose validation
  X-->>B: 202 receipt
  Note over S: shows "checking cover", not a result
  X->>B: callback, sealed response
  B-->>S: in force, balance remaining
  U->>S: register
```

**Screen.** One search box with a type selector: ABHA number, member ID, mobile. A results list showing the insurer name for each policy found. A confirm-cover panel that fills after the user picks a policy: in force or not, balance remaining, and the payer's own sentence about the policy shown verbatim. A register button that is disabled until cover is confirmed.

**What the UI enforces.** Try identifiers in order of strength and tell the user which one matched. The balance remaining is the allowed amount less the amount already used, both of which the eligibility answer carries as money values on the benefit. Show that subtraction, not the allowed amount on its own: the allowed amount alone reads as more cover than the patient has. Group digits the Indian way, so four hundred and fifty thousand reads as 4,50,000, and give the figure a word beside it rather than a bare number. Disable registration when the policy is not in force or the limit is exhausted, and say why in the payer's words.

**What the backend does behind it.** Resolves the processor code from the policy and stores it against the admission. The screen never shows the difference between insurer and processor, but every later call depends on it.

**States the screen shows.** Searching, policies found, checking cover, cover confirmed, cover refused, registered.

## Plan the treatment

```mermaid
flowchart TD
  A[Pick specialty from plan] --> B[Pick package, rate locks]
  B --> F{Flags on the package}
  F -- implant allowed --> I[Implant picker, capped]
  F -- stratification allowed --> R[Bed category picker, capped]
  F -- standalone --> S[Clear other selections]
  F -- unspecified --> U[Free-text name and amount]
  B --> E[Eligibility: benefits, then auth-requirements]
  E --> D[Document checklist and questionnaires]
  D --> T{Total within balance?}
  T -- yes --> P[Continue to preauthorisation]
  T -- no --> N[Blocked, show the shortfall]
```

**Screen.** A specialty picker limited to what the plan says this hospital may use, read from the cached insurance plan. A package picker under it, with the rate shown and locked. Add-on controls that appear only when the package's flags allow them, each capped at the plan's maximum. A live total against the balance remaining, turning red when it would exceed it. A document checklist and questionnaire panel that populate once the packages are chosen.

**What the UI enforces.** Rate not editable. Quantity capped. A standalone package clears any other selection and says so. A package flagged as needing a parent will not stay selected without one. A government-reserved package is not shown to a private hospital. When the total exceeds the balance, the submit path is closed, not merely warned.

**What the backend does behind it.** Reads the cached plan and derives the document checklist and questionnaires from the selected packages. Calls eligibility with purpose benefits to confirm the balance. Refreshes the plan if a policy-change communication has arrived since the cache was filled.

Everything this screen offers comes from the insurance plan. The specialties, the packages, the rates, the add-on allowances, the flags that govern them, the documents each package demands and the questionnaires attached to it are all in the plan. Fetch it and cache it as the Insurance Plan chapter describes.

The auth-requirements exchange is specified to return the required documents, and the rest of this section says so. The one published sample does not: it carries no benefit detail and no supporting-information requirements, and is indistinguishable from the plain benefits answer. So build the checklist from the plan, which certainly carries the requirements, and use the auth-requirements answer to confirm that authorisation is needed and to add anything it does return. A screen that depends on that answer alone will be empty against the only payer whose response has been published.

## Preauthorisation, query, enhancement, cancel

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Submitted: submit
  Submitted --> UnderReview: receipt, then payer ack
  UnderReview --> Approved: approved
  UnderReview --> Reduced: approved at lower amount
  UnderReview --> Queried: query
  UnderReview --> Rejected: rejected
  Queried --> Answered: reply sent
  Answered --> UnderReview
  Approved --> EnhancementPending: enhancement sent
  EnhancementPending --> Approved: enhancement decided
  Approved --> Cancelled: cancel confirmed
  Rejected --> Resubmitted: resubmit
  Resubmitted --> UnderReview
```

**Screen.** Four tabs in the payer's own order: medical information, admission information, treatment, finance. A documents panel driven by the checklist from flow 2, with each mandatory item shown as missing until attached and the submit button disabled until none are. After submission, a case panel with one status line and a timeline of everything sent and received.

**What the UI enforces.** Every mandatory document attached. Every questionnaire the plan demands answered. Registration and admission dates present. Total within balance. Under PMJAY, a biometric token or a consent response, and admission not more than one day ahead.

**The query inbox.** A queried case shows the payer's text, with the item it concerns highlighted, and a reply form that attaches documents and carries the case remarks. Reply goes out as a query answer, never as a new preauthorisation; the screen should make that impossible to confuse.

**Enhancement.** Opens only on an approved case with no request in flight, offers only packages the plan marks enhanceable, and shows the already-approved items greyed alongside the new ones.

**Cancel.** A reason picker with the seven documented reasons and a free-text field that is required when the reason is Other. Hidden once a claim has been raised.

What each state shows the user: Submitted means "sent, no word yet", not approval. UnderReview appears only when the payer's receipt has come back. Approved shows the preauthorisation reference, the approved amount, and any reduction note verbatim.

Three fields on the answer are worth naming, because the response carries several amounts and picking the wrong one misstates the decision. The **approved amount** for the case as a whole is the benefit total on the response, and the same category per line gives the approved amount for each item. The submitted category alongside it is what you asked for, not what you were granted. Showing it as the decision is the classic error. The **preauthorisation reference** is the payer's own number for the case. The **reduction note**, and any other sentence the adjudicator wrote, arrives as process notes and is shown verbatim. The Preauthorisation Response chapter in the FHIR Reference gives the full shape.

## Discharge and claim

```mermaid
sequenceDiagram
  participant U as Billing user
  participant S as Screen
  participant B as Backend
  participant X as NHCX
  U->>S: discharge type, dates, documents
  U->>S: bill and amount
  S->>S: amount within approved? documents complete?
  S->>B: submit claim
  B->>X: claim, workflow 15
  X-->>B: 202 receipt
  Note over S: "submitted", awaiting decision
  X->>B: interim callbacks, in process
  B-->>S: "in process at payer"
  X->>B: final callback
  B-->>S: approved amount, or query, or rejection with reason
```

**Screen.** A discharge form: type (home, death, left against advice, discharged against advice), dates, and the documents that type requires. Then the claim form: bill number, date, bill attachment, amount claimed with the approved amount shown beside it, post-operative evidence. A single submit for the claim; under PMJAY the discharge is not a separate submission.

**What the UI enforces.** Amount claimed not above the approved amount. Discharge type chosen before the claim opens. Under PMJAY: a fresh biometric or the discharge consent; for a LAMA or DAMA leaving before surgery, the line items replaced by the stay line with the user told the approved packages are voided.

**States.** Draft, submitted, in process, forwarded, queried, approved, reduced, rejected. Rejected is final; the only action offered is appeal.

## Appeal a decision

**Screen.** From a rejected or short-paid case, one appeal form: the payer's reason shown at the top, a document attachment that is required, and for a shortfall an amount field capped at the difference. A notice of how many appeals remain, and, once the Committee has decided, a closed state with the decision.

**What the UI enforces.** No appeal without a document. Shortfall amount never above the difference. Under PMJAY, the shortfall form stays disabled until the settlement notice has arrived and been acknowledged, and neither form reopens after a Committee decision.

## Payments

**Screen.** Per case, a payment panel listing each notice as it arrives, and on settlement the UTR as text on the page, gross, deductions itemised, and net. Reconciliation staff copy the UTR, so a copy control beside it earns its place. The value still has to be readable without one: a UTR that exists only inside the `value` attribute of an input box is not on the screen. The same goes for every other figure the payer sent. An acknowledge button per notice. A reconciliation view across cases for accounts, filterable by date and payer, exportable.

**What the UI enforces.** There are two different acknowledgements here and the screen should not confuse them. The 202 receipt your callback returns is a transport acknowledgement, sent automatically the moment the notice arrives. Separately, the provider sends a real acknowledgement message back to the payer, a Task on workflow 17, and the Payment and Communication chapter gives its shape. That one is a business act, so it belongs on the screen: one button per notice, and a clear indication once it has gone. Send it whether or not the user clicks, and show that it went. A rejected payment notice shows as not paid, in red, with the case kept open.

## The case list and the inbox

```mermaid
flowchart LR
  CB[Callback inbox] --> M{Message type}
  M -- decision on a case --> CL[Case list: update state]
  M -- query --> Q[Query inbox]
  M -- communication --> R{Reason}
  R -- information --> Q
  R -- TAT alert --> D[Claims desk]
  R -- grievance --> G[Grievance desk]
  R -- wallet or policy change --> P[Refresh plan or balance]
  R -- arbitration ack --> A[Appeals view]
  M -- payment notice --> PAY[Payments panel]
  M -- protocol response --> E[Error view with the payer's code]
```

**Screen.** Every case in one list with its current state and the time of the last callback, sortable by what needs action: queries waiting for an answer, turnaround alerts, payment notices unacknowledged. A separate inbox for payer communications by reason: information requests, turnaround alerts, grievances, wallet changes, policy changes, arbitration acknowledgements, each routed to the desk that owns it.

**What the UI enforces.** Nothing on this screen is entered. It is a view over what was sent and what came back, and it is honest about silence. A case with no answer for longer than expected shows as waiting, with how long it has been waiting, and never as any decision. Do not offer a refresh or chase button unless you have implemented the status exchange behind it, because a control that does nothing is worse than no control.

## Two things that will break a naive screen

**A delivery failure arriving on a case that already has an answer.** A report on the error endpoint, or a protocol response saying a message could not be opened, is about one message. It is not about the case. A screen that simply shows the most recent thing that arrived will turn an approved preauthorisation into an error, which is wrong and alarming. Show the failure as a flag beside the state, not as the state.

**The same answer delivered twice.** The exchange retries, so a callback can arrive more than once with the same call ID. A timeline built by appending everything received will show the payer approving the case twice. Treat a repeated call ID as the message you already have, and if the timeline mentions it at all, mention it as a repeat.

## Errors the user should see

Show the payer's error as the payer wrote it, with the code, and add one line saying what the user can do. The reference payer's messages already name the field: "Invalid procedure code received as X", "Insufficient wallet balance", "Existing case in progress for case number Y". Do not translate them into a generic failure. A protocol response, meaning the message could not be opened, is a system problem and goes to the integration team, not to the desk.


---

# NHCX support

Write to the team that owns the problem. A question sent to the wrong address waits in the wrong queue.

| For                                                                                            | Write to                                                                                               |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| NHCX integration, onboarding, participant records, certificates and failing calls              | `hcx.integration@nha.gov.in`                                                                           |
| FHIR bundle validation at sandbox exit, and the internal and Health Tech Committee (HTC) demos | `hcx.integration@nha.gov.in`                                                                           |
| Building a FHIR bundle, and the NRCeS profiles                                                 | `nrc-help@cdac.in`                                                                                     |
| ABDM Milestone 1 integration and sandbox credentials                                           | `integration.support@nha.gov.in`, or the [sandbox support portal](https://sandboxsupport.abdm.gov.in/) |
| Facility registration in the Health Facility Registry (HFR)                                    | `facility@nha.gov.in`                                                                                  |

Replies have no fixed turnaround time.

## Before you write

Most failures have a known cause. Check these first:

- [Troubleshooting](/docs/nhcx/v1/troubleshooting): what to do when something breaks, by symptom.
- [Troubleshooting by layer and code](/docs/nhcx/v1/reference/troubleshooting): every layer of a call, and what each error code means there.
- [Error codes](/docs/nhcx/v1/reference/error-codes): every code with its message.

## What to put in the message

A report without these cannot be traced:

- Your participant code and the recipient's.
- The environment, the use case and the path you called.
- The `x-hcx-correlation_id`, `x-hcx-api_call_id` and `x-hcx-timestamp` of the failing message.
- The workflow code and the status you sent.
- The raw sealed message as sent, and the raw response as received.
- The error code and message exactly as returned.

Never send a token, a client secret or a private key.


---

# Accepted with 202, and no callback arrives

Your call returned `202` and no answer has come. The `202` only means the exchange accepted the request. The answer travels three more legs, and any of them can stop it, so find which one.

## In short

- Check `/v1/error` first. An undeliverable request is reported there.
- Then check that the exchange can reach your endpoint, and that you answer `202` in time.
- A status check with the request's API call ID says where the request stands.
- Never resubmit on the same correlation ID. Start a new cycle.

## Prerequisites

- You have the request's `x-hcx-api_call_id`, `x-hcx-correlation_id` and `x-hcx-timestamp`.
- You host `/v1/error`, where the exchange reports a request it cannot deliver.

## Work through these in order

1. **Did `/v1/error` receive anything?** When the exchange cannot deliver your request, the failure comes back to your [error endpoint](/docs/nhcx/v1/api/other/endpoints/other-v1-error). Check its log first.
2. **Can the exchange reach your callback endpoint at all?** Domain name, hosting in India, allowed addresses and routing all matter. See [Your callback URL is rejected or never called](/docs/nhcx/v1/troubleshooting/your-callback-url-is-rejected).
3. **Does your endpoint answer `202` within 30 seconds, with the receipt body?** A slow or malformed receipt counts as a failed delivery. The exchange retries five times, then deletes the request.
4. **Did you address the right recipient?** When a [TPA](/docs/nhcx/v1/getting-started/glossary#organisations-and-programmes) processes the policy, `x-hcx-recipient_code` is the `processingid` from the policy lookup, not the payer's code.
5. **Where does the request stand?** Send one [status check](/docs/nhcx/v1/api/status/endpoints/status-v1-status), with the request's API call ID as its correlation ID. `request.queued` means it is still inside the exchange. `request.dispatched` means the recipient holds it, and a `/v1/on_status` callback follows.
6. **Did the recipient reject it?** A recipient that cannot process your request answers with a clear-text `ProtocolResponse` instead of a sealed payload. Its `x-hcx-status` is `response.error`. A handler that accepts only sealed bodies drops it, so read `x-hcx-error_details`.

## What you see when it works

The callback reaches your endpoint carrying the correlation ID you sent. Your endpoint answers it `202` within 30 seconds, with the receipt body. The next request of the same kind completes the same way.

## When it goes wrong

Do not resubmit with the same correlation ID. The exchange refuses it as a duplicate, `NHCX-1006`. Once you know the old cycle failed, start a new one with a new correlation ID.

If every check passes and nothing arrives, write to `hcx.integration@nha.gov.in`. Include the API call ID, the correlation ID, the timestamp and the `202` body.

| Code        | What it means                                         |
| ----------- | ----------------------------------------------------- |
| `NHCX-1001` | The receiver system is not reachable                  |
| `NHCX-1006` | A request with the same correlation ID already exists |
| `NHCX-1010` | No data for the correlation ID of a callback          |
| `NHCX-1012` | No records for the API call ID of a status check      |

## Next steps

- [Status and Search](/docs/nhcx/v1/getting-started/status-and-search): the status check in full.
- [The recipient cannot decrypt your message](/docs/nhcx/v1/troubleshooting/the-recipient-cannot-decrypt): when the rejection carries `PAYR-1001`.
- [The payer rejects your FHIR bundle](/docs/nhcx/v1/troubleshooting/the-payer-rejects-your-bundle): when it names a bundle fault.


---

# Every NHCX call returns 401

Every call fails with `401`, often with the message `Sender is not authorized to execute the operation`. When every endpoint fails the same way, the fault is your token or the header carrying it. It is not any one call.

## In short

- An expired token is the usual cause. Fetch a new one and retry the failing call once.
- The header value is `Bearer`, a space, then the token.
- Send the token in `bearer_auth`. NHCX reads `bearer_auth`, not `Authorization`.
- A sandbox token never works against a production host.

## Prerequisites

- More than one endpoint is failing. If one call fails while others succeed, read that call's own error instead.
- You have the full response body, not only the status code.

## Work through these in order

1. **Has the token expired?** An expired token returns this message. A token lasts 1200 seconds (20 minutes) from the moment it arrives, so a token older than that has expired. Fetch a new token and retry the failing call once. A retry with the old token fails the same way.
2. **Does the value start with `Bearer `?** The header value is the word `Bearer`, a space, then the token. A bare token returns `401`.
3. **Is the token in the header the call reads?** Every NHCX call reads the token from `bearer_auth`, not `Authorization`.
4. **Are the token and the host from the same environment?** A sandbox token does not work against a production host, or the reverse. Compare the host that issued the token with the host of the failing call. [Base URLs](/docs/nhcx/v1/getting-started/base-urls) lists both.
5. **Is the token call itself healthy?** If minting a token fails, check the credentials and the body. The session address needs `grantType` set to `client_credentials`. [Session Token](/docs/nhcx/v1/getting-started/session-token) has the call.

## What you see when it works

A call that returned `401` now returns its normal response. It keeps doing so across several calls, over more than 20 minutes, which is longer than one token lasts. One success can be a token that happened to be fresh, so confirm again after the next refresh.

## When it goes wrong

A `401` on linking or de-linking a policy, while other calls work, is a different fault. The token must come from the client ID that created the payer or [TPA](/docs/nhcx/v1/getting-started/glossary#organisations-and-programmes) named in the link. Run the linking job under those credentials.

If all five checks pass and calls still return `401`, the credentials may have been revoked or reissued. Write to `hcx.integration@nha.gov.in` with the call, its time and the full response body. Never send the token or the client secret.

## Next steps

- [Session Token](/docs/nhcx/v1/getting-started/session-token): minting the token and keeping it fresh.
- [Troubleshooting](/docs/nhcx/v1/reference/troubleshooting): the symptom table, if the `401` names a header.
- [When something breaks](/docs/nhcx/v1/troubleshooting): the other symptoms.


---

# When something breaks

Find the symptom you are seeing, not the error code. Each chapter here walks the checks in order, so you can start without knowing which code applies. They run in the order a message travels: your token, your address, delivery, encryption, the bundle, then the identifiers that tie a cycle together.

- [Every NHCX call returns 401](/docs/nhcx/v1/troubleshooting/every-call-returns-401): every endpoint fails the same way, not one call.
- [Your callback URL is rejected or never called](/docs/nhcx/v1/troubleshooting/your-callback-url-is-rejected): the endpoint update is refused, or nothing ever reaches your server.
- [Accepted with 202, and no callback arrives](/docs/nhcx/v1/troubleshooting/accepted-then-no-callback): the exchange took your request and nothing followed.
- [The recipient cannot decrypt your message](/docs/nhcx/v1/troubleshooting/the-recipient-cannot-decrypt): the answer is a `ProtocolResponse` carrying `PAYR-1001`.
- [The payer rejects your FHIR bundle](/docs/nhcx/v1/troubleshooting/the-payer-rejects-your-bundle): the answer names a bundle fault such as `PAYR-1004` or `PAYR-1008`.
- [Responses arrive against the wrong request](/docs/nhcx/v1/troubleshooting/responses-arrive-against-the-wrong-request): answers land on the wrong case, or the exchange refuses a duplicate.

If you already hold an error code, [Troubleshooting](/docs/nhcx/v1/reference/troubleshooting) in the Reference is organised the other way, by layer and by code. [Error Codes](/docs/nhcx/v1/reference/error-code-guide) lists every code either side can send.

## A service name you do not recognise

The name in a log line or a URL does not always match the exchange. Reprocess is served by `taskhcxservice`, notifications by `subscriptionhcxservice`, payment by `servicehcxpayment`.

| Service name in a log or URL    | Exchange it serves                                            |
| ------------------------------- | ------------------------------------------------------------- |
| `coverageeligibilityhcxservice` | Coverage eligibility                                          |
| `insuranceplanhcxservice`       | Insurance plan                                                |
| `preauthhcxservice`             | Preauthorisation                                              |
| `claimhcxservice`               | Claim                                                         |
| `communicationhcxservice`       | Communication, including a request for additional attachments |
| `servicehcxpayment`             | Payment notice                                                |
| `statushcxservice`              | Status check                                                  |
| `taskhcxservice`                | Task: reprocess and cancel                                    |
| `searchhcxservice`              | Search                                                        |
| `participanthcxservice`         | Participant service: registry, certificates and policies      |
| `subscriptionhcxservice`        | Notifications                                                 |
| `abdmproxy`                     | Face authentication for PMJAY biometrics                      |
| `nhcxpayerservice`              | PMJAY payer service: the role lookup and acting on a case     |
| `dummyhcxpayer`                 | The sandbox dummy payer's test hooks                          |

[Environments and addresses](/docs/nhcx/v1/reference/environments-and-addresses) has the full address of each.

## Next steps

- [Troubleshooting](/docs/nhcx/v1/reference/troubleshooting): the five layers and the symptom table.
- [Get your sandbox credentials](/docs/nhcx/v1/getting-started/get-your-sandbox-credentials): where to write, and what to put in the message.


---

# Responses arrive against the wrong request

An answer lands on the wrong case in your system. Or the exchange refuses a request as a duplicate, or refuses a callback it cannot match. All three come from how your system sets and reads the [correlation ID](/docs/nhcx/v1/getting-started/glossary#messages) and the [API call ID](/docs/nhcx/v1/getting-started/glossary#messages).

## In short

- Open each cycle with a new correlation ID, equal to that request's API call ID.
- Every message in the cycle echoes it. Every call gets a new API call ID.
- A failed cycle's correlation ID is inactive, so start a new cycle.
- Match incoming messages on the correlation ID, never on arrival order.

## Prerequisites

- You log the `x-hcx-correlation_id` and `x-hcx-api_call_id` of every message you send and receive.

## Work through these in order

1. **Does each request cycle get its own correlation ID?** Generate a new random 36-character identifier for every request that opens a cycle. Set it equal to that request's API call ID. Never copy one from an example.
2. **Does every message in the cycle carry it unchanged?** The answer, any query and every callback echo the request's correlation ID. The answer's own API call ID is different.
3. **Is the API call ID new on every call?** Generate a fresh one for every call, retries included.
4. **Did you reuse a failed cycle's correlation ID?** After an error the correlation ID becomes inactive. A new request with it is refused with `NHCX-1006`. Start a fresh cycle with a new ID.
5. **Do you match answers by correlation ID?** Store the correlation ID against the case before you send. Match every incoming message on it, never on arrival order or time.
6. **If you are the payer, is the recipient right?** The recipient code of your answer is the sender code of the request you answer.

## What you see when it works

Every callback lands on the case whose request carried its correlation ID. New requests are accepted with `202`, and your logs show no `NHCX-1006` or `NHCX-1010`.

## When it goes wrong

If one case's answers keep landing elsewhere, compare the correlation ID in the misplaced callback with the one stored on each case. Two cases holding the same value point at a generator that repeats. A [status check](/docs/nhcx/v1/api/status/endpoints/status-v1-status) shows which request the exchange holds for an ID.

| Code        | What it means                                                              |
| ----------- | -------------------------------------------------------------------------- |
| `NHCX-1006` | A request with the same correlation ID already exists                      |
| `NHCX-1010` | No data for the correlation ID of a callback                               |
| `NHCX-1012` | No records for an API call ID                                              |
| `PAYR-1516` | No event found for the API call ID and correlation ID of an error response |

## Next steps

- [Envelope Fields](/docs/nhcx/v1/reference/envelope-fields): every identifier on the envelope, and when each one changes.
- [The JWE message format](/docs/nhcx/v1/getting-started/jwe-message-format): how a cycle threads from request to answer.
- [When something breaks](/docs/nhcx/v1/troubleshooting): the other symptoms.


---

# The payer rejects your FHIR bundle

The payer opened your message and could not accept the Fast Healthcare Interoperability Resources (FHIR) bundle inside it. The answer names the fault with a code.

| Code        | What it means                                      |
| ----------- | -------------------------------------------------- |
| `PAYR-1004` | The bundle is malformed, followed by error details |
| `PAYR-1008` | The bundle is invalid or cannot be parsed          |
| `PAYR-1009` | No identifier for the patient                      |
| `PAYR-1013` | No identifier for the provider organisation        |

## In short

- Read the message with the code. `PAYR-1004` has two meanings.
- Run the [NRCeS](/docs/nhcx/v1/getting-started/glossary#organisations-and-programmes) validator on the exact bundle you sealed, and fix what it reports first.
- Every resource declares its NRCeS profile. The patient, both organisations and the claim each carry an identifier with a type.
- Attachments are Base64, named, and of an allowed content type.

## Prerequisites

- You have the full answer, including the message and any details after the code.
- You can run the NRCeS validator on the exact bundle you sealed.

## Work through these in order

Read the message with the code first. `PAYR-1004` also means "Provider is not registered with the payer for requested policy" on the standard payer sheet. The message text tells you which fault you have, and [Error Codes](/docs/nhcx/v1/reference/error-code-guide) explains the two sheets.

1. **Does the bundle pass the NRCeS validator?** Run it on the exact bundle you sealed, and fix what it reports first.
2. **Is the bundle shaped right?** It is a `Bundle` of type `collection`. Every resource declares its NRCeS profile in `meta.profile`. Resources reference each other as `urn:uuid:` identifiers, not relative paths.
3. **Does every resource carry its identifier and type?** The patient, both organisations and the claim each need an identifier with a type.
4. **Is your hospital identified correctly?** Send the [HFR](/docs/nhcx/v1/getting-started/glossary#identity-and-registration) ID as an identifier typed `NPI` in the provider `Organization`. It must match the registry ID recorded for you as sender.
5. **Are the attachments valid?** Each has Base64 data and a name that is not empty. Its content type is one of `application/pdf`, `application/jpg`, `application/jpeg`, `application/png` or `application/fhir+json`.
6. **Are the values clean?** Trim leading and trailing spaces. Codes are case sensitive and must match the expected values exactly.

## What you see when it works

The validator passes the bundle. The payer's answer is an adjudication, a claim response or an eligibility response with an outcome, not a bundle error.

## When it goes wrong

If the validator passes and the payer still refuses the bundle, send the bundle to `hcx.integration@nha.gov.in` for review by the NRCeS team. Include the payer's full error message, and replace personal data with test values first.

## Next steps

- [Bundles and Conventions](/docs/nhcx/v1/reference/fhir): the rules every bundle follows.
- [Codes and Value Sets](/docs/nhcx/v1/reference/fhir/codes-and-value-sets): the exact codes each element takes.
- [Troubleshooting](/docs/nhcx/v1/reference/troubleshooting): every bundle code, in the layer 4 rows.


---

# The recipient cannot decrypt your message

The payer's answer is a clear-text `ProtocolResponse` carrying `PAYR-1001`: an error occurred while decrypting the payload. The recipient could not open your [JWE](/docs/nhcx/v1/getting-started/glossary#messages) with its private key. The fault is almost always on the sending side: the wrong certificate, the wrong algorithm or the wrong form.

## In short

- Seal with the certificate of the participant in `x-hcx-recipient_code`, fetched within the last 24 hours.
- Use `RSA-OAEP-256` with `A256GCM`, in compact form.
- Resend with a new correlation ID and a new API call ID.
- `PAYR-1002` is the reverse fault. Update your own registered certificate.

## Prerequisites

- You have the `ProtocolResponse`, including `x-hcx-error_details` and the correlation ID.
- You know which certificate you sealed with, and when you fetched it.

## Work through these in order

1. **Did you seal to the recipient you addressed?** The certificate must belong to the participant in `x-hcx-recipient_code`. [Fetch it](/docs/nhcx/v1/api/registry/endpoints/registry-fetch-certs), passing that code as `participantid`. When a [TPA](/docs/nhcx/v1/getting-started/glossary#organisations-and-programmes) processes the policy, that code is the `processingid`.
2. **Is your cached copy stale?** Cache a certificate for 24 hours at most. On `PAYR-1001`, fetch it again and resend. A recipient that rotated its key has a new certificate.
3. **Did the key import correctly?** The call can return a PEM X.509 certificate or a bare SubjectPublicKeyInfo (SPKI) public key. Try the X.509 import first, then fall back to the bare key.
4. **Are the algorithms right?** The protected header carries `alg` `RSA-OAEP-256` and `enc` `A256GCM`.
5. **Is the form right?** The body is `{"payload": "<JWE compact string>"}`, one compact string with four dots.
6. **Is the [protected header](/docs/nhcx/v1/getting-started/glossary#messages) complete?** Check every `x-hcx-` field against [Envelope Fields](/docs/nhcx/v1/reference/envelope-fields). The sender and recipient codes come from the registry. The API call ID and correlation ID are fresh.

The reverse fault has its own code. `PAYR-1002` means the payer could not seal its answer to you with the certificate registered for you. Update it with [the certificate update call](/docs/nhcx/v1/api/registry/endpoints/registry-v2-update-cert) or the participant update. The payer fetches the new one and sends its answer.

## What you see when it works

You resend with a new correlation ID and a new API call ID. The answer arrives as a sealed payload on your callback, not a `ProtocolResponse`. Your own code opens it with your private key.

## When it goes wrong

If every check passes and `PAYR-1001` persists, ask the recipient to confirm that its registered certificate matches the private key it decrypts with. Then write to `hcx.integration@nha.gov.in` with the recipient code and the correlation ID.

## Next steps

- [Fetching a Recipient Certificate](/docs/nhcx/v1/getting-started/fetching-a-recipient-certificate): which certificate, and how long to cache it.
- [Building and Sending a JWE](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe): the algorithms and the compact form.
- [Your Certificate](/docs/nhcx/v1/getting-started/your-certificate): replacing yours when the payer reports `PAYR-1002`.


---

# Your callback URL is rejected or never called

The National Health Claims Exchange (NHCX) delivers requests and answers to the `endpoint_url` on your participant record. Either the update that sets it is refused, or it saves and nothing ever arrives. A sender addressing you sees `NHCX-1001`, receiver system not reachable.

## In short

- The URL is HTTPS, uses a domain name with no port, and points at a server in India.
- Allow the exchange's three addresses through your firewall.
- An endpoint update activates only after you confirm its passcode within 24 hours.
- Answer every delivery `202` within 30 seconds.

## Prerequisites

- Your participant is active, and you can call the participant update.
- You know the rules the address must meet. [Receiving a Callback](/docs/nhcx/v1/getting-started/receiving-a-callback) has them.

## Work through these in order

1. **Is the URL HTTPS and publicly reachable?** It must be publicly accessible and reachable from the exchange.
2. **Does it use a domain name?** Use a fully qualified domain name. An IP address, or a port number in the URL, is not accepted.
3. **Is the server hosted in India?** Callback servers must be.
4. **Are the exchange's addresses allowed in?** Allow `3.109.99.210`, `13.126.152.0` and `13.200.129.223` in your server configuration and firewall. Confirm no firewall rule blocks incoming requests from them.
5. **Did you confirm the update?** An endpoint update sends a passcode. The new endpoint activates only after you confirm it with [the update validation call](/docs/nhcx/v1/api/onboarding/endpoints/onboarding-update-validate), within 24 hours.
6. **Does your application route every path the exchange calls?** Requests arrive on use-case paths such as `/v1/claim/on_submit`. Check that load balancers, gateways and reverse proxies send each path to the right service and version.
7. **Does your endpoint answer fast enough?** Answer `202` with the receipt body within 30 seconds. Otherwise the exchange retries five times, then deletes the request.

## What you see when it works

Your participant record shows the new endpoint as active. The next message addressed to you arrives on the right path, and your endpoint answers it `202` within 30 seconds.

To see a delivery arrive, send a coverage eligibility check to the [dummy payer](/docs/nhcx/v1/getting-started/glossary#messages), `1000003538@hcx`. Its `/v1/coverageeligibility/on_check` callback arrives at your endpoint.

## When it goes wrong

If every check passes and nothing arrives, find out whether the request was ever sent to you. See [Accepted with 202, and no callback arrives](/docs/nhcx/v1/troubleshooting/accepted-then-no-callback).

If the update itself keeps failing, write to `hcx.integration@nha.gov.in` with your participant code, the endpoint URL and the full response.

## Next steps

- [Receiving a Callback](/docs/nhcx/v1/getting-started/receiving-a-callback): the endpoint, the receipt and the paths to host.
- [Creating and Updating a Participant](/docs/nhcx/v1/getting-started/creating-and-updating-a-participant): the update and its confirmation.
- [When something breaks](/docs/nhcx/v1/troubleshooting): the other symptoms.


---

# 21 September 2026

4 changes

### NHCX error pages list their codes

This is a correction. [Error codes](/docs/nhcx/v1/reference/error-codes) said no code was recorded, and so did the errors page of every NHCX module. 310 codes were recorded all along, and the pages now list them: by who sent them on the reference page, and by the paths they arrive on under each module. An NHCX code reaches you sealed inside a callback rather than in the response to your call, which is why a page built from response examples found none.

### The NHCX plugin installs

This is a correction. The command on [Build with AI](/docs/nhcx/v1/getting-started/build-with-ai#install-the-plugin) failed, because the marketplace did not list the plugin it named. It does now. The plugin also carries three commands and an agent for Claude Code: `/nhcx-decode-error`, `/nhcx-preflight`, `/nhcx-prove-seal` and `nhcx-call-debugger`.

### NHCX skills install as a folder

This is a correction. The install box for an NHCX skill was empty, and the command behind it fetched three files that an NHCX skill does not have. Each skill is 59 files across eight directories, so the command now takes the archive. Each also gains a scaffold, and its router says where the folder came from, that it is a snapshot, and what its claims rest on.

### Build it well, for NHCX

[Build it well](/docs/nhcx/v1/getting-started/build-it-well) is new. It covers who refused a message, which sends are safe to repeat, how to match an answer to its request, and what to do when no answer comes.


---

# 23 September 2026

5 changes

### The JWE message format has its own page

[The JWE message format](/docs/nhcx/v1/getting-started/jwe-message-format) is new. It lists the five parts of a message, the algorithms, every protected header field with its obligation, the status values, the receipt, protocol errors and the correlation rule in one place. [JWE Secure Messaging](/docs/nhcx/v1/concepts/jwe-status-and-errors) now explains how a message is sealed and opened in plain terms.

### Workflow codes follow the Workflow Status Sheet

This is a correction. Where the PMJAY Handbook and the Workflow Status Sheet disagree, the pages now follow the sheet. Cancel a preauthorisation on `PC01`, answered on `PC02`, not `122`. `251` acknowledges a resubmitted preauthorisation and is no longer listed as a reprocess acknowledgement. `25` is the claim document acknowledgement. [Workflow Codes](/docs/nhcx/v1/concepts/workflow-codes) also has a searchable list of every code with its status.

### Task inputs use intimationNumber

This is a correction. Pages told a preauthorisation Task to send its reference as `initimationNumber`, the spelling in NHA's PMJAY samples. They now use `intimationNumber`, the standard's spelling. If a payer refuses a Task for an invalid case number, check which spelling it expects.

### The NHCX adapter downloads and runs in Docker

[NHCX adapter](/docs/nhcx/v1/getting-started/nhcx-adapter#download) now offers the latest release for your operating system and architecture, with its checksums, and the commands to run the published container image `ghcr.io/nha-in/nhcx-adapter`.

### The NHCX skills are rebuilt

The seven NHCX skills on [Build with AI](/docs/nhcx/v1/getting-started/build-with-ai#install-a-skill) are replaced by a new generation. `nhcx-full` builds the whole provider-side integration end to end, and the insurance plan now belongs to `nhcx-preauth`, so `nhcx-insurance` is withdrawn. Each skill works through eight logged steps, from discovery to tests on the sandbox, and takes its NHCX facts from the nhcx-docs MCP server or a release of the NHCX package. The `nhcx` plugin is now version 1.0.0 and connects the nhcx-docs MCP server when it installs. Download a skill again rather than updating a copy from before this date.


---

# What's new in NHCX

Changes to the NHCX documentation that affect what you build, newest first. Each entry links to what you can now read, run or consume. Changes to other gateways are on the [site-wide What's new](/docs/whats-new).

## 23 September 2026

5 changes

- [The JWE message format has its own page](/docs/nhcx/v1/whats-new/2026-09-23#the-jwe-message-format-has-its-own-page)
- [Workflow codes follow the Workflow Status Sheet](/docs/nhcx/v1/whats-new/2026-09-23#workflow-codes-follow-the-workflow-status-sheet)
- [Task inputs use intimationNumber](/docs/nhcx/v1/whats-new/2026-09-23#task-inputs-use-intimationnumber)
- [The NHCX adapter downloads and runs in Docker](/docs/nhcx/v1/whats-new/2026-09-23#the-nhcx-adapter-downloads-and-runs-in-docker)
- [The NHCX skills are rebuilt](/docs/nhcx/v1/whats-new/2026-09-23#the-nhcx-skills-are-rebuilt)

## 21 September 2026

4 changes

- [NHCX error pages list their codes](/docs/nhcx/v1/whats-new/2026-09-21#nhcx-error-pages-list-their-codes)
- [The NHCX plugin installs](/docs/nhcx/v1/whats-new/2026-09-21#the-nhcx-plugin-installs)
- [NHCX skills install as a folder](/docs/nhcx/v1/whats-new/2026-09-21#nhcx-skills-install-as-a-folder)
- [Build it well, for NHCX](/docs/nhcx/v1/whats-new/2026-09-21#build-it-well-for-nhcx)

## What gets an entry

An entry has to change what you build or what you must go back and fix. Six kinds qualify:

- new coverage
- a correction
- a republished source
- an operation added or withdrawn
- a new artefact you can consume
- a procedure documented for the first time

Page layout, navigation and wording changes do not get an entry.


---

# Support

For integration-related queries, issues or technical assistance, raise a support request through the designated support channels.

## Support ticketing platform (recommended)

Submit integration-related issues, API errors, onboarding queries, certification-related concerns and implementation support requests through the designated support portal: [sandboxsupport.abdm.gov.in](https://sandboxsupport.abdm.gov.in/).

## Integration support email

Queries may also be sent to <integration.support@nha.gov.in>.

## Before you raise a request

Include the details in [what to put in a support request](/docs/hiecm/v3/troubleshooting#what-to-put-in-a-support-request), so the call you made can be traced.


---

# UHI API reference

No OpenAPI specification is published for UHI yet. The message shapes for each service are on its own page.

- [Network and protocol](/docs/uhi/v1/concepts/network-and-protocol): the search, select, init and confirm pattern every UHI service shares, and the roles on either side of it.
- [Onboarding](/docs/uhi/v1/getting-started/onboarding): registration, the signing keys and the callback URL your participant registers.
- The service pages: the fields each service adds on top of the shared pattern.


---

# UHI gateway

[UHI](/docs/uhi/v1/getting-started/glossary#uhi) is the Unified Health Interface, one of [ABDM](/docs/uhi/v1/getting-started/glossary#abdm)'s three gateways. After this page you will know the two roles, the two transports and the signing scheme that every UHI service shares.

[HIE-CM](/docs/uhi/v1/getting-started/glossary#hie-cm) moves records that already exist. UHI helps a patient find and book a service before any record exists: a consultation, an ambulance, a unit of blood, a medicine at a pharmacy. Any consumer app on the network can discover any provider on it.

## Prerequisite

Your application must have completed ABDM [M2](/docs/hiecm/v3/api/m2) with HIE-CM before it can be onboarded to any UHI service. This is a hard requirement. UHI sits on top of HIE-CM, it is not an alternative to it.

## Two roles

| Role                                               | Full name                           | What it is                                                                                                               |
| -------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| [EUA](/docs/uhi/v1/getting-started/glossary#eua)   | End User Application                | The patient facing app or website. Searches, shows results, books, displays status.                                      |
| [HSPA](/docs/uhi/v1/getting-started/glossary#hspa) | Health Service Provider Application | The provider platform. Holds doctor profiles and slot availability, confirms bookings, drives the appointment lifecycle. |

The HSP is the hospital, clinic or doctor, and the HSPA is its digital interface. The Gateway is the routing layer, and [NHA](/docs/uhi/v1/getting-started/glossary#nha) is the network operator that governs onboarding and the protocol.

## Two transports in one flow

This is the critical architectural point.

- **Discovery goes through the gateway.** Your EUA sends one `/search`, and the gateway broadcasts it to every registered HSPA. Responses come back to your callback URL as `/on_search`.
- **Everything after discovery is direct.** Booking, fulfilment and post fulfilment are point to point between the EUA and the one HSPA the patient chose. There is no central UHI API for those stages, so both sides expose their own endpoints.

The provider URI for those direct calls comes from the context of the `on_search` response. You do not know it before discovery.

## Signing

Every UHI call is signed with Ed25519 over a BLAKE-512 hash of the request body, carried in an `Authorization` header. Inbound gateway calls carry the same structure in an `X-Gateway-Authorization` header, with the key ID prefixed `gateway-nha`.

A header generator utility is published at [github.com/NHA-ABDM/UHI](https://github.com/NHA-ABDM/UHI/tree/main/header_generator_utility). Generate your Ed25519 key pair with it and send NHA the public key only.

## Sandbox environment

```text
Gateway base URI   https://uhigatewaysandbox.abdm.gov.inReference EUA      http://uhieuasandbox.abdm.gov.in/api/v1/euaServiceReference HSPA     https://hspasbx.abdm.gov.in/api/v1/hspa
```

## Service identity

A service is identified by fixed values in the call itself, not by a different endpoint. For physical consultation:

| Field                                 | Value           |
| ------------------------------------- | --------------- |
| `context.domain`                      | `nic2004:85111` |
| `context.core_version`                | `0.7.1`         |
| `message.intent.fulfillment.type`     | `Physical`      |
| `message.intent.item.descriptor.code` | `Consultation`  |
| `message.intent.item.descriptor.name` | `Consultation`  |

Other services use different values. Check the page for the service you are building.

## Services

- [Physical consultation](/docs/uhi/v1/concepts/services/physical-consultation)
- [Ambulance booking](/docs/uhi/v1/concepts/services/ambulance-booking)
- [Blood bank](/docs/uhi/v1/concepts/services/blood-bank)
- [Jan Aushadhi Kendra](/docs/uhi/v1/concepts/services/jan-aushadhi-kendra)
- [Jan Aushadhi medicine search](/docs/uhi/v1/concepts/services/jan-aushadhi-medicine-search)
- [AMRIT pharmacy](/docs/uhi/v1/concepts/services/amrit-pharmacy)
- [PMJAY HEM](/docs/uhi/v1/concepts/services/pmjay-hem)

The index for all of them is [UHI in API references](/docs/uhi/v1).

## What is missing here

Per stage request and response bodies sit on the [physical consultation](/docs/uhi/v1/concepts/services/physical-consultation) page. The other six services have their own documents and are not covered here.

## Next

- [HIE-CM](/docs/hiecm/v3/)
- [Milestones, by role](/docs/hiecm/v3/milestones)
- [UHI API references](/docs/uhi/v1)


---

# Ambulance booking

Ambulance booking on [UHI](/docs/uhi/v1/getting-started/glossary#uhi) lets a patient or a caregiver find ambulances near them across every registered provider, see arrival windows and indicative charges, and start a booking with the one they pick. After this page you will know the four calls that are live today, their fields, and what [NHA](/docs/uhi/v1/getting-started/glossary#nha) tests your app for.

Read [UHI services](/docs/uhi/v1) first, for the `context` block, the acknowledgement model, signing and the two transports.

## What is live, and what is not

This service is released in two phases.

| Phase  | Calls                                                                              | Status   |
| ------ | ---------------------------------------------------------------------------------- | -------- |
| First  | `search`, `on_search`, `init`, `on_init`                                           | Current  |
| Second | `confirm`, `on_confirm`, `status`, `on_status`, `cancel`, `on_cancel`, `on_update` | Upcoming |

Today the flow ends at a quote. The patient discovers ambulances, picks one, sends their details with `init`, and receives a quote with terms in `on_init`. There is no `confirm`. The outcome is the patient requesting a callback from the provider they chose.

Two limits follow from that.

- **The `agent` block must not appear in any current-phase payload.** Driver name, vehicle number and driver phone are post-confirmation data. Their absence is tested in `on_search` and `on_init`, and tests that your EUA shows no driver or vehicle UI at any point before confirmation.
- **Live tracking and dispatch updates are not available.** They arrive with the second phase.

## Out of scope right now

- The `NON_EMERGENCY` flow, which is future scope. Build `EMERGENCY` first.
- Booking confirmation and order creation from the EUA.
- State-operated ambulance networks. 108, 102 and 112 services are not on UHI today.
- Patient transport ambulances. An HSPA may return a `PTA` category in its catalog. Ignore it.

## Service identity

| Field                                 | Value                          |
| ------------------------------------- | ------------------------------ |
| `context.domain`                      | `nic2008:86909`                |
| `context.core_version`                | `0.7.1`                        |
| `message.intent.item.descriptor.code` | `AMBULANCE`                    |
| `message.intent.fulfillment.type`     | `EMERGENCY` or `NON_EMERGENCY` |

## Who is involved

| Role                                                     | What it does here                                                                                       |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| [EUA](/docs/uhi/v1/getting-started/glossary#eua)         | The patient or caregiver app. Sends the search, shows options, sends `init`, shows the quote and terms  |
| [HSPA](/docs/uhi/v1/getting-started/glossary#hspa)       | The ambulance operator's platform. Answers searches with live availability, answers `init` with a quote |
| [Gateway](/docs/uhi/v1/getting-started/glossary#gateway) | The routing layer. Broadcasts the search. Not involved from `init` onwards                              |

## The four calls

| # | Call        | Direction               | What happens                                                                              |
| - | ----------- | ----------------------- | ----------------------------------------------------------------------------------------- |
| 1 | `search`    | EUA to gateway to HSPAs | The patient searches by case type, ambulance class and pickup location                    |
| 2 | `on_search` | HSPA to gateway to EUA  | Each HSPA with availability returns a catalog with arrival windows and indicative pricing |
| 3 | `init`      | EUA to HSPA, direct     | The EUA sends patient details, billing and the chosen fulfilment                          |
| 4 | `on_init`   | HSPA to EUA, direct     | The HSPA returns a quote, payment terms and a cancellation policy                         |

Every one returns an acknowledgement synchronously. The real answer arrives later at the callback URL.

Silence is not an error. An HSPA answers only for areas it covers, so no response from a given HSPA tells you nothing about network health.

## Search filters

| Case type       | Ambulance class codes | Location fields required                         |
| --------------- | --------------------- | ------------------------------------------------ |
| `EMERGENCY`     | `ALS`, `BLS`, `ALL`   | `SOURCE` only: pickup GPS and address            |
| `NON_EMERGENCY` | `ALS`, `BLS`, `ALL`   | `SOURCE` and `DESTINATION`, both GPS and address |

`ALS` is advanced life support, `BLS` is basic life support. For an emergency search, set the class to `ALL` so nothing available is filtered out.

## search

`context` is the standard UHI block. The service-specific parts live in `message.intent`.

| Field                                  | Type     | Required    | What it is                                                   |
| -------------------------------------- | -------- | ----------- | ------------------------------------------------------------ |
| `category.descriptor.code`             | string   | Optional    | Ambulance class: `ALS`, `BLS`, or `ALL` for every class      |
| `fulfillment.type`                     | string   | Mandatory   | `EMERGENCY` or `NON_EMERGENCY`                               |
| `fulfillment.start.time.timestamp`     | ISO 8601 | Mandatory   | Requested pickup time. Use the current time for an emergency |
| `fulfillment.end.time.timestamp`       | ISO 8601 | Optional    | End of the acceptable window. Used for non-emergency only    |
| `fulfillment.tags.additional_services` | string   | Optional    | Comma-separated extras, for example an oxygen cylinder       |
| `locations[SOURCE].gps`                | string   | Mandatory   | Pickup coordinates as `latitude,longitude`                   |
| `locations[SOURCE].address`            | string   | Mandatory   | Pickup address text                                          |
| `locations[DESTINATION].gps`           | string   | Conditional | Drop-off coordinates. Non-emergency only                     |
| `locations[DESTINATION].address`       | string   | Conditional | Drop-off address. Non-emergency only                         |
| `item.descriptor.code`                 | string   | Mandatory   | `AMBULANCE`                                                  |

### Sample, emergency

With your identifiers substituted.

```json
{  "context": {    "domain": "nic2008:86909",    "country": "IND",    "city": "std:011",    "action": "search",    "core_version": "0.7.1",    "consumer_id": "<YOUR_EUA_ID_FROM_NHA_ONBOARDING>",    "consumer_uri": "<YOUR_HTTPS_CALLBACK_URL>",    "message_id": "e9a19230-f951-11ec-b135-53aea776f66b",    "timestamp": "2026-03-23T15:24:35",    "transaction_id": "e9a19230-f951-11ec-b135-53aea776f66b"  },  "message": {    "intent": {      "category": {        "descriptor": { "code": "ALS", "name": "ALS" }      },      "fulfillment": {        "type": "EMERGENCY",        "start": { "time": { "timestamp": "2026-01-05T15:24:35" } },        "end": { "time": { "timestamp": "2026-01-05T23:59:59" } },        "tags": { "additional_services": "oxygen cylinder, etc" }      },      "locations": [        {          "descriptor": { "code": "SOURCE", "name": "SOURCE" },          "gps": "12.423423,77.325647",          "address": "SHIVAJI MARG, PUNE"        }      ],      "item": {        "descriptor": { "code": "AMBULANCE", "name": "AMBULANCE" }      }    }  }}
```

## on\_search

| Field                                                 | Type     | Required  | What it is                                               |
| ----------------------------------------------------- | -------- | --------- | -------------------------------------------------------- |
| `context.provider_id`                                 | string   | Mandatory | HSPA identifier. You need this for `init`                |
| `context.provider_uri`                                | string   | Mandatory | HSPA callback URL. You need this for `init`              |
| `context.transaction_id`                              | string   | Mandatory | Matches your search                                      |
| `catalog.descriptor.name`                             | string   | Mandatory | HSPA name                                                |
| `catalog.descriptor.images`                           | string   | Optional  | HSPA logo, preferably base64                             |
| `catalog.descriptor.flag`                             | boolean  | Mandatory | `false` means the service is active, `true` means paused |
| `providers[].id`                                      | string   | Mandatory | Provider identifier                                      |
| `providers[].categories[].code`                       | string   | Mandatory | Ambulance class: `ALS` or `BLS`                          |
| `providers[].fulfillments[].id`                       | string   | Mandatory | Fulfilment ID, for example `ML-ALS-01`                   |
| `providers[].fulfillments[].type`                     | string   | Mandatory | Case type. Must match the search                         |
| `providers[].fulfillments[].tracking`                 | boolean  | Mandatory | Whether live tracking is supported for this option       |
| `providers[].fulfillments[].start.time.timestamp`     | ISO 8601 | Mandatory | Earliest estimated arrival                               |
| `providers[].fulfillments[].end.time.timestamp`       | ISO 8601 | Mandatory | Latest estimated arrival                                 |
| `providers[].fulfillments[].tags.additional_services` | string   | Optional  | Extras available on this option                          |
| `providers[].fulfillments[].tags.deeplink_url`        | string   | Optional  | Deep link into the HSPA app                              |
| `providers[].items[].id`                              | string   | Mandatory | Item identifier                                          |
| `providers[].items[].descriptor.flag`                 | boolean  | Mandatory | `true` means payment is required                         |
| `providers[].items[].price.value`                     | string   | Mandatory | Base indicative price in INR                             |
| `providers[].items[].price.estimated_Value`           | string   | Optional  | Estimated total charge                                   |
| `providers[].items[].price.minimum_Value`             | string   | Optional  | Minimum or advance charge                                |
| `providers[].items[].price.maximum_Value`             | string   | Optional  | Maximum expected charge                                  |
| `providers[].items[].fulfillment_id`                  | string   | Mandatory | Links this price to a fulfilment                         |

### How the pieces link

Each fulfilment ID appears twice: once where the fulfilment is declared, and once as `items[].fulfillment_id`. The item also carries `category_id`. The chain is category, then fulfilment, then item, joined through the item object. Walk it to show "ALS ambulance, arriving 12:30 to 12:35, around 500 rupees".

### Sample, trimmed

```json
{  "context": {    "domain": "nic2008:86909",    "action": "on_search",    "core_version": "0.7.1",    "consumer_id": "<YOUR_EUA_ID_FROM_NHA_ONBOARDING>",    "consumer_uri": "<YOUR_HTTPS_CALLBACK_URL>",    "provider_id": "<HSPA_ID_FROM_THIS_RESPONSE>",    "provider_uri": "<HSPA_CALLBACK_URL_FROM_THIS_RESPONSE>",    "transaction_id": "e9a19230-f951-11ec-b135-53aea776f66b",    "message_id": "e9a19230-f951-11ec-b135-53aea776f66b"  },  "message": {    "catalog": {      "descriptor": {        "name": "Medulance HSPA",        "flag": false,        "short_desc": "Medulance: Ambulance Provider HSPA"      },      "providers": [        {          "id": "1",          "descriptor": { "name": "Medulance", "flag": false },          "categories": [            { "id": "1", "descriptor": { "name": "Advanced Life Support (ALS)", "code": "ALS", "flag": false } },            { "id": "2", "descriptor": { "name": "Basic Life Support (BLS)", "code": "BLS", "flag": false } }          ],          "fulfillments": [            {              "id": "ML-ALS-01",              "type": "EMERGENCY",              "tracking": true,              "start": { "time": { "timestamp": "2026-01-05T12:30:00" } },              "end": { "time": { "timestamp": "2026-01-05T12:35:00" } },              "tags": {                "additional_services": "oxygen cylinder, etc",                "deeplink_url": "https://deeplinkurl.com"              }            }          ],          "items": [            {              "id": "1",              "descriptor": { "name": "Charges", "flag": true },              "price": {                "currency": "INR",                "value": "500",                "estimated_Value": "500",                "minimum_Value": "200",                "maximum_Value": "1500"              },              "category_id": "1",              "fulfillment_id": "ML-ALS-01"            }          ]        }      ]    }  }}
```

## init

Direct to the HSPA, at the `provider_uri` you took from `on_search`.

| Field                                        | Type    | Required    | What it is                                                                                         |
| -------------------------------------------- | ------- | ----------- | -------------------------------------------------------------------------------------------------- |
| `context.provider_id`                        | string  | Mandatory   | Carried from `on_search`                                                                           |
| `context.provider_uri`                       | string  | Mandatory   | Carried from `on_search`                                                                           |
| `order.provider.id`                          | string  | Mandatory   | The provider the user picked                                                                       |
| `order.item.id`                              | string  | Mandatory   | The item the user picked                                                                           |
| `order.item.fulfillment_id`                  | string  | Mandatory   | The fulfilment the user picked                                                                     |
| `order.fulfillment.id`                       | string  | Mandatory   | Matches `item.fulfillment_id`                                                                      |
| `order.fulfillment.type`                     | string  | Mandatory   | `EMERGENCY` or `NON_EMERGENCY`                                                                     |
| `order.fulfillment.tracking`                 | boolean | Mandatory   | Carried from `on_search`                                                                           |
| `order.fulfillment.tags.additional_services` | string  | Optional    | Extras the patient asked for                                                                       |
| `order.fulfillment.tags.deeplink_url`        | string  | Optional    | Carried from `on_search` if present                                                                |
| `order.billing.name`                         | string  | Mandatory   | Patient or responsible person                                                                      |
| `order.billing.address`                      | object  | Mandatory   | Pickup address: `locality`, `state`, `country`, `area_code`                                        |
| `order.billing.phone`                        | string  | Mandatory   | Contact number                                                                                     |
| `order.customer.id`                          | string  | Mandatory   | Patient [ABHA](/docs/uhi/v1/getting-started/glossary#abha) address, for example `91XXXXXXXXXX@sbx` |
| `order.customer.person.dob`                  | string  | Optional    | `YYYY-MM-DD`                                                                                       |
| `order.customer.person.gender`               | string  | Optional    | `M`, `F` or `O`                                                                                    |
| `order.locations[SOURCE]`                    | object  | Mandatory   | Pickup GPS and address                                                                             |
| `order.locations[DESTINATION]`               | object  | Conditional | Required for non-emergency, optional for emergency                                                 |

## on\_init

The HSPA answers with the order ID, a quote and the terms.

| Field                                    | Type         | Required    | What it is                                                        |
| ---------------------------------------- | ------------ | ----------- | ----------------------------------------------------------------- |
| `order.id`                               | string       | Mandatory   | The HSPA's order ID. Carry it into every call in the second phase |
| `order.fulfillment.tags.terms_reference` | string (URL) | Mandatory   | Link to the HSPA's versioned terms document                       |
| `order.quote.price.value`                | string       | Mandatory   | Total confirmed price in INR                                      |
| `order.quote.breakup[].title`            | string       | Mandatory   | Line item name, for example `Ambulance Base Charge`               |
| `order.quote.breakup[].price.value`      | string       | Mandatory   | Line item amount                                                  |
| `order.payment.type`                     | string       | Mandatory   | `ON-ORDER` at booking, or `PRE-ORDER` in advance                  |
| `order.payment.status`                   | string       | Mandatory   | For example `NOT_PAID`                                            |
| `order.terms[].type`                     | string       | Mandatory   | `Commercial`, `Settlement`, `Cancellation`, `Refund` or `Payment` |
| `order.terms[].termsState`               | string       | Mandatory   | `INITIATED`, awaiting EUA review                                  |
| `order.locations[SOURCE]`                | object       | Mandatory   | Echoed from `init`                                                |
| `order.locations[DESTINATION]`           | object       | Conditional | Echoed from `init` for non-emergency                              |

Three terms apply in the current phase: `Commercial`, `Cancellation` and `Payment`, each at `INITIATED`.

```json
{  "quote": {    "price": { "currency": "INR", "value": "500.0" },    "breakup": [      { "title": "Ambulance Base Charge", "price": { "currency": "INR", "value": "400.0" } },      { "title": "Consumable Charges", "price": { "currency": "INR", "value": "100.0" } }    ]  },  "payment": { "type": "ON-ORDER", "status": "NOT_PAID" }}
```

Most of `on_init` exists for the second phase. You may receive these fields now without showing all of them to the user yet.

## What your EUA has to show

| ID         | Requirement                                                                                                |
| ---------- | ---------------------------------------------------------------------------------------------------------- |
| `AMB-E-01` | Show the HSPA name and logo from `catalog.descriptor` in the listing, whenever they arrive in the response |
| `AMB-E-02` | Show the estimated arrival window from `fulfillment.start` and `fulfillment.end` for each option           |
| `AMB-E-03` | Show the indicative price from `item.price.value` before the user selects                                  |
| `AMB-E-04` | Show the full `on_init` cancellation and payment terms before enabling any confirm action                  |
| `AMB-E-05` | Show no driver or vehicle detail anywhere before confirmation                                              |

## Edge cases to handle

| Case                                                                    | What your system does                                              |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------ |
| No HSPA answers within your window                                      | Show the user a clear empty result. Do not present it as a failure |
| An HSPA returns an empty `providers` array                              | Handle it without a crash or a display error                       |
| A duplicate `search` with the same `transaction_id`                     | Expect the gateway or the HSPA to deduplicate                      |
| `on_init` with `payment.type: PRE-ORDER` and a non-zero `minimum_Value` | Show the advance payment requirement to the user                   |

## Prerequisites

For an EUA:

- [ABDM](/docs/uhi/v1/getting-started/glossary#abdm) [M2](/docs/hiecm/v3/api/m2) with [HIE-CM](/docs/uhi/v1/getting-started/glossary#hie-cm) completed. This is the hard prerequisite for production access.
- A publicly reachable HTTPS `consumer_uri` for `on_search` and `on_init`.
- Ed25519 signing with BLAKE-512 body hashing.
- Asynchronous handling. Do not block on a synchronous reply to `search` or `init`.
- `EMERGENCY` support at minimum. `NON_EMERGENCY` is recommended, not required.

For an HSPA:

- A publicly reachable HTTPS callback URL for `search` from the gateway and `init` from EUAs.
- Ed25519 signing on every outbound response.
- Real-time or near real-time availability data. Integrations relying only on manually maintained records are not approved for production.
- An `on_init` that carries a confirmed quote, payment terms and a cancellation policy.
- No `agent` block in any current-phase payload.

## What is missing here

- The calls in the second phase have no field reference yet.
- A Postman collection for this service is available from your onboarding contact.
- Error codes for this service are not enumerated in the source document.

## Next

- [UHI services](/docs/uhi/v1) for the shared protocol
- [Physical consultation](/docs/uhi/v1/concepts/services/physical-consultation), the service with the full lifecycle
- [Blood bank](/docs/uhi/v1/concepts/services/blood-bank)
- [Support](/docs/support)


---

# AMRIT Pharmacy discovery

AMRIT Pharmacies are the discounted medicine stores run inside government hospitals by HLL Lifecare Limited. After this page you will know the five ways to search for one and every field that comes back.

## Who does what

Three parties. Shared roles, signing and onboarding are on [UHI services](/docs/uhi/v1).

| Party                                                    | Who runs it                                                      | What it does here                                                      |
| -------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [EUA](/docs/uhi/v1/getting-started/glossary#eua)         | You, or any [PHR](/docs/uhi/v1/getting-started/glossary#phr) app | Sends the `search`. Receives the `on_search`. Renders the store list.  |
| [UHI](/docs/uhi/v1/getting-started/glossary#uhi) Gateway | [NHA](/docs/uhi/v1/getting-started/glossary#nha)                 | Validates and routes the `search`. Relays the `on_search` back to you. |
| [HSPA](/docs/uhi/v1/getting-started/glossary#hspa)       | HLL Lifecare Limited                                             | Queries the AMRIT store database. Builds the `on_search` catalog.      |

You do not build a [HSPA](/docs/uhi/v1/getting-started/glossary#hspa) unless you are HLL or their technology partner.

## Message flow

Two calls, asynchronous, discovery only. There is no ordering and no reservation. The HTTP 200 from the Gateway is a receipt. The store data arrives afterwards on your callback URL.

| Step | Who acts    | What happens                                                               |
| ---- | ----------- | -------------------------------------------------------------------------- |
| 1    | Your system | You build a `search` with your filters and POST it to the Gateway.         |
| 2    | Gateway     | Returns HTTP 200 ACK immediately. Forwards the `search` to the AMRIT HSPA. |
| 3    | AMRIT HSPA  | Queries the store database against your filters.                           |
| 4    | AMRIT HSPA  | POSTs an `on_search` to the Gateway with a catalog of matching stores.     |
| 5    | Gateway     | POSTs the `on_search` to your `consumer_uri`.                              |
| 6    | Your system | ACKs the `on_search` and renders the list.                                 |

Match a response to its request by `context.transaction_id`. Your `consumer_uri` must be a publicly reachable HTTPS endpoint.

## Service identity

| Parameter                    | Value                                                     | Where it goes                                            |
| ---------------------------- | --------------------------------------------------------- | -------------------------------------------------------- |
| `domain`                     | `nic2025:477201`                                          | `context.domain` in every call                           |
| `fulfillment.type`           | `AMRIT`                                                   | `message.intent.fulfillment.type`                        |
| `item.descriptor.code`       | `AMRIT_PHARMACY`                                          | `message.intent.item.descriptor.code`                    |
| `item.descriptor.name`       | `AMRIT_PHARMACY`                                          | `message.intent.item.descriptor.name`                    |
| Provider ID                  | Not yet published                                         | Identifies the AMRIT HSPA on the network                 |
| Provider URL                 | Not yet published                                         | The AMRIT HSPA endpoint registered with NHA              |
| HSPA public key ID           | Not yet published                                         | The Gateway uses it to verify AMRIT's response signature |
| Gateway base URL, sandbox    | `https://uhigatewaysandbox.abdm.gov.in/api/v1/uhi/search` | Append `/search` or `/on_search` to the base path        |
| Gateway base URL, production | `https://uhigateway.abdm.gov.in/api/v1/uhi/search`        | Append `/search` or `/on_search` to the base path        |

The last three are issued at onboarding. See [Confirm at onboarding](#confirm-at-onboarding). Ask your contact for the registered values before you go to sandbox.

## Search filters

No mandatory location filter. All five filter shapes are independent and they combine.

| Search type           | Fields used                                                                                      | Use case                               |
| --------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------- |
| By pharmacy code      | `category.descriptor.code`, `category.descriptor.name`                                           | Look up one store by its assigned code |
| By state and district | `location.state.code`, `location.state.name`, `location.district.code`, `location.district.name` | All AMRIT stores in a district         |
| By pincode            | `address.area_code`                                                                              | Stores in a 6 digit pincode area       |
| By GPS and radius     | `location.gps`, `location.radius.type`, `location.radius.value`, `location.radius.unit`          | Stores near the user                   |
| Combined              | state, district and `address.area_code` together                                                 | Narrow to a sub area of a district     |

`address` sits beside `location` inside `message.intent`, not inside it.

## Sample payloads

The `context` block is identical across all five variants. Only `message.intent` changes.

### Search by pharmacy code

```json
{  "context": {    "domain": "nic2025:477201",    "country": "IND",    "city": "std:011",    "action": "search",    "core_version": "0.7.1",    "consumer_id": "<YOUR_EUA_ID_FROM_NHA_ONBOARDING>",    "consumer_uri": "<YOUR_HTTPS_CALLBACK_URL>",    "message_id": "<FRESH_UUID_PER_CALL>",    "timestamp": "2026-06-09T18:24:35",    "transaction_id": "<FRESH_UUID_PER_SEARCH_SESSION>"  },  "message": {    "intent": {      "category": {        "descriptor": {          "code": "Pharmacy Code",          "name": "Pharmacy Code"        }      },      "fulfillment": {        "type": "AMRIT",        "start": { "time": { "timestamp": "2026-06-09T00:00:00" } },        "end": { "time": { "timestamp": "2026-06-09T23:59:59" } }      },      "item": {        "descriptor": { "code": "AMRIT_PHARMACY", "name": "AMRIT_PHARMACY" }      }    }  }}
```

Two values are in circulation for `category.descriptor`: the literal string `Pharmacy Code`, and the pharmacy code value itself. Those are two different things. See [Confirm at onboarding](#confirm-at-onboarding).

### Search by state and district

```json
{  "message": {    "intent": {      "fulfillment": {        "type": "AMRIT",        "start": { "time": { "timestamp": "2026-06-09T00:00:00" } },        "end": { "time": { "timestamp": "2026-06-09T23:59:59" } }      },      "item": {        "descriptor": { "code": "AMRIT_PHARMACY", "name": "AMRIT_PHARMACY" }      },      "location": {        "district": { "code": "466", "name": "Ahmednagar" },        "state": { "code": "27", "name": "Maharashtra" }      }    }  }}
```

### Search by pincode

```json
{  "message": {    "intent": {      "fulfillment": {        "type": "AMRIT",        "start": { "time": { "timestamp": "2026-06-09T00:00:00" } },        "end": { "time": { "timestamp": "2026-06-09T23:59:59" } }      },      "item": {        "descriptor": { "code": "AMRIT_PHARMACY", "name": "AMRIT_PHARMACY" }      },      "address": { "area_code": "413736" }    }  }}
```

### Search by GPS and radius

```json
{  "message": {    "intent": {      "fulfillment": {        "type": "AMRIT",        "start": { "time": { "timestamp": "2026-06-09T00:00:00" } },        "end": { "time": { "timestamp": "2026-06-09T23:59:59" } }      },      "item": {        "descriptor": { "code": "AMRIT_PHARMACY", "name": "AMRIT_PHARMACY" }      },      "location": {        "gps": "19.7126974,74.4833288",        "radius": { "type": "CONSTANT", "value": "5", "unit": "km" }      }    }  }}
```

### Combined filters

```json
{  "message": {    "intent": {      "fulfillment": {        "type": "AMRIT",        "start": { "time": { "timestamp": "2026-06-09T00:00:00" } },        "end": { "time": { "timestamp": "2026-06-09T23:59:59" } }      },      "item": {        "descriptor": { "code": "AMRIT_PHARMACY", "name": "AMRIT_PHARMACY" }      },      "location": {        "district": { "code": "466", "name": "Ahmednagar" },        "state": { "code": "27", "name": "Maharashtra" }      },      "address": { "area_code": "413736" }    }  }}
```

### on\_search response

Each `providers[]` entry is one AMRIT store. Three things here do not appear in other UHI services: the pharmacy type on the fulfillment, the store opening and closing times, and the [HFR](/docs/uhi/v1/getting-started/glossary#hfr) ID tag.

```json
{  "context": {    "domain": "nic2025:477201",    "country": "IND",    "city": "std:011",    "action": "on_search",    "core_version": "0.7.1",    "consumer_id": "eua-nha",    "consumer_uri": "https://uhieuasandbox.abdm.gov.in/api/v1/euaService",    "provider_id": "amrit-hspa",    "provider_uri": "https://amritpharmacy.gov.in/api/v1/admin/store/",    "message_id": "e9a19230-f951-11ec-b135-53aea776f66b",    "timestamp": "2026-06-09T18:24:35",    "transaction_id": "e9a19230-f951-11ec-b135-53aea776f66b"  },  "message": {    "catalog": {      "descriptor": {        "name": "AMRIT PHARMACY SERVICE",        "images": "<AMRIT_PHARMACY_HSPA_LOGO_URL>",        "short_desc": "<HSPA_SHORT_DESCRIPTION_SET_BY_HLL>",        "long_desc": "<HSPA_LONG_DESCRIPTION_SET_BY_HLL>"      },      "providers": [        {          "id": "AMRITST01460",          "descriptor": {            "name": "ESIS NAGPUR",            "code": "",            "symbol": "",            "short_desc": "AMRIT - ESIS NAGPUR",            "long_desc": ""          },          "fulfillments": [            {              "id": "0",              "type": "AMRIT",              "agent": { "name": "<CONTACT_PERSON_NAME>" },              "start": { "time": { "timestamp": "<STORE_OPENING_TIME>" } },              "end": { "time": { "timestamp": "<STORE_CLOSING_TIME>" } },              "tags": { "@abdm/gov.in/hfr_id": "<HFR_ID>" }            }          ],          "location": {            "id": "1",            "descriptor": { "name": "ESIS NAGPUR" },            "city": { "name": "", "code": "" },            "district": { "name": "NAGPUR", "code": "466" },            "state": { "name": "Maharashtra", "code": "27" },            "country": { "name": "INDIA", "code": "+91" },            "gps": "19.7126974,74.4833288",            "address": "AMRIT PHARMACY, ESIS HOSPITAL, SOMWARI ROAD, OPP. NURSES HOSTEL, KRIDA CHOWK, SOMWARIPETH, NAGPUR, MAHARASHTRA - 440009",            "radius": { "type": "CONSTANT", "value": "12", "unit": "km" }          },          "contact": {            "phone": "<PHARMACY_CONTACT_NUMBER>",            "email": "<PHARMACY_CONTACT_EMAIL>"          }        }      ]    }  }}
```

The angle bracket values above are placeholders. No filled example is published for the store hours, the contact block or the HFR ID, and no timestamp format for opening and closing times. The two `catalog.descriptor` description fields hold descriptive prose in placeholders rather than real values, so they appear here that way too. The sample also carries a `location.radius` block that the field reference does not list.

## Field reference

### search: context

All fields are mandatory and identical across every variant.

| Field            | Type     | Value                                                |
| ---------------- | -------- | ---------------------------------------------------- |
| `domain`         | string   | `nic2025:477201`, fixed                              |
| `country`        | string   | `IND`, fixed                                         |
| `city`           | string   | STD code, for example `std:011`                      |
| `action`         | string   | `search`, fixed                                      |
| `core_version`   | string   | `0.7.1`                                              |
| `consumer_id`    | string   | Your registered EUA identifier                       |
| `consumer_uri`   | string   | Your HTTPS callback URL                              |
| `message_id`     | UUID     | Fresh per call. Never reuse.                         |
| `transaction_id` | UUID     | Fresh per search session. The `on_search` copies it. |
| `timestamp`      | ISO 8601 | Request time                                         |

### search: message.intent

| Field path                         | Type            | Mandatory   | Description                                     |
| ---------------------------------- | --------------- | ----------- | ----------------------------------------------- |
| `fulfillment.type`                 | string          | Yes         | `AMRIT`, fixed                                  |
| `fulfillment.start.time.timestamp` | datetime        | Yes         | Start of the search window                      |
| `fulfillment.end.time.timestamp`   | datetime        | Yes         | End of the search window                        |
| `item.descriptor.code`             | string          | Yes         | `AMRIT_PHARMACY`, fixed                         |
| `item.descriptor.name`             | string          | Yes         | `AMRIT_PHARMACY`, fixed                         |
| `category.descriptor.code`         | string          | Conditional | Set when searching by pharmacy code             |
| `category.descriptor.name`         | string          | Conditional | Set when searching by pharmacy code             |
| `location.state.name`              | string          | No          | State name, for example `Maharashtra`           |
| `location.state.code`              | string          | No          | Numeric state code, for example `27`            |
| `location.district.name`           | string          | No          | District name, for example `Ahmednagar`         |
| `location.district.code`           | string          | No          | Numeric district code, for example `466`        |
| `location.gps`                     | string          | No          | `lat,long`, for example `19.7126974,74.4833288` |
| `location.radius.type`             | string          | No          | `CONSTANT`. Required with a GPS search.         |
| `location.radius.value`            | string or float | No          | Radius in km                                    |
| `location.radius.unit`             | string          | No          | `km`                                            |
| `address.area_code`                | string          | No          | 6 digit pincode                                 |

### on\_search: provider records

| Field path                                                       | Type     | Description                                                                    |
| ---------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ |
| `catalog.providers[].id`                                         | string   | AMRIT store code, for example `AMRITST01460`                                   |
| `catalog.providers[].descriptor.name`                            | string   | Name of the hospital that hosts the store                                      |
| `catalog.providers[].descriptor.code`                            | string   | Empty. Reserved for future use.                                                |
| `catalog.providers[].descriptor.symbol`                          | string   | Empty. Reserved for future use.                                                |
| `catalog.providers[].descriptor.short_desc`                      | string   | Pharmacy label, for example `AMRIT - ESIS NAGPUR`                              |
| `catalog.providers[].descriptor.long_desc`                       | string   | May be empty                                                                   |
| `catalog.providers[].fulfillments[].type`                        | string   | Pharmacy type. One of `AMRIT`, `AMRIT_OPTICALS`, `HLL_PNS`, `AMRIT_DEENDAYAL`. |
| `catalog.providers[].fulfillments[].agent.name`                  | string   | Contact person at the store                                                    |
| `catalog.providers[].fulfillments[].start.time.timestamp`        | datetime | Store opening time                                                             |
| `catalog.providers[].fulfillments[].end.time.timestamp`          | datetime | Store closing time                                                             |
| `catalog.providers[].fulfillments[].tags["@abdm/gov.in/hfr_id"]` | string   | Health Facility Registry identifier for the store                              |
| `catalog.providers[].location.gps`                               | string   | `lat,long` of the store                                                        |
| `catalog.providers[].location.address`                           | string   | Full street address                                                            |
| `catalog.providers[].location.city.name`                         | string   | May be empty                                                                   |
| `catalog.providers[].location.city.code`                         | string   | May be empty                                                                   |
| `catalog.providers[].location.district.name`                     | string   | District name                                                                  |
| `catalog.providers[].location.district.code`                     | string   | District code                                                                  |
| `catalog.providers[].location.state.name`                        | string   | State name                                                                     |
| `catalog.providers[].location.state.code`                        | string   | State code                                                                     |
| `catalog.providers[].location.country.name`                      | string   | `INDIA`, fixed                                                                 |
| `catalog.providers[].location.country.code`                      | string   | `+91`, fixed                                                                   |
| `catalog.providers[].contact.phone`                              | string   | Store phone number                                                             |
| `catalog.providers[].contact.email`                              | string   | May be empty                                                                   |

Note that `fulfillments[].type` carries the pharmacy type here. In Jan Aushadhi Kendra discovery the same field carries the literal value `contact`. Do not reuse a parser across the two services without checking this field.

## Confirm at onboarding

Three values are issued when you onboard. Build the flow and hold these until you have them.

- **Your registered provider ID, provider URL and HSPA public key ID.** Responses carry `amrit-hspa` at `https://amritpharmacy.gov.in/api/v1/admin/store/`. The public key ID is issued to you directly.
- **What goes in `category.descriptor` for a pharmacy code search.** Both the literal string `Pharmacy Code` and the pharmacy code value are in circulation. Confirm which the HSPA accepts.
- **The format of store opening and closing times.** No format is published, so read the values back from your first live response rather than parsing to a fixed pattern.

## Next

- The other pharmacy discovery service on UHI: [Jan Aushadhi Kendra discovery](/docs/uhi/v1/concepts/services/jan-aushadhi-kendra)
- Shared UHI protocol, signing and onboarding: [UHI services](/docs/uhi/v1)


---

# Blood bank discovery

Blood bank discovery is the smallest service on [UHI](/docs/uhi/v1/getting-started/glossary#uhi): one call pair. Your app sends a search with a blood group, a component and a location, and gets back blood banks with unit counts, addresses and phone numbers.

Read [UHI services](/docs/uhi/v1) first, for the `context` block, the acknowledgement model, signing and the two transports.

## Scope

Discovery only: `search` and `on_search`. There is no booking or reservation. Put the blood bank's phone number somewhere the user cannot miss it, because calling is how a unit gets held.

## Service identity

| Field                             | Value                   | Note                                                   |
| --------------------------------- | ----------------------- | ------------------------------------------------------ |
| `context.domain`                  | `nic2008:86906`         | Fixed. A wrong value means no HSPA answers your search |
| `context.core_version`            | `0.7.1`                 | Must match exactly                                     |
| `context.action`                  | `search` or `on_search` | Set by the sender                                      |
| `message.intent.fulfillment.type` | `BloodStock`            | Fixed for every blood bank search                      |

## Who is involved

Both roles are open here. An organisation can onboard as either or both.

| Role                                               | What it does                                                                                   |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [EUA](/docs/uhi/v1/getting-started/glossary#eua)   | A patient or clinician facing app. Sends searches, receives results at its callback URL        |
| [HSPA](/docs/uhi/v1/getting-started/glossary#hspa) | A blood bank management system or aggregator. Answers searches from its own inventory database |

At the time of the document there was one registered blood bank HSPA on the network: e-RaktKosh, the centralised blood bank management system.

[NHA](/docs/uhi/v1/getting-started/glossary#nha) sets a bar for the HSPA role. Your blood bank database has to be maintained independently and cover stock at a scope and quality comparable to e-RaktKosh. Integrations built on manually maintained or infrequently updated records will not be approved for production.

## The flow

| Step | Who                                                      | What happens                                                           |
| ---- | -------------------------------------------------------- | ---------------------------------------------------------------------- |
| 1    | Your EUA                                                 | Posts `search` to the gateway with blood group, component and location |
| 2    | [Gateway](/docs/uhi/v1/getting-started/glossary#gateway) | Returns HTTP 200 with an acknowledgement. This confirms receipt only   |
| 3    | Gateway                                                  | Routes the search to every registered blood bank HSPA                  |
| 4    | HSPA                                                     | Queries its inventory database                                         |
| 5    | HSPA                                                     | Posts `on_search` to the gateway with availability and unit counts     |
| 6    | Gateway                                                  | Forwards `on_search` to your `consumer_uri`                            |
| 7    | Your EUA                                                 | Returns HTTP 200 and aggregates results as they arrive                 |

There is no end signal. Responses land one at a time and nothing tells you the last one has arrived. Use a timeout window of 10 to 15 seconds, and display results as they come in.

## Two search modes

Blood group and component filters work with either mode.

| Mode               | Mandatory                                                             | Optional               | Behaviour                                                                                       |
| ------------------ | --------------------------------------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------- |
| GPS and radius     | `location.gps`, `location.radius`                                     | Blood group, component | Returns matching blood banks within the radius. Group and component default to `All` if omitted |
| State and district | `location.state` (name and code), `location.district` (name and code) | Blood group, component | Returns matching blood banks in that district                                                   |

Support both. GPS returns incomplete results where blood bank density is low, and state and district is the only option when GPS is unavailable.

## search

`context` is the standard UHI block, with `domain` fixed to `nic2008:86906` and `action` set to `search`. Set `city` to `std:011` as the default. The filters live in `message.intent`.

| Field                              | Value                     | What it is                                                     |
| ---------------------------------- | ------------------------- | -------------------------------------------------------------- |
| `item.descriptor.name`             | Blood group name or `All` | The group being searched, for example `O+Ve`                   |
| `item.descriptor.code`             | Blood group code or `-1`  | Numeric code from the master list below. `-1` means all groups |
| `category.descriptor.name`         | Component name            | For example `WholeBlood`, `PlateletConcentrate`                |
| `category.descriptor.code`         | Component code            | Numeric code from the master list below                        |
| `fulfillment.type`                 | `BloodStock`              | Fixed                                                          |
| `fulfillment.start.time.timestamp` | ISO 8601                  | Start of the availability window                               |
| `fulfillment.end.time.timestamp`   | ISO 8601                  | End of the availability window                                 |
| `location.gps`                     | `latitude,longitude`      | Search origin, for GPS mode                                    |
| `location.radius.type`             | `CONSTANT`                | Fixed, for GPS mode                                            |
| `location.radius.value`            | Numeric string            | Radius in km, for example `10.0`                               |
| `location.radius.unit`             | `km`                      | Fixed                                                          |
| `location.state.name`              | State name in capitals    | For example `DELHI`                                            |
| `location.state.code`              | Numeric state code        | For example `7`                                                |
| `location.district.name`           | District name in capitals | For example `SOUTH`                                            |
| `location.district.code`           | Numeric district code     | For example `83`                                               |

### Sample, GPS with a specific group and component

```json
{  "context": {    "domain": "nic2008:86906",    "country": "IND",    "city": "std:011",    "action": "search",    "core_version": "0.7.1",    "consumer_id": "<YOUR_EUA_ID_FROM_NHA_ONBOARDING>",    "consumer_uri": "<YOUR_HTTPS_CALLBACK_URL>",    "message_id": "5cc46ce0-cd96-11ef-957f-718cff4e4e0a",    "timestamp": "2025-01-08T07:58:36.421576Z",    "transaction_id": "5cc46ce0-cd96-11ef-957f-718cff4e4e0a"  },  "message": {    "intent": {      "item": {        "descriptor": { "name": "O+Ve", "code": "15" }      },      "category": {        "descriptor": { "name": "WholeBlood", "code": "11" }      },      "fulfillment": {        "type": "BloodStock",        "start": { "time": { "timestamp": "2025-01-08T13:28:36" } },        "end": { "time": { "timestamp": "2025-01-08T23:59:59" } }      },      "location": {        "gps": "17.3788008,78.4368212",        "radius": { "type": "CONSTANT", "value": "10.0", "unit": "km" }      }    }  }}
```

To search every blood group at once, set `item.descriptor.name` to `All` and `item.descriptor.code` to `-1`.

### Sample, state and district

Replace the `location` block. Everything else is the same.

```json
{  "location": {    "state": { "name": "DELHI", "code": "7" },    "district": { "name": "SOUTH", "code": "83" }  }}
```

## on\_search

| Field                                      | Type    | What it is                                                              |
| ------------------------------------------ | ------- | ----------------------------------------------------------------------- |
| `context.action`                           | string  | `on_search`                                                             |
| `context.provider_id`                      | string  | The responding HSPA                                                     |
| `context.provider_uri`                     | string  | The HSPA's callback URL                                                 |
| `context.transaction_id`                   | string  | Echoed from your search. Use it to correlate                            |
| `catalog.descriptor.name`                  | string  | HSPA or data source name, for example `e-RaktKosh`                      |
| `providers[].id`                           | string  | Unique ID for this blood bank record                                    |
| `providers[].descriptor.name`              | string  | Blood bank name                                                         |
| `providers[].descriptor.short_desc`        | string  | Blood bank type, for example `Govt.`, `Charitable/Vol`                  |
| `providers[].categories[].descriptor.name` | string  | Blood component name                                                    |
| `providers[].categories[].descriptor.code` | string  | Blood component code                                                    |
| `providers[].fulfillments[].type`          | string  | `Available` or `NotAvailable`                                           |
| `providers[].items[].descriptor.name`      | string  | Blood group name                                                        |
| `providers[].items[].descriptor.code`      | string  | Blood group code                                                        |
| `providers[].items[].quantity.count`       | integer | Units available for this group                                          |
| `providers[].items[].fulfillment_id`       | string  | Points at the fulfilment record that says `Available` or `NotAvailable` |
| `providers[].location.gps`                 | string  | Blood bank coordinates                                                  |
| `providers[].location.address`             | string  | Full address                                                            |
| `providers[].location.city.name`           | string  | City                                                                    |
| `providers[].location.state.name`          | string  | State                                                                   |
| `providers[].location.district.name`       | string  | District                                                                |
| `providers[].contact.phone`                | string  | Blood bank phone number                                                 |
| `providers[].contact.email`                | string  | Blood bank email                                                        |

### The part that trips people up

Availability is not a field on the item. Each provider declares a small set of `fulfillments`, one meaning `Available` and one meaning `NotAvailable`. Each blood group item points at one of them through `fulfillment_id`. A group with a unit count of 16 can still be unavailable. Resolve the link before you show a number to a user.

### Sample response

```json
{  "context": {    "domain": "nic2008:86906",    "action": "on_search",    "consumer_id": "<YOUR_EUA_ID_FROM_NHA_ONBOARDING>",    "consumer_uri": "<YOUR_HTTPS_CALLBACK_URL>",    "provider_id": "nha.hspa",    "provider_uri": "https://hspasbx.abdm.gov.in/api/v1/bloodbank",    "transaction_id": "c51c2800-cd96-11ef-957f-718cff4e4e0a",    "message_id": "c51c2800-cd96-11ef-957f-718cff4e4e0a"  },  "message": {    "catalog": {      "descriptor": {        "name": "e-RaktKosh",        "short_desc": "e-RaktKosh: A Centralized Blood Bank Management System"      },      "providers": [        {          "id": "0",          "descriptor": {            "name": "Janseva Blood Centre",            "short_desc": "Charitable/Vol"          },          "categories": [            { "id": "0", "descriptor": { "name": "WholeBlood", "code": "11" } }          ],          "fulfillments": [            { "id": "0", "type": "NotAvailable" },            { "id": "1", "type": "Available" }          ],          "items": [            {              "id": "0",              "descriptor": { "name": "O+Ve", "code": "15" },              "quantity": { "count": 2 },              "category_id": "0",              "fulfillment_id": "1"            },            {              "id": "1",              "descriptor": { "name": "AB+Ve", "code": "17" },              "quantity": { "count": 16 },              "category_id": "0",              "fulfillment_id": "0"            }          ],          "location": {            "gps": "18.5246036,73.792927",            "address": "Paud Road, Pune, Maharashtra",            "city": { "name": "Pune" },            "state": { "name": "Maharashtra", "code": "27" },            "district": { "name": "Pune", "code": "521" }          },          "contact": {            "phone": "<MOBILE_NUMBER>",            "email": "contact@example.org"          }        }      ]    }  }}
```

In that response `O+Ve` points at fulfilment `1`, which is `Available`. `AB+Ve` has a count of 16 but points at fulfilment `0`, which is `NotAvailable`.

## Blood group master list

Use these in `item.descriptor.code`.

| Code | Group |
| ---- | ----- |
| `-1` | All   |
| `11` | A+Ve  |
| `12` | A-Ve  |
| `13` | B+Ve  |
| `14` | B-Ve  |
| `15` | O+Ve  |
| `16` | O-Ve  |
| `17` | AB+Ve |
| `18` | AB-Ve |
| `22` | Oh+Ve |
| `23` | Oh-Ve |

## Blood component master list

Use these in `category.descriptor.code`.

| Code | Component                    |
| ---- | ---------------------------- |
| `11` | Whole Blood                  |
| `12` | Packed Red Blood Cells       |
| `13` | Fresh Frozen Plasma          |
| `14` | Single Donor Platelet        |
| `16` | Platelet Rich Plasma         |
| `17` | Cryoprecipitate              |
| `18` | Single Donor Plasma          |
| `19` | Plasma                       |
| `20` | Platelet Concentrate         |
| `21` | Cryo Poor Plasma             |
| `23` | Random Donor Platelets       |
| `24` | Platelets Additive Solutions |
| `28` | SAGM Packed Red Blood Cells  |
| `29` | Irradiated RBC               |
| `30` | Leukoreduced RBC             |

## Known limitations

| Limitation                                                                    | What to do about it                                                                                     |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| GPS search returns incomplete results where blood bank density is low         | Offer state and district as a visible alternative, not a hidden fallback                                |
| Update frequency varies by blood bank. Some update in real time, others daily | Show a disclaimer that counts are indicative and may have changed. Tell users to call before travelling |
| Responses arrive asynchronously with no end signal                            | Use a 10 to 15 second timeout and render results as they arrive                                         |
| No pagination on `on_search`                                                  | Expect large payloads. Paginate or lazy load on the client                                              |
| No booking or reservation                                                     | Show the blood bank phone number prominently                                                            |

## Prerequisites

For an EUA:

- [ABDM](/docs/uhi/v1/getting-started/glossary#abdm) [M2](/docs/hiecm/v3/api/m2) with [HIE-CM](/docs/uhi/v1/getting-started/glossary#hie-cm) completed. This is a hard prerequisite for any UHI service.
- A publicly reachable HTTPS `consumer_uri`.
- Ed25519 signing with BLAKE-512 body hashing.
- Asynchronous handling. Do not block on a synchronous reply to `search`.

For an HSPA:

- An independently maintained blood bank database with real-time or near real-time inventory, comparable in scope and quality to e-RaktKosh.
- A publicly reachable HTTPS `provider_uri` to receive searches from the gateway.
- Ed25519 signing on every outbound response.
- Sandbox integration and written sign-off before production.

## What is missing here

- No error code list is published for this service.
- No response time SLA is published for HSPAs beyond an acceptable latency window.
- State and district codes are issued at onboarding. Delhi is `7` and South district is `83`.

## Next

- [UHI services](/docs/uhi/v1) for the shared protocol
- [Ambulance booking](/docs/uhi/v1/concepts/services/ambulance-booking)
- [Physical consultation](/docs/uhi/v1/concepts/services/physical-consultation)
- [Support](/docs/support)


---

# Jan Aushadhi Kendra discovery

Jan Aushadhi Kendras are the government generic medicine stores run under the Pradhan Mantri Bhartiya Janaushadhi Pariyojana. After this page you will know the five ways to search for one and every field that comes back.

## Who does what

Three parties. Shared roles, signing and onboarding are on [UHI services](/docs/uhi/v1).

| Party                                                    | Who runs it                                                      | What it does here                                                                           |
| -------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [EUA](/docs/uhi/v1/getting-started/glossary#eua)         | You, or any [PHR](/docs/uhi/v1/getting-started/glossary#phr) app | Sends the `search`. Receives the `on_search` on your callback URL. Renders the Kendra list. |
| [UHI](/docs/uhi/v1/getting-started/glossary#uhi) Gateway | [NHA](/docs/uhi/v1/getting-started/glossary#nha)                 | Validates and routes the `search`. Relays the `on_search` back to you.                      |
| [HSPA](/docs/uhi/v1/getting-started/glossary#hspa)       | PMBI, the Pharmaceuticals and Medical Devices Bureau of India    | Queries the PMBI Kendra database. Builds the `on_search` catalog.                           |

You do not build a [HSPA](/docs/uhi/v1/getting-started/glossary#hspa) unless you are PMBI or their technology partner.

## Message flow

Two calls, asynchronous, discovery only. There is no booking and no ordering. The HTTP 200 from the Gateway is a receipt, not the result.

| Step | Who acts    | What happens                                                                                                 |
| ---- | ----------- | ------------------------------------------------------------------------------------------------------------ |
| 1    | Your system | The user taps "Find Jan Aushadhi Kendra". You build a `search` with your filters and POST it to the Gateway. |
| 2    | Gateway     | Returns HTTP 200 ACK to you straight away. Forwards the `search` to the PMBI HSPA.                           |
| 3    | PMBI HSPA   | Queries the Kendra database against your filters.                                                            |
| 4    | PMBI HSPA   | POSTs an `on_search` to the Gateway with a catalog of matching Kendras.                                      |
| 5    | Gateway     | POSTs the `on_search` to your `consumer_uri`.                                                                |
| 6    | Your system | ACKs the `on_search` and renders the list.                                                                   |

Match the `on_search` to its request by `context.transaction_id`, which the HSPA copies from your `search`. Your `consumer_uri` must be a publicly reachable HTTPS endpoint.

## Service identity

Fixed for this service. These values route your `search` to PMBI rather than to a teleconsultation or ambulance provider.

| Parameter                    | Value                                                     | Where it goes                                           |
| ---------------------------- | --------------------------------------------------------- | ------------------------------------------------------- |
| `domain`                     | `nic2008:47721`                                           | `context.domain` in every call                          |
| `fulfillment.type`           | `JANAUSHADHI`                                             | `message.intent.fulfillment.type`                       |
| `item.descriptor.code`       | `JANAUSHADHI`                                             | `message.intent.item.descriptor.code`                   |
| `item.descriptor.name`       | `JANAUSHADHI`                                             | `message.intent.item.descriptor.name`                   |
| Provider ID                  | `pmbi.hspa`                                               | Identifies the PMBI HSPA on the network                 |
| Provider URL                 | `https://nha-pmbi.pmbi.co.in/api/store`                   | The PMBI HSPA endpoint registered with NHA              |
| HSPA public key ID           | `pmbi.hspapid.jak`                                        | The Gateway uses it to verify PMBI's response signature |
| Gateway base URL, sandbox    | `https://uhigatewaysandbox.abdm.gov.in/api/v1/uhi/search` | Append `/search` or `/on_search` to the base path       |
| Gateway base URL, production | `https://uhigateway.abdm.gov.in/api/v1/uhi/search`        | Append `/search` or `/on_search` to the base path       |

## Search filters

There is no mandatory location filter. All five filter shapes below are independent, and they combine.

| Search type           | Fields used                                                                                      | Use case                             |
| --------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------ |
| By Kendra code        | `category.descriptor.code`, `category.descriptor.name`                                           | Look up one Kendra by its PMBJP code |
| By state and district | `location.state.code`, `location.state.name`, `location.district.code`, `location.district.name` | All Kendras in a district            |
| By pincode            | `address.area_code`                                                                              | Kendras in a 6 digit pincode area    |
| By GPS and radius     | `location.gps`, `location.radius.type`, `location.radius.value`, `location.radius.unit`          | Kendras near the user                |
| Combined              | state, district and `address.area_code` together                                                 | Narrow to a sub area of a district   |

Note that `address` sits beside `location` inside `message.intent`, not inside it.

## Sample payloads

The `context` block is the same in all five variants. Only `message.intent` changes. Fill in your own `consumer_id`, `consumer_uri`, `message_id`, `transaction_id` and `timestamp`.

### Search by Kendra code

```json
{  "context": {    "domain": "nic2008:47721",    "country": "IND",    "city": "std:011",    "action": "search",    "core_version": "0.7.1",    "consumer_id": "<YOUR_EUA_ID_FROM_NHA_ONBOARDING>",    "consumer_uri": "<YOUR_HTTPS_CALLBACK_URL>",    "message_id": "<FRESH_UUID_PER_CALL>",    "timestamp": "2026-06-09T18:24:35",    "transaction_id": "<FRESH_UUID_PER_SEARCH_SESSION>"  },  "message": {    "intent": {      "category": {        "descriptor": {          "code": "PMBJK02129",          "name": "PMBJK02129"        }      },      "fulfillment": {        "type": "JANAUSHADHI",        "start": { "time": { "timestamp": "2026-06-19T00:00:00" } },        "end": { "time": { "timestamp": "2026-06-19T23:59:59" } }      },      "item": {        "descriptor": { "code": "JANAUSHADHI", "name": "JANAUSHADHI" }      }    }  }}
```

Confirm what goes in `category.descriptor` before you build this one. See [Confirm at onboarding](#confirm-at-onboarding) below.

### Search by state and district

Replace the `category` block with a `location` block.

```json
{  "message": {    "intent": {      "fulfillment": {        "type": "JANAUSHADHI",        "start": { "time": { "timestamp": "2026-06-09T00:00:00" } },        "end": { "time": { "timestamp": "2026-06-09T23:59:59" } }      },      "item": {        "descriptor": { "code": "JANAUSHADHI", "name": "JANAUSHADHI" }      },      "location": {        "district": { "code": "509", "name": "KHAMMAM" },        "state": { "code": "36", "name": "Telangana" }      }    }  }}
```

### Search by pincode

```json
{  "message": {    "intent": {      "fulfillment": {        "type": "JANAUSHADHI",        "start": { "time": { "timestamp": "2026-06-19T00:00:00" } },        "end": { "time": { "timestamp": "2026-06-19T23:59:59" } }      },      "item": {        "descriptor": { "code": "JANAUSHADHI", "name": "JANAUSHADHI" }      },      "address": { "area_code": "500028" }    }  }}
```

### Search by GPS and radius

```json
{  "message": {    "intent": {      "fulfillment": {        "type": "JANAUSHADHI",        "start": { "time": { "timestamp": "2026-06-09T00:00:00" } },        "end": { "time": { "timestamp": "2026-06-09T23:59:59" } }      },      "item": {        "descriptor": { "code": "JANAUSHADHI", "name": "JANAUSHADHI" }      },      "location": {        "gps": "17.39916197665472, 78.43400530708318",        "radius": { "type": "CONSTANT", "value": "5", "unit": "km" }      }    }  }}
```

### Combined filters

```json
{  "message": {    "intent": {      "fulfillment": {        "type": "JANAUSHADHI",        "start": { "time": { "timestamp": "2026-06-19T00:00:00" } },        "end": { "time": { "timestamp": "2026-06-19T23:59:59" } }      },      "item": {        "descriptor": { "code": "JANAUSHADHI", "name": "JANAUSHADHI" }      },      "location": {        "district": { "code": "507", "name": "HYDERABAD" },        "state": { "code": "36", "name": "Telangana" }      },      "address": { "area_code": "500028" }    }  }}
```

### on\_search response

PMBI sends this to your `consumer_uri` through the Gateway. Each entry in `catalog.providers` is one enrolled Kendra. Shortened here to one record.

```json
{  "context": {    "domain": "nic2008:47721",    "country": "IND",    "city": "std:011",    "action": "on_search",    "core_version": "0.7.1",    "consumer_id": "nha.eua",    "consumer_uri": "https://uhieuasandbox.abdm.gov.in/api/v1/euaService",    "provider_id": "pmbi.hspa",    "provider_uri": "https://staging-nha-pmbi.pmbi.co.in/api/store",    "message_id": "e9a19230-f951-11ec-b135-53aea776f66b",    "timestamp": "2026-06-09T18:24:35",    "transaction_id": "e9a19230-f951-11ec-b135-53aea776f66b"  },  "message": {    "catalog": {      "descriptor": {        "name": "JAN AUSHADHI KENDRA HSPA",        "images": "https://janaushadhi.gov.in/img/bhartiya_janaushadhi_priyojna_2.svg",        "short_desc": "",        "long_desc": ""      },      "providers": [        {          "id": "PMBJK10844",          "descriptor": {            "name": "Jan Aushadhi Kendra",            "code": "PP",            "symbol": "1",            "short_desc": "",            "long_desc": ""          },          "fulfillments": [            {              "id": "0",              "type": "contact",              "agent": { "name": "Sunita Zanwar" },              "start": { "time": { "timestamp": "2023-06-30T00:00:00" } }            }          ],          "location": {            "id": "1",            "descriptor": { "name": "Jan Aushadhi Kendra" },            "city": { "name": "", "code": "" },            "district": { "name": "PUNE", "code": "490" },            "state": { "name": "Maharashtra", "code": "27" },            "country": { "name": "INDIA", "code": "+91" },            "gps": "18.51996721338908,73.86697649999999",            "address": "Shop No.2, CTS No.350, Sai Appartment, Near KEM Hospital Rasta Peth, Pune, Pune, Maharashtra, India - 411011",            "radius": { "type": "CONSTANT", "value": "1.19", "unit": "km" }          },          "contact": {            "phone": "<MOBILE_NUMBER>",            "email": "contact@example.org"          }        }      ]    }  }}
```

## Field reference

### search: context

All fields are mandatory. The block is identical across every variant.

| Field            | Type     | Value                                                |
| ---------------- | -------- | ---------------------------------------------------- |
| `domain`         | string   | `nic2008:47721`, fixed                               |
| `country`        | string   | `IND`, fixed                                         |
| `city`           | string   | STD code, for example `std:011`                      |
| `action`         | string   | `search`, fixed                                      |
| `core_version`   | string   | `0.7.1`                                              |
| `consumer_id`    | string   | Your registered EUA identifier                       |
| `consumer_uri`   | string   | Your HTTPS callback URL                              |
| `message_id`     | UUID     | Fresh per call. Never reuse.                         |
| `transaction_id` | UUID     | Fresh per search session. The `on_search` copies it. |
| `timestamp`      | ISO 8601 | Request time, for example `2026-06-09T18:24:35`      |

### search: message.intent

| Field path                         | Type            | Mandatory   | Description                                     |
| ---------------------------------- | --------------- | ----------- | ----------------------------------------------- |
| `fulfillment.type`                 | string          | Yes         | `JANAUSHADHI`, fixed                            |
| `fulfillment.start.time.timestamp` | datetime        | Yes         | Start of the search window                      |
| `fulfillment.end.time.timestamp`   | datetime        | Yes         | End of the search window                        |
| `item.descriptor.code`             | string          | Yes         | `JANAUSHADHI`, fixed                            |
| `item.descriptor.name`             | string          | Yes         | `JANAUSHADHI`, fixed                            |
| `category.descriptor.code`         | string          | Conditional | Set when searching by Kendra code               |
| `category.descriptor.name`         | string          | Conditional | Set when searching by Kendra code               |
| `location.state.name`              | string          | No          | State name, for example `Maharashtra`           |
| `location.state.code`              | string          | No          | Numeric state code, for example `27`            |
| `location.district.name`           | string          | No          | District name, for example `Ahmednagar`         |
| `location.district.code`           | string          | No          | Numeric district code, for example `466`        |
| `location.gps`                     | string          | No          | `lat,long`, for example `19.7126974,74.4833288` |
| `location.radius.type`             | string          | No          | `CONSTANT`. Required with a GPS search.         |
| `location.radius.value`            | string or float | No          | Radius in km, for example `5`                   |
| `location.radius.unit`             | string          | No          | `km`                                            |
| `address.area_code`                | string          | No          | 6 digit pincode, for example `413736`           |

### on\_search: provider records

| Field path                                                | Type     | Description                                                                                                                                      |
| --------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `catalog.providers[].id`                                  | string   | PMBJP Kendra code, for example `PMBJK01460`                                                                                                      |
| `catalog.providers[].descriptor.name`                     | string   | Kendra name                                                                                                                                      |
| `catalog.providers[].descriptor.code`                     | string   | Ownership type: `PP` private-private, `PG` private-government, `GG` government-government. Treat the list as incomplete.                         |
| `catalog.providers[].descriptor.symbol`                   | string   | Serial number assigned by PMBI                                                                                                                   |
| `catalog.providers[].descriptor.short_desc`               | string   | May be empty                                                                                                                                     |
| `catalog.providers[].descriptor.long_desc`                | string   | May be empty                                                                                                                                     |
| `catalog.providers[].fulfillments[].type`                 | string   | `contact`. This block carries the contact person.                                                                                                |
| `catalog.providers[].fulfillments[].agent.name`           | string   | Contact person at the Kendra                                                                                                                     |
| `catalog.providers[].fulfillments[].start.time.timestamp` | datetime | PMBJP enrolment date                                                                                                                             |
| `catalog.providers[].location.gps`                        | string   | `lat,long` of the Kendra                                                                                                                         |
| `catalog.providers[].location.address`                    | string   | Full street address                                                                                                                              |
| `catalog.providers[].location.city.name`                  | string   | May be empty                                                                                                                                     |
| `catalog.providers[].location.city.code`                  | string   | May be empty                                                                                                                                     |
| `catalog.providers[].location.district.name`              | string   | District name                                                                                                                                    |
| `catalog.providers[].location.district.code`              | string   | District code                                                                                                                                    |
| `catalog.providers[].location.state.name`                 | string   | State name                                                                                                                                       |
| `catalog.providers[].location.state.code`                 | string   | State code                                                                                                                                       |
| `catalog.providers[].location.radius`                     | object   | A distance with a unit, for example `1.19 km`. Present in responses, absent from the field reference, so what it is measured from is not stated. |
| `catalog.providers[].location.country.name`               | string   | `INDIA`, fixed                                                                                                                                   |
| `catalog.providers[].location.country.code`               | string   | `+91`, fixed                                                                                                                                     |
| `catalog.providers[].contact.phone`                       | string   | Kendra phone number                                                                                                                              |
| `catalog.providers[].contact.email`                       | string   | May be empty                                                                                                                                     |

## Confirm at onboarding

Two values are settled when you onboard. Build the flow and hold these until your onboarding contact confirms them.

- **What goes in `category.descriptor` for a Kendra code search.** Both the Kendra code itself, for example `PMBJK02129`, and the literal string `Jan Aushadhi Kendra Code` are in circulation. Confirm which the HSPA accepts before you ship a Kendra code search.
- **The HSPA identity in `on_search`.** Route on `transaction_id`, not on `provider_id`, so a change of provider host does not break your matching.

## Next

- Searching for a medicine, then for the Kendras that stock it: [Jan Aushadhi medicine search](/docs/uhi/v1/concepts/services/jan-aushadhi-medicine-search)
- Shared UHI protocol, signing and onboarding: [UHI services](/docs/uhi/v1)


---

# Jan Aushadhi medicine search

This is the two step version of Jan Aushadhi discovery: your user searches for a medicine by name, then you search again for the Kendras that carry it, with a stock flag on each. After this page you will know what changes from [Jan Aushadhi Kendra discovery](/docs/uhi/v1/concepts/services/jan-aushadhi-kendra), which is `fulfillment.type` and `item.descriptor` and nothing else.

## Who does what

The same three parties as every [UHI](/docs/uhi/v1/getting-started/glossary#uhi) service. Your app is the [EUA](/docs/uhi/v1/getting-started/glossary#eua). [NHA](/docs/uhi/v1/getting-started/glossary#nha) runs the Gateway. PMBI runs the [HSPA](/docs/uhi/v1/getting-started/glossary#hspa) that holds the medicine and stock data. Signing, onboarding and the Gateway base URLs are on [UHI services](/docs/uhi/v1).

## Message flow

Two round trips, four calls in total. Each `search` gets an immediate HTTP 200 ACK from the Gateway, and the real answer arrives later on your `consumer_uri`.

| Step | Call        | Who acts              | What comes back                                                                        |
| ---- | ----------- | --------------------- | -------------------------------------------------------------------------------------- |
| 1    | `search`    | Your system           | ACK. The medicine catalogue arrives separately.                                        |
| 2    | `on_search` | PMBI HSPA via Gateway | Matching generic medicines, each with an ID, item code, price and pack size.           |
| 3    | `search`    | Your system           | ACK. You send the medicine ID your user picked, plus a location filter.                |
| 4    | `on_search` | PMBI HSPA via Gateway | Kendras that carry that medicine, each with an `items[]` entry holding the stock flag. |

Both `on_search` responses carry the `transaction_id` of the `search` that triggered them. Use two separate `transaction_id` values, one per step, so you can tell the two responses apart.

## Service identity

`domain` is the same as Kendra discovery. `fulfillment.type` is not.

| Step                        | `domain`        | `fulfillment.type`     | `item.descriptor.code` and `.name` |
| --------------------------- | --------------- | ---------------------- | ---------------------------------- |
| Medicine search             | `nic2008:47721` | `JANAUSHADHI_MEDICINE` | The medicine name                  |
| Kendras stocking a medicine | `nic2008:47721` | `JANAUSHADHI_KENDRA`   | The `medicineId` from step 1       |

A plain Kendra search uses `JANAUSHADHI`. The two values `JANAUSHADHI_MEDICINE` and `JANAUSHADHI_KENDRA` apply to the medicine search document. See [Confirm at onboarding](#confirm-at-onboarding).

## Step 1: search by medicine name

Put the medicine name in `item.descriptor`. The code is the name with spaces removed, and the name keeps its spaces.

```json
{  "context": {    "domain": "nic2008:47721",    "country": "IND",    "city": "std:011",    "action": "search",    "core_version": "0.7.1",    "consumer_id": "<YOUR_EUA_ID_FROM_NHA_ONBOARDING>",    "consumer_uri": "<YOUR_HTTPS_CALLBACK_URL>",    "message_id": "<FRESH_UUID_PER_CALL>",    "timestamp": "2026-06-09T18:24:35",    "transaction_id": "<FRESH_UUID_PER_SEARCH_SESSION>"  },  "message": {    "intent": {      "fulfillment": {        "type": "JANAUSHADHI_MEDICINE",        "start": { "time": { "timestamp": "2026-06-09T00:00:00" } },        "end": { "time": { "timestamp": "2026-06-09T23:59:59" } }      },      "item": {        "descriptor": {          "code": "<MEDICINE_NAME_WITHOUT_SPACES>",          "name": "<MEDICINE_NAME>"        }      }    }  }}
```

### on\_search: the medicine catalogue

Each `providers[]` entry is one generic medicine, not a store. The `items[]` array inside it carries price and pack size.

```json
{  "context": {    "domain": "nic2008:47721",    "country": "IND",    "city": "std:011",    "action": "on_search",    "core_version": "0.7.1",    "consumer_id": "eua-nha",    "consumer_uri": "http://uhieuasandbox.abdm.gov.in/api/v1/euaService",    "provider_id": "janaushadhi-hspa",    "provider_uri": "https://janaushadhi.gov.in:8443/api/v1/admin/kendra/",    "message_id": "e9a19230-f951-11ec-b135-53aea776f66b",    "timestamp": "2026-06-09T18:24:35",    "transaction_id": "e9a19230-f951-11ec-b135-53aea776f66b"  },  "message": {    "catalog": {      "descriptor": {        "name": "JAN AUSHADHI KENDRA HSPA",        "images": "<HSPA_LOGO_IMAGE_URL_SET_BY_PMBI>",        "short_desc": "<HSPA_SHORT_DESCRIPTION_SET_BY_PMBI>",        "long_desc": "<HSPA_LONG_DESCRIPTION_SET_BY_PMBI>"      },      "providers": [        {          "id": "78299",          "descriptor": {            "name": "3-way stopcock with 10 cm extension line",            "code": "8150.0",            "symbol": "",            "short_desc": "",            "long_desc": ""          },          "items": [            {              "id": "0",              "price": { "currency": "INR", "value": "20.0" },              "quantity": { "measure": { "value": 10, "unit": "s" } }            }          ]        }      ]    }  }}
```

Sample values appear on this page as the value only, without the annotation pair. The `catalog.descriptor` fields carry descriptive prose rather than real values, so they appear here as written.

| Field path                                           | Type   | Description                                                           |
| ---------------------------------------------------- | ------ | --------------------------------------------------------------------- |
| `catalog.providers[].id`                             | string | `medicineId`. This is what you send back in step 2.                   |
| `catalog.providers[].descriptor.name`                | string | Generic name of the medicine                                          |
| `catalog.providers[].descriptor.code`                | string | PMBI item code, for example `8150.0`                                  |
| `catalog.providers[].items[].price.currency`         | string | `INR`                                                                 |
| `catalog.providers[].items[].price.value`            | string | MRP                                                                   |
| `catalog.providers[].items[].quantity.measure.value` | number | Unit size, for example `10`                                           |
| `catalog.providers[].items[].quantity.measure.unit`  | string | Unit of the pack: `s`, `ml`, `sachet`, `drops`, `mg` or `tetra pack`. |

## Step 2: search for Kendras stocking that medicine

Change `fulfillment.type` to `JANAUSHADHI_KENDRA` and put the `medicineId` in `item.descriptor`. Add whichever location filter your user chose: state and district, pincode, or GPS and radius. The filter fields are the same as on [Jan Aushadhi Kendra discovery](/docs/uhi/v1/concepts/services/jan-aushadhi-kendra).

```json
{  "context": {    "domain": "nic2008:47721",    "country": "IND",    "city": "std:011",    "action": "search",    "core_version": "0.7.1",    "consumer_id": "<YOUR_EUA_ID_FROM_NHA_ONBOARDING>",    "consumer_uri": "<YOUR_HTTPS_CALLBACK_URL>",    "message_id": "<FRESH_UUID_PER_CALL>",    "timestamp": "2026-06-19T18:24:35",    "transaction_id": "<FRESH_UUID_PER_SEARCH_SESSION>"  },  "message": {    "intent": {      "fulfillment": {        "type": "JANAUSHADHI_KENDRA",        "start": { "time": { "timestamp": "2026-06-19T00:00:00" } },        "end": { "time": { "timestamp": "2026-06-19T23:59:59" } }      },      "item": {        "descriptor": {          "code": "78299",          "name": "78299"        }      },      "location": {        "district": { "code": "507", "name": "HYDERABAD" },        "state": { "code": "36", "name": "Telangana" }      }    }  }}
```

### on\_search: Kendras with stock

Kendra records, the same shape as Kendra discovery, with one addition: each Kendra carries an `items[]` entry for the medicine you asked about, and that entry has a `flag` for stock.

```json
{  "context": {    "domain": "nic2008:47721",    "country": "IND",    "city": "std:011",    "action": "on_search",    "core_version": "0.7.1",    "consumer_id": "eua-nha",    "consumer_uri": "http://uhieuasandbox.abdm.gov.in/api/v1/euaService",    "provider_id": "janaushadhi-hspa",    "provider_uri": "https://janaushadhi.gov.in:8443/api/v1/admin/kendra/",    "message_id": "e9a19230-f951-11ec-b135-53aea776f66b",    "timestamp": "2026-06-09T18:24:35",    "transaction_id": "e9a19230-f951-11ec-b135-53aea776f66b"  },  "message": {    "catalog": {      "descriptor": {        "name": "JAN AUSHADHI KENDRA HSPA",        "images": "<HSPA_LOGO_IMAGE_URL_SET_BY_PMBI>",        "short_desc": "<HSPA_SHORT_DESCRIPTION_SET_BY_PMBI>",        "long_desc": "<HSPA_LONG_DESCRIPTION_SET_BY_PMBI>"      },      "providers": [        {          "id": "PMBJK01472",          "descriptor": {            "name": "Jan Aushadhi Kendra2",            "code": "PP",            "symbol": "2",            "short_desc": "",            "long_desc": ""          },          "fulfillments": [            {              "id": "0",              "type": "contact",              "agent": { "name": "GOPAL RAMBHAU KARALE" },              "start": { "time": { "timestamp": "2018-03-22T12:00:00" } }            }          ],          "items": [            {              "id": "78299",              "descriptor": {                "name": "3-way stopcock with 10 cm extension line",                "code": "8150.0",                "symbol": "",                "short_desc": "",                "flag": false              },              "quantity": { "measure": { "value": 10, "unit": "s" } }            }          ],          "location": {            "id": "1",            "descriptor": { "name": "Jan Aushadhi Kendra2" },            "city": { "name": "", "code": "" },            "district": { "name": "Akola", "code": "467" },            "state": { "name": "Maharashtra", "code": "27" },            "country": { "name": "INDIA", "code": "+91" },            "gps": "20.6838699,77.02622334",            "address": "Shop no.1 basement, Radha Krishna complex, behind Harsh sankul, opp. S.A.college",            "radius": { "type": "CONSTANT", "value": "0.4", "unit": "km" }          },          "contact": { "phone": "<MOBILE_NUMBER>", "email": "" }        }      ]    }  }}
```

The fields that are new compared with a plain Kendra record:

| Field path                                           | Type    | Description                                                                                          |
| ---------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `catalog.providers[].items[].id`                     | string  | `medicineId`, matching the one you sent                                                              |
| `catalog.providers[].items[].descriptor.name`        | string  | Generic name of the medicine                                                                         |
| `catalog.providers[].items[].descriptor.code`        | string  | PMBI item code                                                                                       |
| `catalog.providers[].items[].descriptor.flag`        | boolean | Stock indicator for this medicine at this Kendra                                                     |
| `catalog.providers[].items[].quantity.measure.value` | number  | Unit size                                                                                            |
| `catalog.providers[].items[].quantity.measure.unit`  | string  | Unit of the pack                                                                                     |
| `catalog.providers[].location.radius`                | object  | A distance with a unit, for example `0.4 km`. Present in responses, absent from the field reference. |

Every other field on the provider record is documented in the [Kendra discovery field reference](/docs/uhi/v1/concepts/services/jan-aushadhi-kendra#field-reference).

`flag` arrives as `false` on both sample records. Confirm its polarity with your onboarding contact before you render "in stock" or "out of stock" to a user.

## Confirm at onboarding

Four values are issued or confirmed when you onboard. Build the flow, and hold these until your onboarding contact confirms them.

- **The service type value.** Send the value your onboarding pack gives. Both `JANAUSHADHI` and `JANAUSHADHI_MEDICINE` are in circulation for this search.
- **The polarity of `descriptor.flag`.** It arrives as `false` on stocked and unstocked records alike. Do not render "in stock" or "out of stock" from it until the polarity is confirmed.
- **Whether a location filter is accepted.** The medicine search sends the medicine name in `item.descriptor` and no `location` block. Send the name only.
- **The HSPA identity.** Route on `transaction_id`, not on `provider_id`, so a change of provider host does not break your matching.

## Next

- Kendra discovery without a medicine filter: [Jan Aushadhi Kendra discovery](/docs/uhi/v1/concepts/services/jan-aushadhi-kendra)
- Shared UHI protocol, signing and onboarding: [UHI services](/docs/uhi/v1)


---

# Physical consultation

Physical consultation is the fullest service on [UHI](/docs/uhi/v1/getting-started/glossary#uhi). A patient searches for a doctor, then sees real slots and fees from clinics they have no prior relationship with. They book one, and receive a 4-digit PIN to present at the clinic. After this page you will know the four stages, the endpoints each role exposes, and the fields on every call, as [NHA](/docs/uhi/v1/getting-started/glossary#nha) documents them.

Read [UHI services](/docs/uhi/v1) first, for the `context` block, the acknowledgement model, signing and the two transports.

## Where this service stands

The full consultation lifecycle is the first phase, live and open for onboarding. Online payment and refunds are the second phase, in ideation. Today the only payment model is pay on visit.

## Service identity

Every call in this service carries these fixed values.

| Field                                 | Value                       |
| ------------------------------------- | --------------------------- |
| `context.domain`                      | `nic2004:85111`             |
| `context.core_version`                | `0.7.1`                     |
| `message.intent.fulfillment.type`     | `Physical` (case sensitive) |
| `message.intent.item.descriptor.code` | `Consultation`              |
| `message.intent.item.descriptor.name` | `Consultation`              |

## Who is involved

| Actor                                                    | Role here                                                                                                           |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| [EUA](/docs/uhi/v1/getting-started/glossary#eua)         | The patient facing app. Searches, books, shows the PIN and the status.                                              |
| [HSPA](/docs/uhi/v1/getting-started/glossary#hspa)       | The provider platform. Holds doctor profiles and slots, confirms bookings, generates the PIN, drives the lifecycle. |
| HSP                                                      | The hospital, clinic or doctor. The HSPA is its digital interface.                                                  |
| [Gateway](/docs/uhi/v1/getting-started/glossary#gateway) | The routing layer. Involved in discovery only.                                                                      |
| NHA                                                      | Network operator. Governs onboarding, compliance and the protocol.                                                  |

## The flow end to end

```mermaid
sequenceDiagram
    participant P as Patient
    participant EUA as Your EUA
    participant GW as HIE-CM gateway
    participant H as HSPA
    P->>EUA: Search for a cardiologist
    EUA->>GW: search (broadcast)
    GW->>H: search
    H->>GW: on_search (doctor catalog)
    GW->>EUA: on_search
    P->>EUA: Pick Dr Mehra
    EUA->>H: search (direct, for that doctor's slots)
    H->>EUA: on_search (slots)
    P->>EUA: Pick a slot
    EUA->>H: init
    H->>EUA: on_init (order id, quote, 5 terms)
    P->>EUA: Agree to terms
    EUA->>H: confirm (all terms AGREED)
    H->>EUA: on_confirm (CONFIRMED, 4-digit PIN)
    Note over P,H: Patient visits the clinic and shows the PIN
    H->>EUA: on_update (APPOINTMENT_STARTED)
    H->>EUA: on_update (COMPLETED)
```

## Stage by stage

| Stage              | Calls                                      | Transport                                      |
| ------------------ | ------------------------------------------ | ---------------------------------------------- |
| 1. Discovery       | `search` and `on_search`, twice            | First pair via the gateway, second pair direct |
| 2. Booking         | `init`, `on_init`, `confirm`, `on_confirm` | Direct                                         |
| 3. Fulfilment      | `status`, `on_status`, `on_update`         | Direct                                         |
| 4. Post-fulfilment | `cancel`, `on_cancel`, `on_message`        | Direct                                         |

## Endpoints you expose

An HSPA exposes these. Everything except the first `search` is called by an EUA directly.

| Endpoint           | Called by                                         | What you do                                              |
| ------------------ | ------------------------------------------------- | -------------------------------------------------------- |
| `/search` (first)  | Gateway broadcast, with `X-Gateway-Authorization` | Query your doctor catalog, answer via `on_search`        |
| `/search` (second) | EUA, direct                                       | Return slots for the selected doctor                     |
| `/init`            | EUA, direct                                       | Hold the slot, answer with terms via `on_init`           |
| `/confirm`         | EUA, direct                                       | Confirm the appointment, return the PIN via `on_confirm` |
| `/status`          | EUA, direct                                       | Return the current order state via `on_status`           |
| `/cancel`          | EUA, direct                                       | Process the cancellation, answer via `on_cancel`         |
| `/on_update`       | EUA, direct                                       | Receive a `DOCTOR_NO_SHOW` state from the EUA            |
| `/on_message`      | EUA, direct                                       | Receive a chat message or file from the patient          |

An EUA exposes these. Everything except the first `on_search` is called by the HSPA directly.

| Endpoint              | Called by                               | What you do                                              |
| --------------------- | --------------------------------------- | -------------------------------------------------------- |
| `/on_search` (first)  | Gateway, with `X-Gateway-Authorization` | Aggregate catalogs, store each `provider_uri`            |
| `/on_search` (second) | HSPA, direct                            | Show the slots for the chosen doctor                     |
| `/on_init`            | HSPA, direct                            | Show all terms to the patient, store `order.id`          |
| `/on_confirm`         | HSPA, direct                            | Show the PIN, store the order                            |
| `/on_status`          | HSPA, direct                            | Replace your stored order state                          |
| `/on_update`          | HSPA, direct                            | Update state and notify the patient                      |
| `/on_cancel`          | HSPA, direct                            | Mark the appointment cancelled                           |
| `/on_message`         | HSPA, direct                            | Show the message from the provider. Mandatory for an EUA |

## Stage 1: discovery

### First search, broadcast

Your EUA posts to the gateway. The gateway validates your signature and the domain, then forwards to every registered HSPA in that domain. Search filters go in `message.intent`.

```http
POST https://uhigatewaysandbox.abdm.gov.in/api/v1/uhi/search
```

| Field                              | Type     | Required    | What it is                                                                                   |
| ---------------------------------- | -------- | ----------- | -------------------------------------------------------------------------------------------- |
| `fulfillment.type`                 | string   | Yes         | `Physical`. Case sensitive                                                                   |
| `fulfillment.agent.name`           | string   | No          | Doctor name, for a name search                                                               |
| `fulfillment.agent.id`             | string   | No          | Doctor [HPR](/docs/uhi/v1/getting-started/glossary#hpr) address, for example `<HPR_ADDRESS>` |
| `fulfillment.start.time.timestamp` | datetime | Yes         | Start of the search window                                                                   |
| `fulfillment.end.time.timestamp`   | datetime | Yes         | End of the search window                                                                     |
| `item.descriptor.code`             | string   | Yes         | `Consultation`                                                                               |
| `item.descriptor.name`             | string   | Yes         | `Consultation`                                                                               |
| `category.descriptor.code`         | string   | No          | Speciality code, for example `CARDIOLOGY`                                                    |
| `category.descriptor.name`         | string   | No          | Speciality name, for example `Cardiology`                                                    |
| `location.gps`                     | string   | Conditional | `latitude,longitude` for a proximity search                                                  |
| `location.radius.type`             | string   | Conditional | `CONSTANT` when using GPS                                                                    |
| `location.radius.value`            | string   | Conditional | Radius in km, for example `"10"`                                                             |
| `location.radius.unit`             | string   | Conditional | `km`                                                                                         |
| `location.city.name`               | string   | No          | City name                                                                                    |
| `location.city.code`               | string   | No          | City STD code                                                                                |
| `address.area_code`                | string   | No          | 6-digit pincode                                                                              |
| `provider.descriptor.name`         | string   | No          | Facility name                                                                                |
| `provider.id`                      | string   | No          | Provider ID, used in the second search                                                       |

A search by state and district:

```json
{  "context": {    "action": "search",    "city": "std:011",    "consumer_id": "<YOUR_EUA_ID_FROM_NHA_ONBOARDING>",    "consumer_uri": "<YOUR_HTTPS_CALLBACK_URL>",    "core_version": "0.7.1",    "country": "IND",    "domain": "nic2004:85111",    "message_id": "e9a19230-f951-11ec-b135-53aea776f66b",    "timestamp": "2026-06-18T06:52:13.969464Z",    "transaction_id": "e9a19230-f951-11ec-b135-53aea776f66b"  },  "message": {    "intent": {      "fulfillment": {        "type": "Physical",        "start": { "time": { "timestamp": "2026-06-18T10:37:32" } },        "end": { "time": { "timestamp": "2026-06-18T23:59:59" } }      },      "item": {        "descriptor": { "code": "Consultation", "name": "Consultation" }      },      "location": {        "state": { "name": "MAHARASHTRA", "code": "27" },        "district": { "name": "PUNE", "code": "490" }      }    }  }}
```

Three warnings apply to this call:

- A GPS search needs all three radius fields. Omit any one and the GPS filter is ignored without an error.
- The `transaction_id` in `search` must match the one in the `on_search` that answers it, or you cannot correlate the response.
- More filter combinations exist. The Swagger spec is the list.

### First on\_search, the catalog

Each matching HSPA answers independently, so you receive several. Aggregate them on `transaction_id`.

| Field                                                     | Required | What it is                                                                             |
| --------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `context.provider_uri`                                    | Yes      | The HSPA base URL. Store this. Every later call goes here                              |
| `message.catalog.descriptor.name`                         | Yes      | HSPA name                                                                              |
| `catalog.providers[].id`                                  | Yes      | Provider or hospital ID within this HSPA                                               |
| `catalog.providers[].descriptor.name`                     | Yes      | Hospital or clinic name                                                                |
| `catalog.providers[].categories[].descriptor.name`        | Yes      | Speciality name                                                                        |
| `catalog.providers[].categories[].descriptor.code`        | Yes      | Speciality code                                                                        |
| `catalog.providers[].fulfillments[].id`                   | Yes      | Slot UUID. This becomes `fulfillment.id` in `init`                                     |
| `catalog.providers[].fulfillments[].type`                 | Yes      | `Physical`                                                                             |
| `catalog.providers[].fulfillments[].agent.id`             | Yes      | Doctor HPR ID                                                                          |
| `catalog.providers[].fulfillments[].agent.name`           | Yes      | Doctor's registered name                                                               |
| `catalog.providers[].fulfillments[].agent.gender`         | No       | `M` or `F`                                                                             |
| `catalog.providers[].fulfillments[].agent.tags`           | No       | `@abdm/gov.in/experience`, `/languages`, `/education`, `/hpr_id`, `/hfr_id`, `/hip_id` |
| `catalog.providers[].fulfillments[].start.time.timestamp` | Yes      | Slot start                                                                             |
| `catalog.providers[].fulfillments[].end.time.timestamp`   | Yes      | Slot end                                                                               |
| `catalog.providers[].items[].id`                          | Yes      | Item ID. This becomes `order.item.id` in `init`                                        |
| `catalog.providers[].items[].price.value`                 | Yes      | Fee in INR, as a decimal string                                                        |
| `catalog.providers[].items[].fulfillment_id`              | Yes      | Links the item to its slot                                                             |
| `catalog.providers[].location.gps`                        | No       | Provider coordinates                                                                   |
| `catalog.providers[].location.address`                    | No       | Provider street address                                                                |

Trimmed to one provider:

```json
{  "context": {    "domain": "nic2004:85111",    "action": "on_search",    "consumer_id": "<YOUR_EUA_ID_FROM_NHA_ONBOARDING>",    "provider_id": "hspa-nha",    "provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",    "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b",    "message_id": "b2c3d4e5-f951-11ec-b135-53aea776f66b"  },  "message": {    "catalog": {      "descriptor": { "name": "ABDM Reference HSPA" },      "providers": [        {          "id": "1",          "descriptor": { "name": "Safdarjung Medical Centre" },          "categories": [            { "id": "201", "parent_category_id": "101", "descriptor": { "name": "Cardiology", "code": "CARDIOLOGY" } },            { "id": "101", "descriptor": { "name": "Allopathy", "code": "ALLOPATHY" } }          ],          "fulfillments": [            {              "id": "slot-uuid-a1b2c3d4-abcd-1234-efgh-567890abcdef",              "type": "Physical",              "agent": {                "id": "<HPR_ADDRESS>",                "name": "Dr. Priya Mehra",                "gender": "F",                "tags": {                  "@abdm/gov.in/experience": "8.0",                  "@abdm/gov.in/languages": "Hindi, English",                  "@abdm/gov.in/education": "MBBS, MD Cardiology",                  "@abdm/gov.in/hpr_id": "<HPR_ID>"                }              },              "start": { "time": { "timestamp": "2026-04-16T10:00:00" } },              "end": { "time": { "timestamp": "2026-04-16T10:20:00" } }            }          ],          "items": [            {              "id": "0",              "descriptor": { "name": "Consultation", "code": "CONSULTATION" },              "price": { "currency": "INR", "value": "500.0" },              "fulfillment_id": "slot-uuid-a1b2c3d4-abcd-1234-efgh-567890abcdef"            }          ],          "location": {            "gps": "28.635308,77.224960",            "address": "Safdarjung Enclave, New Delhi 110029",            "city": { "name": "Delhi", "code": "011" }          }        }      ]    }  }}
```

An HSPA sends the full `agent.tags` set including `@abdm/gov.in/hip_id`. That ID is what lets records generated at the visit be pulled later.

### Second search, direct

After the patient picks a doctor, your EUA sends a second `search` straight to the HSPA's `provider_uri`, asking for that doctor's slots in a time window. It carries `provider_id` and `provider_uri` in the context, and echoes the `provider`, `fulfillments` and `items` blocks from the first `on_search`. The HSPA answers with a second `on_search` scoped to that doctor.

## Stage 2: booking

### init

Direct to the HSPA. You send the patient's details and the chosen slot. The HSPA holds the slot temporarily.

| Field                                    | Required    | What it is                                                                                       |
| ---------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------ |
| `order.provider.id`                      | Yes         | Provider ID from the catalog                                                                     |
| `order.item.id`                          | Yes         | Item ID from the catalog                                                                         |
| `order.item.descriptor.code`             | Yes         | `Consultation`                                                                                   |
| `order.item.descriptor.name`             | Yes         | `Consultation`                                                                                   |
| `order.item.price.currency`              | No          | `INR`                                                                                            |
| `order.item.price.value`                 | No          | Fee as a decimal string                                                                          |
| `order.item.fulfillment_id`              | Yes         | Slot UUID from the catalog                                                                       |
| `order.fulfillment.id`                   | Yes         | The same slot UUID                                                                               |
| `order.fulfillment.type`                 | Yes         | `Physical`                                                                                       |
| `order.fulfillment.agent.id`             | Yes         | Doctor HPR ID                                                                                    |
| `order.fulfillment.agent.name`           | Yes         | Doctor's registered name                                                                         |
| `order.fulfillment.start.time.timestamp` | Yes         | Slot start                                                                                       |
| `order.fulfillment.end.time.timestamp`   | Yes         | Slot end                                                                                         |
| `order.fulfillment.tags`                 | Conditional | `@abdm/gov.in/slot_id` is mandatory and holds the slot UUID                                      |
| `order.billing.name`                     | Yes         | Patient billing name                                                                             |
| `order.billing.address`                  | Yes         | Object with `door`, `name`, `locality`, `city`, `state`, `country`, `area_code`                  |
| `order.billing.phone`                    | Yes         | 10-digit contact number                                                                          |
| `order.billing.email`                    | No          | Patient email                                                                                    |
| `order.customer.id`                      | Yes         | Patient [ABHA](/docs/uhi/v1/getting-started/glossary#abha) address, for example `rahul.k001@sbx` |
| `order.customer.person.gender`           | No          | `M` or `F`                                                                                       |
| `order.customer.person.dob`              | No          | `YYYY-MM-DD`                                                                                     |
| `order.payment.type`                     | Yes         | `ON-ORDER` for pay on visit. Other values: `PRE-FULFILLMENT`, `ON-FULFILLMENT`                   |
| `order.payment.params.redirect_url`      | No          | Payment callback URL                                                                             |

```json
{  "context": {    "domain": "nic2004:85111",    "country": "IND",    "city": "std:011",    "action": "init",    "core_version": "0.7.1",    "consumer_id": "<YOUR_EUA_ID_FROM_NHA_ONBOARDING>",    "consumer_uri": "<YOUR_HTTPS_CALLBACK_URL>",    "provider_id": "hspa-nha",    "provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",    "transaction_id": "a1b2c3d4-f951-11ec-b135-53aea776f66b",    "message_id": "d4e5f6a7-32af-11ef-bcbe-590b07ce8c90",    "timestamp": "2026-04-15T09:10:00Z"  },  "message": {    "order": {      "provider": { "id": "1" },      "item": {        "id": "0",        "descriptor": { "name": "Consultation", "code": "CONSULTATION" },        "price": { "currency": "INR", "value": "500.0" },        "fulfillment_id": "slot-uuid-a1b2c3d4-abcd-1234-efgh-567890abcdef"      },      "fulfillment": {        "id": "slot-uuid-a1b2c3d4-abcd-1234-efgh-567890abcdef",        "type": "Physical",        "agent": { "id": "<HPR_ADDRESS>", "name": "Dr. Priya Mehra" },        "start": { "time": { "timestamp": "2026-04-16T10:00:00" } },        "end": { "time": { "timestamp": "2026-04-16T10:20:00" } }      },      "billing": {        "name": "Rahul Kumar Sharma",        "address": {          "door": "B-204",          "name": "Rahul Kumar Sharma",          "locality": "Rohini Sector 14",          "city": "Delhi",          "state": "Delhi",          "country": "INDIA",          "area_code": "110085"        },        "phone": "<MOBILE_NUMBER>",        "email": "patient@example.org"      },      "customer": {        "id": "rahul.k001@sbx",        "person": { "gender": "M", "dob": "1990-05-15", "dayOfBirth": 15, "monthOfBirth": 5, "yearOfBirth": 1990 }      },      "payment": {        "type": "ON-ORDER",        "params": { "redirect_url": "<YOUR_PAYMENT_REDIRECT_URL>" }      }    }  }}
```

Two warnings:

- `fulfillment.id` must be exactly the slot UUID from `on_search`. A mismatch makes the HSPA reject the call or fail to hold the slot without telling you.
- The hold is short, typically 15 minutes. If `confirm` does not arrive in time the slot is released and you start again at `init`.

### on\_init, the terms

The HSPA answers with the order ID, an itemised quote, and five term objects the patient has to accept.

| Field added by the HSPA | What it is                                                                                                           |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `order.id`              | The HSPA's order ID, generated here. Send it in every later call. Use an alphanumeric string, for example `AHS12345` |
| `order.terms[]`         | Five term objects, each with `termsState: "INITIATED"`                                                               |
| `order.quote`           | Price breakup: consultation, SGST, CGST, registration                                                                |
| `order.payment.type`    | `ON-ORDER`, `FREE` or `PRE-ORDER`                                                                                    |
| `order.payment.status`  | `NOT_PAID` or `FREE`                                                                                                 |

Each term object:

| Field                           | Required    | What it is                                                        |
| ------------------------------- | ----------- | ----------------------------------------------------------------- |
| `terms[].type`                  | Yes         | `Commercial`, `Settlement`, `Cancellation`, `Refund` or `Payment` |
| `terms[].descriptor.name`       | Yes         | Term title                                                        |
| `terms[].descriptor.short_desc` | No          | Brief description                                                 |
| `terms[].descriptor.long_desc`  | No          | Full text. Show this to the patient                               |
| `terms[].reasonRequired`        | Yes         | If true, a reason is needed when this term is actioned            |
| `terms[].timePeriod`            | Yes         | Validity. Copy unchanged into `confirm`                           |
| `terms[].reason`                | Conditional | Required in `confirm` when `reasonRequired` is true               |
| `terms[].termsState`            | Yes         | `INITIATED` here. You set `AGREED` in `confirm`                   |

Store every term object exactly as received. Change only `termsState`, and `reason` where it is required.

### confirm

Send the whole order back with every term at `AGREED`. Any term still at `INITIATED` and the HSPA rejects the call. Use the `order.id` the HSPA assigned in `on_init`, not any ID you generated.

### on\_confirm, the PIN

The HSPA sets `order.state` to `CONFIRMED` and returns a 4-digit PIN.

| Field                                         | What it is                                            |
| --------------------------------------------- | ----------------------------------------------------- |
| `order.state`                                 | `CONFIRMED`, or `FAILED` on a payment or system error |
| `order.id`                                    | The HSPA's order ID                                   |
| `order.authorization.type`                    | `PIN`                                                 |
| `order.authorization.token`                   | The 4-digit PIN                                       |
| `order.authorization.valid_from`              | PIN validity start                                    |
| `order.authorization.valid_to`                | PIN validity end, usually end of the appointment day  |
| `order.authorization.status`                  | `GENERATED` here                                      |
| `order.fulfillment.tags.@abdm/gov.in/slot_id` | The confirmed slot UUID                               |

```json
{  "authorization": {    "type": "PIN",    "token": "3774",    "valid_from": "2026-06-18T00:00:00",    "valid_to": "2026-06-18T23:59:00",    "status": "GENERATED"  }}
```

The PIN is security sensitive. Hold it in memory or secure session storage on the EUA. Do not write it to a database or to application logs.

The HSPA has two more obligations here. It sends an exact copy of the `on_confirm` payload to the gateway audit endpoint listed under [gateway endpoints](#gateway-endpoints), and it sets the communication tags on the fulfilment:

```json
{  "tags": {    "@abdm/gov.in/slot_id": "79db6b5b-afe4-4297-b9b1-5148ed45372c",    "@abdm/gov.in/messaging_support": "true",    "@abdm/gov.in/deep_link": "",    "@abdm/gov.in/helpline_number": "",    "@abdm/gov.in/chatbot_link": ""  }}
```

`messaging_support` and a helpline number are mandatory in `on_confirm`.

## Stage 3: fulfilment

### status and on\_status

`status` carries only `order.id`. The HSPA answers with the full order object, and you replace your stored state with it. This is reconciliation, not a polling loop.

### Order states

| State                 | Set by                          | Meaning                                         |
| --------------------- | ------------------------------- | ----------------------------------------------- |
| `CONFIRMED`           | HSPA, in `on_confirm`           | Booked. PIN generated                           |
| `APPOINTMENT_STARTED` | HSPA, in `on_update`            | The doctor has begun the consultation           |
| `COMPLETED`           | HSPA, in `on_update`            | The doctor has marked the consultation complete |
| `CANCELLED`           | HSPA or EUA                     | Cancelled under the agreed terms                |
| `NO_SHOW`             | HSPA, in `on_update`            | The patient did not appear                      |
| `DOCTOR_NO_SHOW`      | EUA, in `on_update` to the HSPA | The doctor did not appear                       |
| `FAILED`              | HSPA, in `on_confirm`           | Payment or system failure at confirmation       |

`DOCTOR_NO_SHOW` is the only state an EUA may set. Everything else is the HSPA's.

### PIN states

| State           | Meaning                                                 |
| --------------- | ------------------------------------------------------- |
| `GENERATED`     | Set when the PIN is created at confirmation             |
| `VERIFIED`      | The provider checked the PIN before the consultation    |
| `HSPA_OVERRIDE` | The PIN was not checked and the HSPA overrode the check |

### on\_update

The HSPA pushes state changes to your `/on_update` as they happen. This is the main real-time channel, not `status`. Update your local state and notify the patient.

## Stage 4: post-fulfilment

### cancel and on\_cancel

| Field                                             | Required | What it is            |
| ------------------------------------------------- | -------- | --------------------- |
| `order.id`                                        | Yes      | The order to cancel   |
| `order.state`                                     | Yes      | `CANCELLED`           |
| `order.fulfillment.tags.@abdm/gov.in/cancelledby` | Yes      | `patient` or `doctor` |

```json
{  "message": {    "order": {      "id": "0415-234567-8901",      "state": "CANCELLED",      "fulfillment": {        "tags": { "@abdm/gov.in/cancelledby": "patient" }      }    }  }}
```

The `cancelledby` tag is mandatory. Without it the HSPA cannot tell which set of cancellation terms applies.

Your `/on_cancel` handler has to cope with both directions: the HSPA's acknowledgement of a patient cancellation, and an HSPA-initiated cancellation when a doctor cancels. Read the `cancelledby` tag to tell them apart.

### on\_message

Optional for an HSPA, mandatory for an EUA. Both sides consume the same shape. Content sits under `message.intent.chat`.

| Field                           | Required    | What it is                                                       |
| ------------------------------- | ----------- | ---------------------------------------------------------------- |
| `chat.sender.person.id`         | Yes         | ABHA address of the sender, or HPR ID when the doctor sends      |
| `chat.sender.person.name`       | Yes         | Sender's name                                                    |
| `chat.receiver.person.id`       | Yes         | HPR ID of the doctor, or ABHA address of the patient             |
| `chat.receiver.person.name`     | Yes         | Receiver's name                                                  |
| `chat.content.content_id`       | Yes         | UUID for this message                                            |
| `chat.content.content_value`    | Yes         | Base64-encoded text or file                                      |
| `chat.content.content_type`     | Yes         | `text` or `media`                                                |
| `chat.content.content_mimeType` | Conditional | MIME type when `content_type` is `media`                         |
| `chat.content.content_fileName` | Conditional | File name when `content_type` is `media`                         |
| `chat.content.hiType`           | Conditional | Health information type, for example `prescription`, `labReport` |
| `chat.time.timestamp`           | Yes         | Message time                                                     |

## Gateway endpoints

You do not build these. NHA operates them.

| Endpoint                              | Called by | Purpose                                                        |
| ------------------------------------- | --------- | -------------------------------------------------------------- |
| `POST /api/v1/uhi/search`             | EUA       | Broadcast a search to all registered HSPAs                     |
| `POST /api/v1/uhi/on_search`          | HSPA      | Deliver a catalog, which the gateway forwards to the EUA       |
| `POST /api/v1/uhi/on_confirm_audit`   | HSPA      | Exact copy of every `on_confirm`                               |
| `POST /api/v1/uhi/on_update_audit`    | HSPA      | Exact copy of every `on_update`. The care context ID goes here |
| `POST /api/v1/uhi/on_cancel_audit`    | HSPA      | Exact copy of every `on_cancel`                                |
| `POST /api/v1/uhi/on_status_audit`    | HSPA      | Exact copy of every `on_status`                                |
| `POST /api/v1/networkregistry/lookup` | Either    | Look up a counterparty's public key                            |

The audit copies are an HSPA obligation for compliance traceability, not optional.

## Cancellation reason codes

The reason codes are fixed. You choose the labels your users see.

### Patient-initiated, sent in `cancel` with `cancelledby: patient`

| Code                                 | Meaning                                                |
| ------------------------------------ | ------------------------------------------------------ |
| `PATIENT_PERSONAL_EMERGENCY`         | Patient or family emergency                            |
| `PATIENT_HEALTH_IMPROVED`            | Condition resolved, consultation no longer needed      |
| `PATIENT_UNABLE_TO_VISIT_PHYSICALLY` | Scheduling conflict or inability to reach the facility |
| `DOCTOR_ASKED_TO_CANCEL`             | The doctor asked the patient to cancel                 |
| `PATIENT_BOOKED_IN_ERROR`            | Wrong doctor, speciality, date or time                 |
| `PATIENT_SEEKING_ALTERNATIVE`        | Patient has decided to see someone else                |
| `PATIENT_OTHER`                      | Anything else. Your EUA must capture free text         |

### Doctor or facility-initiated, sent in `on_cancel` with `cancelledby: doctor`

| Code                        | Meaning                                                |
| --------------------------- | ------------------------------------------------------ |
| `DOCTOR_PERSONAL_EMERGENCY` | Unplanned personal or medical emergency                |
| `DOCTOR_UNAVAILABLE`        | Unexpected surgery, patient emergency or high footfall |
| `DOCTOR_SCHEDULE_CHANGE`    | Session timings changed                                |
| `FACILITY_CLOSURE`          | Facility temporarily closed                            |
| `TECHNICAL_SYSTEM_ISSUE`    | HSPA platform failure or downtime                      |
| `DOCTOR_OTHER`              | Anything else. The HSPA must provide free text         |

### PIN override, used by facility staff

| Code                              | When it applies                                            |
| --------------------------------- | ---------------------------------------------------------- |
| `OVERRIDE_EMERGENCY_CONSULTATION` | Patient arrives in acute distress                          |
| `OVERRIDE_PIN_TECH_FAILURE`       | The app cannot show the PIN. Identity verified another way |
| `OVERRIDE_PIN_DELIVERY_FAILURE`   | The PIN never reached the patient                          |
| `OVERRIDE_VULNERABLE_PATIENT`     | Elderly, differently-abled or low digital literacy patient |
| `OVERRIDE_EUA_OUTAGE`             | The EUA platform is down                                   |
| `OVERRIDE_MISMATCH`               | PIN could not be validated after three attempts            |
| `OVERRIDE_OTHER`                  | Anything else. The HSPA must provide free text             |

## Terms and conditions text

The `on_init` terms array carries the text the patient reads before confirming. Sample clauses are published. Two points carry through all of them.

- UHI is a technology gateway. It does not supervise providers, does not guarantee outcomes, and does not collect, hold or route any payment.
- Every payment, refund, cancellation charge and pricing dispute is between the patient and the facility.

## Field and error reference

The tables above carry the fields you send and receive most. For the complete order field list, use the [Swagger spec](https://uhigatewaysandbox.abdm.gov.in/swagger-ui/index.html?urls.primaryName=v2.0.2#/).

Error codes for this service are not published as a list. The error object carries `type` and `code`, both mandatory, with `path` and `message` optional.

## Next

- [UHI services](/docs/uhi/v1) for the shared protocol
- [Ambulance booking](/docs/uhi/v1/concepts/services/ambulance-booking)
- [Blood bank](/docs/uhi/v1/concepts/services/blood-bank)
- [M2](/docs/hiecm/v3/api/m2), the prerequisite
- [Support](/docs/support)


---

# PM-JAY HEM hospital discovery

PM-JAY is India's national health insurance scheme, and HEM is the Hospital Empanelment Management system that knows which hospitals are empanelled right now. After this page you will know the six ways to search HEM over UHI, and every field that comes back.

## Who does what

This is an [EUA](/docs/uhi/v1/getting-started/glossary#eua) side integration. [NHA](/docs/uhi/v1/getting-started/glossary#nha) runs the single [HSPA](/docs/uhi/v1/getting-started/glossary#hspa). No third party builds one for this service.

| Party                                                    | Who runs it                                                      | What it does here                                                        |
| -------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------ |
| EUA                                                      | You, or any [PHR](/docs/uhi/v1/getting-started/glossary#phr) app | Sends the `search`. Receives the `on_search`. Renders the hospital list. |
| [UHI](/docs/uhi/v1/getting-started/glossary#uhi) Gateway | NHA                                                              | Validates and routes the `search`. Relays the `on_search` back to you.   |
| PM-JAY HEM HSPA                                          | NHA                                                              | Queries the HEM database. Builds the `on_search` catalog.                |

Signing, onboarding and Gateway base URLs are shared across UHI. See [UHI services](/docs/uhi/v1).

## Before you onboard

Your application must have completed [HIE-CM](/docs/uhi/v1/getting-started/glossary#hie-cm) Milestone 2 as an [ABDM](/docs/uhi/v1/getting-started/glossary#abdm) compliant application. The network's document states that applications without M2 cannot be onboarded onto UHI services, PM-JAY HEM included. If you have not done that, start at [M2](/docs/hiecm/v3/api/m2).

You also need:

- A publicly reachable HTTPS callback URL for `on_search` responses.
- UHI request signing in place, Ed25519 signatures over a BLAKE-512 body hash.
- Code that treats `search` as fire and forget. Do not block waiting for a synchronous reply.

## Message flow

Two calls, discovery only. Booking and referral are a later phase. The HTTP 200 from the Gateway confirms receipt, nothing more.

| Step | Who acts        | What happens                                                         |
| ---- | --------------- | -------------------------------------------------------------------- |
| 1    | Your system     | POST `/search` to the Gateway with state, plus any optional filters. |
| 2    | Gateway         | Returns HTTP 200 ACK immediately.                                    |
| 3    | Gateway         | POSTs the `search` to the PM-JAY HEM HSPA.                           |
| 4    | PM-JAY HEM HSPA | Queries the HEM database.                                            |
| 5    | PM-JAY HEM HSPA | POSTs `on_search` to the Gateway with matching hospital records.     |
| 6    | Gateway         | POSTs the `on_search` to your `consumer_uri`.                        |
| 7    | Your system     | ACKs the `on_search` and renders the hospital list.                  |

Both calls can return NACK as well as ACK. Match a response to its request by `context.transaction_id`.

## Service identity

These values are case sensitive. If any of them is wrong, no HSPA answers your search and you get nothing back.

| Parameter              | Value           | Where it goes                         |
| ---------------------- | --------------- | ------------------------------------- |
| `domain`               | `nic2004:85112` | `context.domain` in every call        |
| `fulfillment.type`     | `PMJAYHEM`      | `message.intent.fulfillment.type`     |
| `item.descriptor.code` | `PMJAY`         | `message.intent.item.descriptor.code` |
| `item.descriptor.name` | `PMJAY`         | `message.intent.item.descriptor.name` |
| `item.descriptor.flag` | `false`         | `message.intent.item.descriptor.flag` |

## Search filters

State is mandatory in every search. The other five filters are optional and stack on top of it.

| Search type             | Mandatory                  | Optional fields added                                        | Use case                             |
| ----------------------- | -------------------------- | ------------------------------------------------------------ | ------------------------------------ |
| State only              | `state.name`, `state.code` | none                                                         | Every empanelled hospital in a state |
| State and district      | `state.name`, `state.code` | `district.name`, `district.code`                             | Narrow to one district               |
| State and speciality    | `state.name`, `state.code` | `category.descriptor.name`, `category.descriptor.code`       | Filter by clinical speciality        |
| State and facility name | `state.name`, `state.code` | `provider.descriptor.name`                                   | Find a hospital by name              |
| State and pincode       | `state.name`, `state.code` | `address.area_code`                                          | Search a pincode area                |
| State and GPS           | `state.name`, `state.code` | `location.gps`, `radius.type`, `radius.value`, `radius.unit` | Proximity search                     |

State and district names go in capitals, for example `ANDHRA PRADESH`. Note that `address` is a sibling of `fulfillment` inside `message.intent`, not a child of `location`.

To get the speciality codes for `category.descriptor.code`, call the PM-JAY speciality list endpoint.

```bash
# Sandboxcurl --location 'https://apisbeta.nha.gov.in/pmjay/payer/hbp/get/scheme/specialities' \  --header 'Accept: application/json' \  --header 'source: internal' \  --header 'Content-Type: application/json' \  --header 'pid: 33222' \  --data '{"schemecode": "PMJAY", "hosptype": "H"}'
```

Swap the host for `https://apisprod.nha.gov.in` in production. The rest of the call is the same.

## Sample payloads

These samples use an abbreviated field listing with dotted paths rather than literal JSON request bodies. Build your JSON from the field reference underneath, where the nesting is explicit.

The `context` block is identical across all six variants. Only `message.intent` changes.

### context

```yaml
context:  domain: 'nic2004:85112'          # Fixed for PM-JAY HEM  country: IND  city: 'std:011'  action: search  core_version: 0.7.1  consumer_id: <YOUR_EUA_ID_FROM_NHA_ONBOARDING>  consumer_uri: <YOUR_HTTPS_CALLBACK_URL>  message_id: dfa04e10-63ec-11ed-9f98-49dd5c7c4d8a   # Fresh UUID per call  timestamp: '2022-11-14T07:20:54.005277Z'  transaction_id: dfa04e10-63ec-11ed-9f98-49dd5c7c4d8a   # Links on_search back to this search
```

### Search by state

The base case. Every other variant adds to this one.

```yaml
message:  intent:    fulfillment:      type: 'PMJAYHEM'      start.time.timestamp: '2022-07-22T13:21:41'      end.time.timestamp: '2022-07-22T23:59:59'    item.descriptor:      code: 'PMJAY'      name: 'PMJAY'      flag: false    location:      state.name: 'ANDHRA PRADESH'      state.code: '28'
```

### Search by state and district

```yaml
message:  intent:    fulfillment:      type: 'PMJAYHEM'      start.time.timestamp: '2022-07-22T13:21:41'      end.time.timestamp: '2022-07-22T23:59:59'    item.descriptor:      code: 'PMJAY'      name: 'PMJAY'      flag: false    location:      state.name: 'ANDHRA PRADESH'      state.code: '28'      district.name: 'ANAKAPALLI'      district.code: 744
```

### Search by state and speciality

Add a `category` block inside `intent`.

```yaml
message:  intent:    fulfillment:      type: 'PMJAYHEM'      start.time.timestamp: '2022-07-22T13:21:41'      end.time.timestamp: '2022-07-22T23:59:59'    category:      descriptor.name: Cardiology      descriptor.code: 100002    item.descriptor:      code: 'PMJAY'      name: 'PMJAY'      flag: false    location:      state.name: 'ANDHRA PRADESH'      state.code: '28'      district.name: 'ANAKAPALLI'      district.code: 744
```

### Search by state and facility name

Add a `provider` block inside `intent`.

```yaml
message:  intent:    provider:      descriptor.name: General Hospital    fulfillment:      type: 'PMJAYHEM'      start.time.timestamp: '2022-07-22T13:21:41'      end.time.timestamp: '2022-07-22T23:59:59'    item.descriptor:      code: 'PMJAY'      name: 'PMJAY'      flag: false    location:      state.name: 'ANDHRA PRADESH'      state.code: '28'
```

### Search by state and pincode

`address` sits beside `fulfillment`, not inside `location`.

```yaml
message:  intent:    fulfillment:      type: 'PMJAYHEM'      start.time.timestamp: '2022-07-22T13:21:41'      end.time.timestamp: '2022-07-22T23:59:59'    item.descriptor:      code: 'PMJAY'      name: 'PMJAY'      flag: false    location:      state.name: 'ANDHRA PRADESH'      state.code: '28'    address:      area_code: 523303
```

### Search by state and GPS

```yaml
message:  intent:    fulfillment:      type: 'PMJAYHEM'      start.time.timestamp: '2022-07-22T13:21:41'      end.time.timestamp: '2022-07-22T23:59:59'    item.descriptor:      code: 'PMJAY'      name: 'PMJAY'      flag: false    location:      state.name: 'ANDHRA PRADESH'      state.code: '28'      gps: 17.3787973,78.4368433      radius.type: CONSTANT      radius.value: 13.0      radius.unit: km
```

### on\_search response

One `providers[]` entry per empanelled hospital. Note that the establishment date and the empanelment date both arrive as `fulfillments[]` entries, told apart by their `type`.

```yaml
context:  domain: 'nic2004:85112'  action: on_search  consumer_id: eua-nha  consumer_uri: <YOUR_HTTPS_CALLBACK_URL>  provider_id: hspa-nha  provider_uri: https://hspasbx.abdm.gov.in/api/v1/hspa  transaction_id: dfa04e10-63ec-11ed-9f98-49dd5c7c4d8a   # Matches the originating search  message_id: <RESPONSE_MESSAGE_ID>message:  catalog:    descriptor.name: PMJAY HSPA    descriptor.short_desc: Pradhan Mantri Jan Arogya Yojana - Hospital Engagement Module    providers:      - id: 'HOSP27G13867'        descriptor.name: General Hospital Wardha        descriptor.code: G                # G government, P private        descriptor.flag: false            # NABH accreditation, may be unpopulated        categories:          - descriptor.name: Cardiology            descriptor.code: 100002          - descriptor.name: General Medicine            descriptor.code: 100005        fulfillments:          - type: 'Establishment Date'            start.time.timestamp: '1915'          - type: 'Empaneled Date'            start.time.timestamp: '2018-09-14 16:03:16.0'        location:          gps: '15.497097,80.048688'          address: '37-1-382-6'          city.name: ONGOLE          district.name: PRAKASAM          district.code: '517'          state.name: Andhra Pradesh          state.code: 28          country.name: INDIA        contact:          phone: <MOBILE_NUMBER>          email: contact@example.org          tags.nodalOfficerNumber: <MOBILE_NUMBER>
```

## Field reference

### search: context

All fields are mandatory.

| Field            | Type     | Value                                                |
| ---------------- | -------- | ---------------------------------------------------- |
| `domain`         | string   | `nic2004:85112`, fixed                               |
| `country`        | string   | `IND`, fixed                                         |
| `city`           | string   | STD code, for example `std:011`                      |
| `action`         | string   | `search`, fixed                                      |
| `core_version`   | string   | `0.7.1`                                              |
| `consumer_id`    | string   | Your registered EUA identifier                       |
| `consumer_uri`   | string   | Your HTTPS callback URL                              |
| `message_id`     | UUID     | Fresh per call. Never reuse.                         |
| `transaction_id` | UUID     | Fresh per search session. The `on_search` copies it. |
| `timestamp`      | ISO 8601 | Request time                                         |

### search: message.intent

| Field path                         | Type     | Mandatory | Description                                          |
| ---------------------------------- | -------- | --------- | ---------------------------------------------------- |
| `fulfillment.type`                 | string   | Yes       | `PMJAYHEM`, fixed                                    |
| `fulfillment.start.time.timestamp` | datetime | Yes       | Start of the search window                           |
| `fulfillment.end.time.timestamp`   | datetime | Yes       | End of the search window                             |
| `item.descriptor.code`             | string   | Yes       | `PMJAY`, fixed                                       |
| `item.descriptor.name`             | string   | Yes       | `PMJAY`, fixed                                       |
| `item.descriptor.flag`             | boolean  | Yes       | `false`, fixed                                       |
| `location.state.name`              | string   | Yes       | State name in capitals, for example `ANDHRA PRADESH` |
| `location.state.code`              | string   | Yes       | Numeric state code, for example `28`                 |
| `location.district.name`           | string   | No        | District name in capitals                            |
| `location.district.code`           | integer  | No        | Numeric district code                                |
| `location.gps`                     | string   | No        | `lat,long`, for example `17.378,78.436`              |
| `location.radius.type`             | string   | No        | `CONSTANT`. Required with a GPS search.              |
| `location.radius.value`            | float    | No        | Radius in km, for example `13.0`                     |
| `location.radius.unit`             | string   | No        | `km`                                                 |
| `address.area_code`                | integer  | No        | 6 digit pincode                                      |
| `category.descriptor.name`         | string   | No        | Speciality name, for example `Cardiology`            |
| `category.descriptor.code`         | integer  | No        | Speciality code, for example `100002`                |
| `provider.descriptor.name`         | string   | No        | Hospital or facility name                            |

### on\_search: provider records

| Field path                                                           | Type    | Description                                        |
| -------------------------------------------------------------------- | ------- | -------------------------------------------------- |
| `catalog.providers[].id`                                             | string  | PM-JAY HEM hospital ID, for example `HOSP27G13867` |
| `catalog.providers[].descriptor.name`                                | string  | Hospital name                                      |
| `catalog.providers[].descriptor.code`                                | string  | `G` government, `P` private                        |
| `catalog.providers[].descriptor.flag`                                | boolean | NABH accreditation. May be unpopulated.            |
| `catalog.providers[].descriptor.short_desc`                          | string  | State level empanelment context                    |
| `catalog.providers[].descriptor.long_desc`                           | string  | Empanelment status description                     |
| `catalog.providers[].categories[].descriptor.name`                   | string  | Speciality name                                    |
| `catalog.providers[].categories[].descriptor.code`                   | integer | Speciality code                                    |
| `catalog.providers[].fulfillments[]` with `type: Establishment Date` | string  | Year the hospital was established                  |
| `catalog.providers[].fulfillments[]` with `type: Empaneled Date`     | string  | Date of PM-JAY empanelment                         |
| `catalog.providers[].location.gps`                                   | string  | `lat,long` of the hospital                         |
| `catalog.providers[].location.address`                               | string  | Street address                                     |
| `catalog.providers[].location.city.name`                             | string  | City name                                          |
| `catalog.providers[].location.district.name`                         | string  | District name                                      |
| `catalog.providers[].location.district.code`                         | string  | District code                                      |
| `catalog.providers[].location.state.name`                            | string  | State name                                         |
| `catalog.providers[].location.state.code`                            | integer | State code                                         |
| `catalog.providers[].contact.phone`                                  | string  | Hospital phone number                              |
| `catalog.providers[].contact.email`                                  | string  | Hospital email                                     |
| `catalog.providers[].contact.tags.nodalOfficerNumber`                | string  | Nodal officer number for PM-JAY questions          |

## Known limitations

These apply to the current phase.

| Limitation                                                                    | What to do                                                                         |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| GPS search can return incomplete results where hospital density is low        | Offer district or pincode search as a fallback next to GPS                         |
| `descriptor.flag`, the NABH accreditation flag, is not consistently populated | Do not filter on it. Show it when present, otherwise say nothing.                  |
| `on_search` responses arrive asynchronously with no end of results signal     | Set a timeout window. Show results as they arrive.                                 |
| No pagination on `on_search`                                                  | Handle large payloads without blocking the UI. Paginate on the client for display. |
| No booking or referral                                                        | Scope your UI to discovery                                                         |
| The covered procedure list can lag real package changes                       | Show a disclaimer and link to pmjay.gov.in for the authoritative package list      |

## Testing before go-live

There are 29 test cases across five categories, to be run against the UHI sandbox before you request production sign off.

| Category               | What it checks                                                                                                                                                                                                       |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A, context validation  | All mandatory `context` fields present. `transaction_id` in `on_search` matches the originating `search`. `domain` mirrors correctly.                                                                                |
| B, search filters      | One test per supported filter variant, checking that results honour the filter.                                                                                                                                      |
| C, on\_search response | Provider ID present and non null. Core fields present. Empanelment and establishment dates present. GPS parseable. Nodal officer number present. Specialities returned.                                              |
| D, user experience     | The feature is reachable in three taps or fewer. UHI, PM-JAY and ABDM branding on the search screen. A fallback message when there are no results. A disclaimer on the results screen asking the user to call ahead. |
| E, edge cases          | A large result set from a high density state renders. An empty `providers[]` array shows a fallback and does not crash. A missing `on_search` times out and offers a retry rather than spinning forever.             |

Ask for the full test case sheet and the UHI Postman collection when you onboard.

## Phase scope

The plan has three phases, and only the first, discovery, is open for onboarding. Booking and referral workflows, provider dashboards and CSC kiosk search are named as the second phase. [ABHA](/docs/uhi/v1/getting-started/glossary#abha) linked discharge summaries and multilingual voice are named as the third. Dates for either are not yet published.

## Next

- Shared UHI protocol, signing and onboarding: [UHI services](/docs/uhi/v1)
- The M2 prerequisite: [HIE-CM M2](/docs/hiecm/v3/api/m2)


---

# Glossary

Every term the UHI documentation links to. Each row keeps its own anchor, so a link like `#eua` lands on the right row. HIE-CM's own vocabulary, the roles and the consent objects, is in the [HIE-CM glossary](/docs/hiecm/v3/getting-started/glossary).

## Across ABDM

These terms mean the same thing on every ABDM gateway.

### ABDM

The Ayushman Bharat Digital Mission (ABDM) is a Government of India initiative that aims to develop an integrated, citizen-centric digital health ecosystem. It establishes common standards and core digital building blocks to enable secure and interoperable exchange of health information among participating stakeholders.

### ABHA

Ayushman Bharat Health Account (ABHA) is the account used by an individual to participate in India’s digital health ecosystem. It includes an [ABHA Number](#abha-number) for unique identification and may be linked to an [ABHA Address](#abha-address) for consent-based access and sharing of digital health records.

### ABHA address

An ABHA Address is a unique, self-declared username that enables an individual to link, access and share health records digitally with appropriate consent.

### ABHA number

An ABHA Number is a unique 14-digit number that identifies an individual as a participant in India’s digital health ecosystem. It provides a trusted identity that may be used across participating healthcare providers and payers. Creation and use of an ABHA Number are voluntary.

### FHIR

Fast Healthcare Interoperability Resources (FHIR) is a standard developed by Health Level Seven International (HL7) for the electronic exchange of healthcare information. ABDM adopts applicable FHIR R4 profiles published by the National Resource Centre for EHR Standards (NRCeS) to support interoperable health-data exchange.

### Gateway

The ABDM Gateway enables secure routing and exchange of information among participating systems in the ABDM ecosystem. Integrators communicate through approved ABDM interfaces and implement the callback endpoints and authentication mechanisms specified in the applicable technical documentation.

### Health Tech Committee

The Health Technology Committee (HTC) reviews eligible integrations as part of the ABDM sandbox exit and production onboarding process. The review is undertaken after completion of the applicable functional, security and documentation requirements prescribed by [NHA](#nha). See [Go live](/docs/hiecm/v3/getting-started/going-live).

### HFR

The Health Facility Registry (HFR) is a comprehensive repository of public and private health facilities in India across different systems of medicine. Registered facilities receive a unique Facility ID and may access applicable digital services within the ABDM ecosystem. See [registries](/docs/hiecm/v3/registries).

### HIE-CM

The Health Information Exchange and Consent Manager (HIE-CM) is a gateway under ABDM that manages consent relating to an individual’s personal health data and supports the secure, consent-based exchange of interoperable health information among ecosystem participants. See [The ABDM gateway](/docs/hiecm/v3/concepts/gateway).

### HPID

Healthcare Professional ID (HPID) refers to the unique identifier assigned to an eligible healthcare professional upon successful registration and verification in the [Healthcare Professionals Registry](#hpr). See [M4](/docs/hiecm/v3/getting-started/glossary#m4).

### HPR

The Healthcare Professionals Registry (HPR) is the national registry of doctors, nurses and pharmacists. Registering a professional on the HPR results in the issuance of an [HPID](#hpid). The HPR Token can also be used to onboard a facility to the [HFR](#hfr).

### KYC

Know Your Customer: the identity check that must pass before an [ABHA number](#abha-number) is issued. The check runs against Aadhaar: by [OTP](#otp), by biometric authentication (face, fingerprint or iris), or, for government entities only, by demographic authentication.

### NHA

The National Health Authority (NHA), under the Ministry of Health and Family Welfare, Government of India, is responsible for the implementation of ABDM and PMJAY and the management of its foundational digital health building blocks, policies and standards.

### NHCX

The National Health Claims Exchange (NHCX) is a digital gateway under ABDM that supports standardised and interoperable exchange of health-insurance claims information among payers, providers and other authorised participants. See [NHCX](/docs/nhcx/v1).

### OTP

One Time Password: a short code sent to a mobile number or an email address to prove the person holds it. An ABHA OTP is valid for 10 minutes, and it is always verified together with the [txnId](#txnid) of the call that requested it.

### PHR

A Personal Health Record (PHR) application enables an individual to discover, link, view and manage personal health records and to provide or withdraw consent for sharing those records through the ABDM ecosystem. See [PHR applications](/docs/hiecm/v3/concepts/participants/phr).

### Safe to Host certificate

The security documentation a [WASA](#wasa) supports. It is issued after the assessment by a CERT-In-empanelled auditor, and it is required for production onboarding under ABDM.

### Sandbox

The ABDM Sandbox is a controlled test environment that enables health-technology companies and other eligible entities to integrate their software with ABDM building blocks, test applicable use cases and demonstrate compliance before seeking production access.

### txnId

Transaction id. Most flows take two or three calls, and the first one returns a `txnId` that the calls after it send back, so ABDM knows which attempt they belong to. It is short lived and single purpose. It is not a session and it is not a token: holding a `txnId` does not authenticate you, and it stops working once the flow it belongs to finishes or expires.

### UHI

The Unified Health Interface (UHI) is an open network for digital health-service discovery and delivery. It enables participating applications and providers to interact through standard protocols for services such as appointment discovery and booking and other supported digital health use cases. See [UHI](/docs/uhi/v1).

### WASA

Web Application Security Assessment (WASA) is a security assessment performed by a CERT-In-empanelled auditor on the relevant application environment. The assessment supports issuance of the required security documentation for production onboarding under ABDM. See [Security audit](/docs/hiecm/v3/getting-started/security-audit).

## On UHI

These terms belong to UHI: the two applications on either side of a booking.

### EUA

End User Application: in [UHI](#uhi), the consumer facing side, the app a patient or a caregiver uses to search for a service and book it. It sends a signed request to the UHI gateway and receives responses at its own callback URL. See [UHI](/docs/uhi/v1).

### HSPA

Health Service Provider Application: in [UHI](#uhi), the provider side system that receives requests and responds to them, such as an ambulance operator's dispatch platform, a blood bank management system or a pharmacy's stock system. It is the counterpart of the [EUA](#eua).


---

# Onboarding to UHI

Every [UHI](/docs/uhi/v1/getting-started/glossary#uhi) service document repeats the same joining route. After this page you will know the seven steps from the [M2](/docs/hiecm/v3/getting-started/glossary#m2) gate to production go-live, and where one service differs from the rest.

Read [Introduction](/docs/uhi/v1) and [UHI gateway](/docs/uhi/v1/concepts/network-and-protocol) first, for the network, the two roles and the message pattern.

## Pick your role first

| Role                                               | Full name                           | What you build                                                                                                                 |
| -------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| [EUA](/docs/uhi/v1/getting-started/glossary#eua)   | End User Application                | The citizen facing app. Sends the search, receives results at your callback URL, drives booking where the service supports it. |
| [HSPA](/docs/uhi/v1/getting-started/glossary#hspa) | Health Service Provider Application | The provider platform. Answers searches from its own catalogue and, where the service supports it, runs the booking lifecycle. |

The HSP is the hospital, clinic, doctor, ambulance operator or blood bank, and the HSPA is its digital interface. The [gateway](/docs/uhi/v1/getting-started/glossary#gateway) is the network's routing layer.

## Which role each service accepts

Four of the seven have a single HSPA that someone else already operates, so your work is the EUA side.

| Service                                                                                                                                                      | EUA | HSPA  | Who runs the HSPA                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --- | ----- | ----------------------------------------------------------- |
| [Physical consultation](/docs/uhi/v1/concepts/services/physical-consultation)                                                                                | Yes | Yes   | Any onboarded provider platform                             |
| [Ambulance booking](/docs/uhi/v1/concepts/services/ambulance-booking)                                                                                        | Yes | Yes   | Any onboarded ambulance operator platform                   |
| [Blood bank](/docs/uhi/v1/concepts/services/blood-bank)                                                                                                      | Yes | Yes   | Open to both roles. e-RaktKosh is the registered HSPA today |
| [PM-JAY HEM](/docs/uhi/v1/concepts/services/pmjay-hem)                                                                                                       | Yes | No    | NHA. There are no third party HSPA integrations             |
| [Jan Aushadhi Kendra](/docs/uhi/v1/concepts/services/jan-aushadhi-kendra) and [medicine search](/docs/uhi/v1/concepts/services/jan-aushadhi-medicine-search) | Yes | Named | PMBI                                                        |
| [AMRIT pharmacy](/docs/uhi/v1/concepts/services/amrit-pharmacy)                                                                                              | Yes | Named | HLL Lifecare Limited                                        |

Two bars on the HSPA role. For blood bank, your inventory data has to be maintained independently at a standard comparable to e-RaktKosh. For ambulance, availability has to be real time or near real time, and an integration built on manually maintained records will not be approved for production.

## The gate before any of this

Your application must have completed ABDM M2 with [HIE-CM](/docs/uhi/v1/getting-started/glossary#hie-cm). An application that has not completed M2 cannot be onboarded onto UHI services. The gate applies to every service on the network.

If M2 is not done, start at [M2 Health Information Provider, Health Information Provider Services](/docs/hiecm/v3/api/m2).

## The steps

Steps 1 to 5 are sandbox. Steps 6 and 7 are production.

1. **Express intent.** Reply to NHA's onboarding communication, or contact your NHA point of contact, and name the service you want to integrate.
2. **Generate your key pair.** Clone [github.com/NHA-ABDM/UHI](https://github.com/NHA-ABDM/UHI/tree/main/header_generator_utility) and run `Generator.java` with option 1. Send NHA the public key only.
3. **Fill the onboarding form.** [sandbox.abdm.gov.in](https://sandbox.abdm.gov.in/sandbox/v3/sandbox-registration) asks for your organisation details, your role, your HTTPS sandbox callback URL and your public key.
4. **Get sandbox access.** NHA emails sandbox credentials. Review the Swagger specification, and ask NHA for the UHI Postman collection for your service.
5. **Build and test.** Implement the stages your service covers, then run the test cases for your role.
6. **Get sign-off.** NHA reviews your test evidence and confirms in writing. Physical consultation also asks for a demo video.
7. **Go to production.** NHA promotes your integration. Update `consumer_id`, `consumer_uri`, `provider_id` and `provider_uri` to production values.

Two documents order steps 2 and 3 the other way round. The form asks for your public key, so generate the key pair first whichever order your document lists.

## The signing keys

Every UHI call is signed with an Ed25519 signature over a BLAKE-512 hash of the request body. The header format is on [UHI gateway](/docs/uhi/v1/concepts/network-and-protocol#signing). Onboarding needs the key pair.

| Item                        | What the documents say                                                                                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| How you generate it         | NHA's header generator utility, `Generator.java` option 1. It also produces signed headers: feed it your subscriber ID, your public key ID and the exact request payload as a string. |
| What you send NHA           | The public key only, registered against your subscriber ID during onboarding.                                                                                                         |
| What you keep               | The private key. Keep it out of your repository and out of your client applications.                                                                                                  |
| Your key ID                 | Appears inside the `Authorization` header as `<SUBSCRIBER_ID_FROM_NHA_ONBOARDING>\|<YOUR_PUBLIC_KEY_ID>\|ed25519`.                                                                    |
| The gateway's key           | Gateway calls to you carry `X-Gateway-Authorization`, key ID prefixed `gateway-nha`. Verify it rather than trusting the source address.                                               |
| Finding another party's key | `POST /api/v1/networkregistry/lookup` on the gateway returns a subscriber's registered public key. Both sides use it before a signed point to point call.                             |

## The callback URL you register

It is your `consumer_uri` if you are an EUA, and your `provider_uri` if you are an HSPA. Four rules come out of the documents.

- Publicly accessible over HTTPS. The gateway and the other party call it from outside your network.
- For an EUA, it must share a domain with your `consumer_id`.
- It is where the real answer arrives. The synchronous reply to any UHI call is an ACK receipt, not the business response. Do not block your request thread.
- You match the answer to your request on `transaction_id`. Several HSPAs can answer one search, and that field is the only thing tying their calls back to yours.

What sits behind that URL depends on your role and how far your service goes.

| Service and role                      | Endpoints you expose                                                                             |
| ------------------------------------- | ------------------------------------------------------------------------------------------------ |
| EUA, discovery only services          | `/on_search`                                                                                     |
| EUA, ambulance booking (first phase)  | `/on_search`, `/on_init`                                                                         |
| EUA, physical consultation            | `/on_search`, `/on_init`, `/on_confirm`, `/on_status`, `/on_update`, `/on_cancel`, `/on_message` |
| HSPA, ambulance booking (first phase) | `/search`, `/init`                                                                               |
| HSPA, physical consultation           | `/search`, `/init`, `/confirm`, `/status`, `/cancel`, `/on_update`, `/on_message`                |

The discovery only services are blood bank, PM-JAY HEM, Jan Aushadhi Kendra, Jan Aushadhi medicine search and AMRIT pharmacy.

On physical consultation, `/on_message` is mandatory for an EUA and optional for an HSPA. `/on_update` is consumed by both sides.

## The sandbox path

```text
Gateway base URI        https://uhigatewaysandbox.abdm.gov.inReference EUA           http://uhieuasandbox.abdm.gov.in/api/v1/euaServiceReference HSPA          https://hspasbx.abdm.gov.in/api/v1/hspaProduction gateway      https://uhigateway.abdm.gov.in
```

Those are NHA's own sandbox applications. If you are building an EUA, the reference HSPA answers your searches until a real one is registered against your test.

The Swagger specification sits at [uhigatewaysandbox.abdm.gov.in/swagger-ui](https://uhigatewaysandbox.abdm.gov.in/swagger-ui/index.html?urls.primaryName=v2.0.2#/). The documents do not agree on a version: physical consultation points at `v2.0.2`, PM-JAY HEM at `v2.0.1`. Check which one your onboarding contact expects.

The reference EUA and HSPA are also published as APKs, with recordings of the integration support calls.

## Before you ask for sign-off

A twenty row readiness checklist applies, whatever your service.

- ABDM M2 with HIE-CM is complete.
- Your Ed25519 key pair is generated and the public key is submitted.
- The onboarding form is submitted and sandbox access is configured.
- Your HTTPS callback URL is live and reachable from outside your network.
- Request signing is implemented, and you verify inbound signatures.
- Every endpoint your role and service requires is exposed and tested.
- Discovery is tested across each filter your service supports.
- Asynchronous handling is tested, including an empty result set and a response that never arrives.
- The test cases for your role pass, and you have the evidence to show.

Services that go beyond discovery add their own items. Physical consultation asks for the booking flow, the PIN, status transitions, terms display and a caching policy with a ceiling of 48 hours.

## Where to ask

There are two support levels. L1 covers technical integration: API errors, signing problems, sandbox access and endpoint configuration. L2 covers the onboarding form, milestone verification and compliance. The named contacts are in the onboarding communication NHA sends you. Use that rather than a name copied from a document that may have moved on.

For anything about these pages rather than about UHI itself, see [support](/docs/support).

## Next

- [UHI gateway](/docs/uhi/v1/concepts/network-and-protocol), for the message pattern, the context block and signing
- [Introduction](/docs/uhi/v1), for the two roles and how far each service goes
- [Physical consultation](/docs/uhi/v1/concepts/services/physical-consultation), the service with the full booking lifecycle
- [M2 Health Information Provider, Health Information Provider Services](/docs/hiecm/v3/api/m2), the prerequisite


---

# Introduction

The Ayushman Bharat Digital Mission ([ABDM](/docs/uhi/v1/getting-started/glossary#abdm)) is India's national health data network, run by the National Health Authority ([NHA](/docs/uhi/v1/getting-started/glossary#nha)). It is three gateways, not one, and this section documents the second of them.

[UHI](/docs/uhi/v1/getting-started/glossary#uhi) is the Unified Health Interface, [ABDM](/docs/uhi/v1/getting-started/glossary#abdm)'s open network for finding and booking a health service. After this page you will know which role to build, how far each service goes, and where the protocol is written down.

[HIE-CM](/docs/uhi/v1/getting-started/glossary#hie-cm) moves records that already exist. UHI finds a doctor, an ambulance or a unit of blood before any record exists.

## The gate before anything else

Your application must have completed ABDM [M2](/docs/hiecm/v3/api/m2) with HIE-CM before it can be onboarded to any UHI service. This applies to every service on the network. UHI sits on top of HIE-CM, it is not an alternative to it.

## Two roles

| Role                                               | Full name                           | What it does                                                                               |
| -------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------ |
| [EUA](/docs/uhi/v1/getting-started/glossary#eua)   | End User Application                | The patient facing app. Searches, shows results, books, displays status.                   |
| [HSPA](/docs/uhi/v1/getting-started/glossary#hspa) | Health Service Provider Application | The provider platform. Holds availability, answers searches, drives the booking lifecycle. |

The HSP is the hospital, clinic, doctor, ambulance operator or blood bank, and the HSPA is its digital interface. The [gateway](/docs/uhi/v1/getting-started/glossary#gateway) is the network's routing layer. Each service page says which roles it accepts.

## Services

A service is identified by fixed values inside the call, not by a different endpoint. All three documents behind this page use `core_version` `0.7.1`.

| Service                                                                       | Domain code     | Discovery             | Order and quote     | Booking and lifecycle                                                                            |
| ----------------------------------------------------------------------------- | --------------- | --------------------- | ------------------- | ------------------------------------------------------------------------------------------------ |
| [Physical consultation](/docs/uhi/v1/concepts/services/physical-consultation) | `nic2004:85111` | `search`, `on_search` | `init`, `on_init`   | `confirm`, `on_confirm`, `status`, `on_status`, `on_update`, `cancel`, `on_cancel`, `on_message` |
| [Ambulance booking](/docs/uhi/v1/concepts/services/ambulance-booking)         | `nic2008:86909` | `search`, `on_search` | `init`, `on_init`   | Not open for onboarding yet                                                                      |
| [Blood bank](/docs/uhi/v1/concepts/services/blood-bank)                       | `nic2008:86906` | `search`, `on_search` | Not in this service | Not in this service                                                                              |

Four more services have their own onboarding documents and their own pages: [Jan Aushadhi Kendra](/docs/uhi/v1/concepts/services/jan-aushadhi-kendra), [Jan Aushadhi medicine search](/docs/uhi/v1/concepts/services/jan-aushadhi-medicine-search), [AMRIT pharmacy](/docs/uhi/v1/concepts/services/amrit-pharmacy) and [PMJAY HEM](/docs/uhi/v1/concepts/services/pmjay-hem).

## Two transports in one flow

Discovery goes through the gateway, which broadcasts your one `search` to every registered HSPA in that domain, so several `on_search` calls come back. Everything after discovery is point to point between your EUA and the HSPA the patient chose. There is no central UHI API for those stages.

Every call is asynchronous and signed.

## Next

- [Network and protocol](/docs/uhi/v1/concepts/network-and-protocol), for the message pairs, the `context` block, Ed25519 signing and the network registry lookup
- [Onboarding](/docs/uhi/v1/getting-started/onboarding), for the route from M2 to sandbox credentials to production
- [Physical consultation](/docs/uhi/v1/concepts/services/physical-consultation), the service with the full booking lifecycle
- [Support](/docs/support)


---

# ABHA on UHI

[ABHA](/docs/uhi/v1/getting-started/glossary#abha) is the patient's account: a 14 digit number and a readable address such as `name@abdm`. UHI uses the address, never the number, and only as a name for the person the booking is for.

## Where it appears

| Field                     | Service                                                                       | Required  | Example                                                                                                     |
| ------------------------- | ----------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------- |
| `order.customer.id`       | [Physical consultation](/docs/uhi/v1/concepts/services/physical-consultation) | Yes       | `rahul.k001@sbx`                                                                                            |
| `order.customer.id`       | [Ambulance booking](/docs/uhi/v1/concepts/services/ambulance-booking)         | Mandatory | `91XXXXXXXXXX@sbx`                                                                                          |
| `chat.sender.person.id`   | Physical consultation                                                         | Yes       | The ABHA address of the sender, or the doctor's [HPR](/docs/uhi/v1/registries/hpr) ID when the doctor sends |
| `chat.receiver.person.id` | Physical consultation                                                         | Yes       | The other side of the same pair                                                                             |

The `@sbx` suffix in both examples is the sandbox one. Production addresses end `@abdm`, so an address hardcoded from a sandbox test will fail once you are promoted.

## What UHI does not do with it

Nothing is verified here. UHI carries the address through the booking; it does not check that it exists, does not authenticate the person behind it, and creates no ABHA of its own. A patient who has no ABHA gets one through [M1](/docs/hiecm/v3/api/m1) on HIE-CM, which is where creation, login and [KYC](/docs/uhi/v1/getting-started/glossary#kyc) live.

Nor does an ABHA address in a UHI message give anyone a right to the patient's records. Records move on HIE-CM, under a consent artefact, and never as part of a booking. See [Consent on HIE-CM](/docs/hiecm/v3/concepts/consent) if that is what you are building.

## Next

- [HPR on UHI](/docs/uhi/v1/registries/hpr), the practitioner side of the same booking
- [Physical consultation](/docs/uhi/v1/concepts/services/physical-consultation), where both appear in full


---

# HFR on UHI

The [HFR](/docs/uhi/v1/getting-started/glossary#hfr) is the national register of health facilities: hospitals, clinics, labs, imaging centres and pharmacies. On UHI it names the place behind a listing.

## Where it appears

| Field                                                            | Service                                                                                                                  | Required                      |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
| `catalog.providers[].fulfillments[].tags["@abdm/gov.in/hfr_id"]` | [AMRIT pharmacy](/docs/uhi/v1/concepts/services/amrit-pharmacy), one tag per store                                       | Listed in the field reference |
| `catalog.providers[].fulfillments[].agent.tags`                  | [Physical consultation](/docs/uhi/v1/concepts/services/physical-consultation), as `/hfr_id` beside the practitioner tags | No                            |

AMRIT pharmacy is the only UHI service in this portal whose catalogue carries the facility identifier as a field of its own. It is one of three things that service adds over the others.

## What the document does not fill in

The value appears as the placeholder `<HFR_ID>`, with no filled example published. The AMRIT page records the same gap for the store hours and the contact block. Treat the field's format as whatever the HFR itself issues, and confirm it against a real store entry before you rely on it.

## Where the ID comes from

Not from UHI. A facility is enrolled in the HFR through [M4](/docs/hiecm/v3/api/m4) on HIE-CM, and the create call there needs a professional token from an [HPR](/docs/uhi/v1/registries/hpr) ID with facility manager rights. UHI quotes the result.

## Next

- [Registries](/docs/uhi/v1/registries), for the four UHI touches and the one it owns
- [AMRIT pharmacy](/docs/uhi/v1/concepts/services/amrit-pharmacy), the catalogue this tag sits in


---

# HPR on UHI

The [HPR](/docs/uhi/v1/getting-started/glossary#hpr) is the national register of health professionals. On UHI it names the person a patient is booking: the doctor in a consultation.

## Where it appears

| Field                                                 | Stage                                                                                 | Required |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------- | -------- |
| `catalog.providers[].fulfillments[].agent.id`         | The catalogue an [HSPA](/docs/uhi/v1/getting-started/glossary#hspa) returns on search | Yes      |
| `catalog.providers[].fulfillments[].agent.tags`       | The same catalogue entry                                                              | No       |
| `order.fulfillment.agent.id`                          | The order, from select onward                                                         | Yes      |
| `chat.sender.person.id` and `chat.receiver.person.id` | Chat, when the doctor is one end of it                                                | Yes      |

## Two forms of the same identifier

The practitioner appears two ways in the same sample. `agent.id` carries the readable address, `<HPR_ADDRESS>`. The tag block beside it carries the numeric ID, `@abdm/gov.in/hpr_id`, as `<HPR_ID>`.

Send the address in `agent.id`. The tag is optional, and it sits with the other practitioner tags The same block also carries: `@abdm/gov.in/experience`, `/languages`, `/education`, `/hpr_id`, `/hfr_id` and `/hip_id`.

## Where the ID comes from

Not from UHI. A professional is registered in the HPR through [M4](/docs/hiecm/v3/api/m4) on HIE-CM, and UHI quotes what M4 wrote. If your HSPA lists a doctor who has no HPR ID, the catalogue entry has no valid `agent.id` to carry, and there is no UHI call that will mint one.

## Next

- [HFR on UHI](/docs/uhi/v1/registries/hfr), the facility the practitioner works in
- [M4 Registry Integration](/docs/hiecm/v3/api/m4), where both are written


---

# Registries

UHI touches four registries, and only one of them belongs to UHI. After this page you will know which identifier goes in which field, and which ones onboarding asks you for.

| Registry                             | Identifies                                                                                                                                                 | Where it appears in UHI                                                                                         |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Network registry                     | A subscriber on the UHI network: an [EUA](/docs/uhi/v1/getting-started/glossary#eua), an [HSPA](/docs/uhi/v1/getting-started/glossary#hspa) or the gateway | `POST /api/v1/networkregistry/lookup`, to fetch a counterparty's public key before a signed point to point call |
| [ABHA](/docs/uhi/v1/registries/abha) | The patient                                                                                                                                                | `order.customer.id`, and the person ids in chat                                                                 |
| [HPR](/docs/uhi/v1/registries/hpr)   | The practitioner                                                                                                                                           | `fulfillment.agent.id`, and an `hpr_id` tag                                                                     |
| [HFR](/docs/uhi/v1/registries/hfr)   | The facility or store                                                                                                                                      | An `hfr_id` tag on a fulfillment                                                                                |

## The network registry is UHI's own

The other three are ABDM registries that UHI quotes. The network registry is UHI's, and it holds something the others do not: the public key each subscriber registered at onboarding. Both sides of a signed call look the counterparty up in it. [UHI gateway](/docs/uhi/v1/concepts/network-and-protocol) has the lookup and the signing.

## Onboarding does not ask for the other three

The onboarding form asks for your organisation details, your role, your callback URL and your public key. It does not ask for an [HPR](/docs/uhi/v1/getting-started/glossary#hpr) ID or an [HFR](/docs/uhi/v1/getting-started/glossary#hfr) entry, and no UHI document in this portal makes either a condition of joining the network.

They arrive by the back door instead. Your application must have completed [M2](/docs/hiecm/v3/api/m2) with [HIE-CM](/docs/uhi/v1/getting-started/glossary#hie-cm) before it can be onboarded to any UHI service, and that route does require a facility in the HFR and a professional in the HPR. See [Onboarding](/docs/uhi/v1/getting-started/onboarding) for the gate, and [HIE-CM's registries](/docs/hiecm/v3/registries) for what M4 writes into them.

## What UHI never does

UHI creates no registry entry. It issues no ABHA number, registers no professional and enrols no facility. Every identifier in a UHI message was written by a milestone on HIE-CM and is being quoted here, which is why a wrong one fails at the far end rather than at the gateway.


---

# 15 September 2026

6 changes

### NHCX has API references

[NHCX API references](/docs/nhcx/v1/api) cover the exchange in 14 modules, from the session token and the participant registry to claims, payment notices and biometric authentication. Each of its 63 calls has its own page with the headers, the body and a request you can send, and each of the 21 callbacks you host has a page of its own. [Error codes](/docs/nhcx/v1/reference/error-codes) lists the codes recorded for the exchange gateway, the standard payer sheet and the PMJAY reference payer.

### Point your agent at NHCX

[Build with AI](/docs/nhcx/v1/getting-started/build-with-ai) connects your coding agent to the Docs MCP server, which searches the NHCX catalogue alongside HIE-CM's. `llms.txt` now lists an index for each NHCX API module, so an agent can fetch one module's pages as Markdown.

### Seven NHCX agent skills

Seven agent skills build NHCX into a hospital information system or a claims desk, one use case each: coverage, the insurance plan, pre-authorisation, the claim, payment, communication and reprocess. [Build with AI](/docs/nhcx/v1/getting-started/build-with-ai#install-a-skill) lists them with the command that installs each.

### Start on the NHCX sandbox

[Get your sandbox credentials](/docs/nhcx/v1/getting-started/get-your-sandbox-credentials) covers what you need before you register, the test participants and the dummy payer. The [Quickstart](/docs/nhcx/v1/getting-started/quickstart) then takes you from a session token to a participant search and a fetched certificate, with nothing built yet.

### The NHCX security audit has a page

[Security audit](/docs/nhcx/v1/go-live/security-audit) covers the functional and security tests every participant passes before production, and the certificates production onboarding reviews.

### Troubleshooting NHCX by what you see

[Troubleshooting](/docs/nhcx/v1/troubleshooting) starts from what you see rather than from the error code:

- Every call returns 401.
- Your callback URL is rejected.
- A 202 arrives and no callback follows.
- The recipient cannot decrypt your message.
- The payer rejects your bundle.
- Responses arrive against the wrong request.


---

# 16 September 2026

3 changes

### The API reference follows the specifications of 16 September 2026

Every endpoint page is now built from the specification set published on 16 September 2026. It covers eleven modules: the gateway, M1 to M4, P1 to P4, subscriptions, and Scan and Pay. Check the operations you call against [the API references](/docs/hiecm/v3/api).

### Each ABHA creation and login method is its own sequence

Every way to create an ABHA and every way to log in that the specification carries has its own sequence in the reference, one page per call in the order you make them. Start from [the M1 API reference](/docs/hiecm/v3/api/m1).

### Error pages list the codes the specifications return

Seven modules have an errors page, and each lists the codes its specification returns. Start from [the M1 error codes](/docs/hiecm/v3/api/m1/errors).


---

# 21 September 2026

4 changes

### NHCX error pages list their codes

This is a correction. [Error codes](/docs/nhcx/v1/reference/error-codes) said no code was recorded, and so did the errors page of every NHCX module. 310 codes were recorded all along, and the pages now list them: by who sent them on the reference page, and by the paths they arrive on under each module. An NHCX code reaches you sealed inside a callback rather than in the response to your call, which is why a page built from response examples found none.

### The NHCX plugin installs

This is a correction. The command on [Build with AI](/docs/nhcx/v1/getting-started/build-with-ai#install-the-plugin) failed, because the marketplace did not list the plugin it named. It does now. The plugin also carries three commands and an agent for Claude Code: `/nhcx-decode-error`, `/nhcx-preflight`, `/nhcx-prove-seal` and `nhcx-call-debugger`.

### NHCX skills install as a folder

This is a correction. The install box for an NHCX skill was empty, and the command behind it fetched three files that an NHCX skill does not have. Each skill is 59 files across eight directories, so the command now takes the archive. Each also gains a scaffold, and its router says where the folder came from, that it is a snapshot, and what its claims rest on.

### Build it well, for NHCX

[Build it well](/docs/nhcx/v1/getting-started/build-it-well) is new. It covers who refused a message, which sends are safe to repeat, how to match an answer to its request, and what to do when no answer comes.


---

# 22 September 2026

3 changes

### PHR calls carry the gateway session token, and their body fields are required

The [P1](/reference/hiecm-p1) and [P2](/reference/hiecm-p2) references showed 21 PHR application calls with no `Authorization` header and no required body fields. Every one of them takes the access token from the gateway session call, and every field the request body shows is required. Get profile, QR code and PHR card also take `X-AUTH-TOKEN` beside `X-token`. If your app sends those calls without the token, add it.

### The PHR public key is not the ABHA service's key

A [PHR](/docs/hiecm/v3/getting-started/glossary#phr) application encrypts the Aadhaar number, mobile number, OTP and password with the key from `GET /abha/api/v3/phr/app/login/public/certificate`, the first call in [P1](/docs/hiecm/v3/api/p1/endpoints/p1-certificate-and-session/01-p1-get-v3-phr-app-login-public-certificate). [Encryption](/docs/hiecm/v3/concepts/encryption) had sent every reader to the M1 certificate. Encrypt every PHR call with the PHR key.

### Consent request init and context notify take an id only

On [consent request init](/docs/hiecm/v3/api/m3/endpoints/m3-consent-management-data-flow-hiu/01-m3-post-consent-v3-request-init) the `hiu` block requires `id` alone; the reference had required `name` too, and the request example still sent it. On [link context notify](/docs/hiecm/v3/api/m2/endpoints/m2-abdm-hip-initiated-linking-hip/02-m2-post-hip-v3-link-context-notify) the `notification.hip` block requires `id` alone; the reference had required `name` and `type`. Neither extra field is needed.


---

# 23 September 2026

6 changes

### P2 consent, linking and share calls go to the gateway

The [P2](/reference/hiecm-p2) reference printed 17 calls under `/api/hiecm/` against `https://abhasbx.abdm.gov.in`, the ABHA service. They are gateway calls and go to `https://dev.abdm.gov.in`: consent requests and artefacts, auto approval, linking, discovery and patient share. The `/abha/api/v3/phr/app/` calls stay on the ABHA service. If your app built these URLs from the sample, change the host.

### List calls send their required query parameters

The samples on a list call now carry the query parameters the call requires, for example `?limit=5&offset=5&status=ALL` on listing subscription requests. Before, the sample sent the path alone and the call was refused. Listing subscription requests now requires `limit`, `offset` and `status`.

### PHR registration by Aadhaar number, and no email update

[P1](/docs/hiecm/v3/milestones/p1) lists registering an ABHA address from an Aadhaar number again, through the ABHA number the Aadhaar OTP creates. Updating the email on a PHR profile is deprecated and no longer listed in P2. On approving a subscription request, `hip` is optional.

### Subscriptions are part of P3, and gateway calls gain two fields

The subscription request and its notifications, a module of their own until now, are the first journey in [P3](/reference/hiecm-p3), beside the approve and deny calls they pair with. Old page links redirect. Listing providers takes optional `stateCode` and `districtCode`, and the discovery reply `on-discover` requires `X-HIU-ID`, as the PHR swagger declares.

### Try it fills in fixed values, and the gateway lists what it owns

In Try it, a field that takes only one value, such as `otpSystem` on an M1 use case or `grantType` on the session call, is filled in and locked. The response panel expands to the whole console, and long lines wrap. Callback bodies declared as a success or an error shape, such as [link on care context](/docs/hiecm/v3/api/m2/endpoints/m2-callbacks/02-m2-post-v3-link-on-carecontext), show their fields. The [gateway](/reference/hiecm-gateway) lists the bridge calls and the session call. Providers and government programmes are in [P2](/reference/hiecm-p2), the health locker list in [P4](/reference/hiecm-p4).

### P2 is Consents Management, and the patient share calls are named for the OPD

The P2 reference is [P2 Consents Management](/reference/hiecm-p2). Its patient share calls read OPD token generation and OPD Token History, in a journey called Quick OPD Registration. Updating the email is gone from every P2 call, not only from the list of journeys. The two PHR application pages are now [one page](/docs/hiecm/v3/concepts/participants/phr), which speaks in P1 to P3. The OpenID configuration, key set and update bridge service pages are gone; their old addresses redirect.


---

# What's new

Changes that affect what you can build against, newest first. Each entry links to what you can now read, run or consume.

## 23 September 2026

6 changes

- [P2 consent, linking and share calls go to the gateway](/docs/whats-new/2026-09-23#p2-consent-linking-and-share-calls-go-to-the-gateway)
- [List calls send their required query parameters](/docs/whats-new/2026-09-23#list-calls-send-their-required-query-parameters)
- [PHR registration by Aadhaar number, and no email update](/docs/whats-new/2026-09-23#phr-registration-by-aadhaar-number-and-no-email-update)
- [Subscriptions are part of P3, and gateway calls gain two fields](/docs/whats-new/2026-09-23#subscriptions-are-part-of-p3-and-gateway-calls-gain-two-fields)
- [Try it fills in fixed values, and the gateway lists what it owns](/docs/whats-new/2026-09-23#try-it-fills-in-fixed-values-and-the-gateway-lists-what-it-owns)
- [P2 is Consents Management, and the patient share calls are named for the OPD](/docs/whats-new/2026-09-23#p2-is-consents-management-and-the-patient-share-calls-are-named-for-the-opd)

## 22 September 2026

3 changes

- [PHR calls carry the gateway session token, and their body fields are required](/docs/whats-new/2026-09-22#phr-calls-carry-the-gateway-session-token-and-their-body-fields-are-required)
- [The PHR public key is not the ABHA service's key](/docs/whats-new/2026-09-22#the-phr-public-key-is-not-the-abha-services-key)
- [Consent request init and context notify take an id only](/docs/whats-new/2026-09-22#consent-request-init-and-context-notify-take-an-id-only)

## 21 September 2026

4 changes

- [NHCX error pages list their codes](/docs/whats-new/2026-09-21#nhcx-error-pages-list-their-codes)
- [The NHCX plugin installs](/docs/whats-new/2026-09-21#the-nhcx-plugin-installs)
- [NHCX skills install as a folder](/docs/whats-new/2026-09-21#nhcx-skills-install-as-a-folder)
- [Build it well, for NHCX](/docs/whats-new/2026-09-21#build-it-well-for-nhcx)

## 16 September 2026

3 changes

- [The API reference follows the specifications of 16 September 2026](/docs/whats-new/2026-09-16#the-api-reference-follows-the-specifications-of-16-september-2026)
- [Each ABHA creation and login method is its own sequence](/docs/whats-new/2026-09-16#each-abha-creation-and-login-method-is-its-own-sequence)
- [Error pages list the codes the specifications return](/docs/whats-new/2026-09-16#error-pages-list-the-codes-the-specifications-return)

## What gets an entry

An entry has to change what you build or what you must go back and fix. Six kinds qualify:

| Kind                                      | Example                                                                |
| ----------------------------------------- | ---------------------------------------------------------------------- |
| New coverage                              | A module, role or gateway you can now build against                    |
| A correction                              | A documented fact was wrong, so what you built against it may be wrong |
| A source republished                      | A specification changed, so a documented behaviour changed             |
| An operation renamed, added or withdrawn  | Your calls have to change                                              |
| A new artefact you can consume            | An OpenAPI file, an agent skill, an MCP server, the Markdown routes    |
| A procedure documented for the first time | The sandbox exit process, the security audit                           |

Page layout, navigation, wording and visual changes do not get an entry. They change nothing you have to act on, and a changelog that carries them buries the entries that do.