PM-JAY HEM Discovery

Discover PM-JAY empanelled hospitals through UHI search and on_search.

PM-JAY Hospital Empanelment Discovery helps an EUA find PM-JAY empanelled hospitals through UHI. Phase 1 supports only search and on_search. Use this page with the shared UHI guide at /docs/uhi/v1/network-and-protocol.

Phase 1 only

Use this service for hospital discovery only. Do not add appointment, referral, or admission flows yet.

Parameter	Value
Service	PM-JAY Hospital Empanelment Discovery
Domain code	nic2004:85112
Core version	0.7.1
Phase 1 scope	search and on_search only
Service owner	NHA, ABDM

Roles

Role	Actor	Responsibility
EUA	A user app	Send search requests to the Gateway. Receive on_search callbacks.
HSPA	PM-JAY HEM HSPA	Return PM-JAY hospital records from the HEM database.
Gateway	UHI Gateway	Route search and on_search messages. Return ACK or NACK.

Flow

sequenceDiagram
participant EUA
participant Gateway
participant HSPA as PM-JAY HEM HSPA
EUA->>Gateway: search
Gateway-->>EUA: ACK
Gateway->>HSPA: search
HSPA->>Gateway: on_search
Gateway->>EUA: on_search
EUA-->>Gateway: ACK

Service identity

Use exact values

Set these values exactly. Wrong case or a wrong code can stop HSPA responses.

Parameter	Value	Use
domain	nic2004:85112	Use in context.domain.
fulfillment.type	PMJAYHEM	Use in message.intent.fulfillment.type.
item.descriptor.code	PMJAY	Use in message.intent.item.descriptor.code.
item.descriptor.name	PMJAY	Use in message.intent.item.descriptor.name.
item.descriptor.flag	false	Use in message.intent.item.descriptor.flag.

Authentication

Sign each UHI request with Ed25519 and a BLAKE-512 body digest. Follow the shared header, ACK, and callback rules at /docs/uhi/v1/network-and-protocol.

Add a fallback for GPS

GPS search can return partial results in low density areas. Offer district or pincode search as a fallback.

Search type	Mandatory fields	Optional fields	Use case
State only	state.name, state.code	None	Find hospitals in one state.
State + district	state.name, state.code	district.name, district.code	Narrow results to one district.
State + speciality	state.name, state.code	category.descriptor.name, category.descriptor.code	Filter by one speciality.
State + facility name	state.name, state.code	provider.descriptor.name	Find a hospital by name.
State + pincode	state.name, state.code	address.area_code	Find hospitals in one pincode.
State + GPS	state.name, state.code	location.gps, radius.type, radius.value, radius.unit	Find hospitals near coordinates.

Field references

search context

Field	Type	Rule
domain	string	Use nic2004:85112.
country	string	Use IND.
city	string	Use an STD code, such as std:011.
action	string	Use search.
core_version	string	Use 0.7.1.
consumer_id	string	Use your EUA ID.
consumer_uri	URL	Use your HTTPS callback URL.
message_id	UUID	Use a unique value for each call.
transaction_id	UUID	Reuse this value in the on_search flow.
timestamp	ISO 8601	Use the request time.

search message.intent

Field path	Type	Required	Rule
fulfillment.type	string	Yes	Use PMJAYHEM.
fulfillment.start.time.timestamp	datetime	Yes	Set the start time.
fulfillment.end.time.timestamp	datetime	Yes	Set the end time.
item.descriptor.code	string	Yes	Use PMJAY.
item.descriptor.name	string	Yes	Use PMJAY.
item.descriptor.flag	boolean	Yes	Use false.
location.state.name	string	Yes	Use the state name in CAPS.
location.state.code	string	Yes	Use the numeric state code.
location.district.name	string	No	Use the district name in CAPS.
location.district.code	integer	No	Use the numeric district code.
location.gps	string	No	Use lat,long format.
location.radius.type	string	No	Use CONSTANT for GPS search.
location.radius.value	float	No	Use radius in km.
location.radius.unit	string	No	Use km.
address.area_code	integer	No	Use a 6-digit pincode.
category.descriptor.name	string	No	Use a speciality name.
category.descriptor.code	integer	No	Use a speciality code.
provider.descriptor.name	string	No	Use a hospital name.

on_search provider record fields

NABH flag quality

Treat descriptor.flag as information only. Some records may not set this value.

Field path	Type	Rule
catalog.providers[].id	string	PM-JAY HEM hospital ID.
catalog.providers[].descriptor.name	string	Hospital name.
catalog.providers[].descriptor.code	string	G for Government or P for Private.
catalog.providers[].descriptor.flag	boolean	NABH flag, if present.
catalog.providers[].descriptor.short_desc	string	State empanelment context.
catalog.providers[].descriptor.long_desc	string	Empanelment status text.
catalog.providers[].categories[].descriptor.name	string	Speciality name.
catalog.providers[].categories[].descriptor.code	integer	Speciality code.
catalog.providers[].fulfillments[] type Establishment Date	string	Hospital establishment year.
catalog.providers[].fulfillments[] type Empaneled Date	string	PM-JAY empanelment date.
catalog.providers[].location.gps	string	Hospital lat,long.
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	PM-JAY nodal officer number.

Sample payloads

Use one transaction_id for one search flow. The on_search context.transaction_id must match the search context.transaction_id.

search — by state

{
  "context": {
    "domain": "nic2004:85112",
    "country": "IND",
    "city": "std:011",
    "action": "search",
    "core_version": "0.7.1",
    "consumer_id": "<your-eua-id>",
    "consumer_uri": "<your-https-callback-url>",
    "message_id": "dfa04e10-63ec-11ed-9f98-49dd5c7c4d8a",
    "timestamp": "2022-11-14T07:20:54.005277Z",
    "transaction_id": "dfa04e10-63ec-11ed-9f98-49dd5c7c4d8a"
  },
  "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", "code": "28" }
      }
    }
  }
}

on_search sample

The source has a longer catalog. This sample keeps 1 provider item.

on_search — PM-JAY HEM response

{
  "context": {
    "domain": "nic2004:85112",
    "action": "on_search",
    "consumer_id": "eua-nha",
    "consumer_uri": "<eua-callback-url>",
    "provider_id": "hspa-nha",
    "provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
    "transaction_id": "dfa04e10-63ec-11ed-9f98-49dd5c7c4d8a",
    "message_id": "<response-message-id>"
  },
  "message": {
    "catalog": {
      "descriptor": {
        "name": "PMJAY HSPA",
        "short_desc": "Pradhan Mantri Jan Arogya Yojana - Hospital Engagement Module"
      },
      "providers": [
        {
          "id": "HOSP27G13867",
          "descriptor": {
            "name": "General Hospital Wardha",
            "code": "G",
            "flag": false
          },
          "categories": [
            { "descriptor": { "name": "Cardiology", "code": 100002 } },
            { "descriptor": { "name": "General Medicine", "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", "code": "517" },
            "state": { "name": "Andhra Pradesh", "code": 28 },
            "country": { "name": "INDIA" }
          },
          "contact": {
            "phone": "9966753790",
            "email": "test@gmail.com",
            "tags": { "nodalOfficerNumber": "9966753790" }
          }
        }
      ]
    }
  }
}

Service-specific masters

Speciality master list

Fetch the full speciality master

The source does not print the full speciality master list. Use the API below to fetch the full list.

Code	Speciality
100002	Cardiology
100005	General Medicine

Speciality API

sandbox — fetch PM-JAY specialities

curl --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"
  }'

production — fetch PM-JAY specialities

curl --location 'https://apisprod.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"
  }'

Known limitations

Add district or pincode fallback for GPS search.
Treat descriptor.flag as optional information.
Set a timeout for on_search callbacks.
Add client-side pagination for large catalogs.
Keep appointment and referral outside Phase 1.
Show a PM-JAY portal link for package details.

Onboarding steps

Use this service checklist with /docs/uhi/v1/onboarding.

Express intent

Contact your NHA point of contact for PM-JAY HEM onboarding.

Complete the form

Submit your organisation details, EUA role, HTTPS callback URL, and public key.

Create your key pair

Run Generator.java Option 1 from the NHA UHI repository.

Test in sandbox

Use the UHI Postman Collection and the Gateway API docs.

Request go-live

Request production access after NHA approves your sandbox tests.

Technical prerequisites

M2 prerequisite

Complete ABDM M2 with HIECM before PM-JAY HEM onboarding. NHA treats this as a hard prerequisite.

EUA prerequisites

Use an ABDM-compliant app with M2 of HIECM complete.
Publish an HTTPS consumer_uri for on_search callbacks.
Create UHI Authorization headers for search requests.
Accept asynchronous on_search responses.
Use the UHI Postman Collection for sandbox tests.

HSPA prerequisites

Do not apply as a third-party HSPA for this service.
Use the NHA PM-JAY HEM HSPA as the provider side.

Resources and support

Resource	Link or detail
Key utility	github.com/NHA-ABDM/UHI/tree/main/header_generator_utility
Gateway YAML	https://uhigatewaysandbox.abdm.gov.in/swagger-docs/v2.0.1/Gateway.yaml
Swagger UI	https://uhigatewaysandbox.abdm.gov.in/swagger-ui/index.html?urls.primaryName=v2.0.1
UHI reference app	https://drive.google.com/file/d/1sAs8lIqPu-uMxd6-eM9AOJ2MiWhvikZH/view?usp=sharing
PM-JAY portal	https://pmjay.gov.in
Onboarding docs	https://abdm.gov.in/uhi/resources/onboarding-documentation
Support	abdm.cons11@nha.gov.in, abdm.cons50@nha.gov.in

Integration test cases

Source category count

The source lists categories A through E only. It does not include a Category F table.

Positive cases

Treat all cases as happy path cases unless the table says otherwise.

Category A — context validation

Case ID	Test case	Action	Pass criteria
TC-A01	Valid context fields	Send search with all mandatory context fields.	ACK arrives without error.
TC-A02	transaction_id match	Compare search and on_search transaction_id.	IDs match exactly.
TC-A03	Domain mirror	Inspect context.domain in on_search.	Value is nic2004:85112.

Case ID	Test case	Action	Pass criteria
TC-B01	State only	Send state.name and state.code.	Providers belong to the state.
TC-B02	State + district	Add district.name and district.code.	Providers belong to the district.
TC-B03	State + speciality	Add category.descriptor fields.	Each provider has the speciality.
TC-B04	State + facility name	Add provider.descriptor.name.	Results include the input name.
TC-B05	State + pincode	Add address.area_code.	Results match the pincode area.
TC-B06	State + GPS + radius	Add GPS and radius fields.	Provider GPS falls inside the radius.

Category C — on_search response validation

Case ID	Test case	Action	Pass criteria
TC-C01	Callback receipt	Monitor consumer_uri after search.	Payload arrives before timeout.
TC-C02	Provider ID	Inspect providers[].id.	All IDs are non-null strings.
TC-C03	Core provider fields	Inspect id, name, GPS, and phone.	No required value is empty.
TC-C04	Empanelment date	Inspect Empaneled Date fulfillment.	Timestamp has a value.
TC-C05	Establishment date	Inspect Establishment Date fulfillment.	Timestamp has a value.
TC-C06	GPS parse	Parse providers[].location.gps.	Value has 2 decimal numbers.
TC-C07	Nodal officer number	Inspect contact.tags.nodalOfficerNumber.	Value is a numeric string.
TC-C08	Speciality categories	Inspect categories[].descriptor fields.	Name and code are present.
TC-C09	Hospital type code	Inspect descriptor.code.	Value is one character.

Category D — UX and best practice compliance

Case ID	Test case	Method	Pass criteria
TC-D01	Service access	Test home screen path.	User reaches it in 3 taps or fewer.
TC-D02	Service label	Inspect the feature label.	Label says PM-JAY hospital search clearly.
TC-D03	Brand footer	Review the search screen.	UHI, PMJAY, and ABDM appear.
TC-D04	GPS search	Test with device GPS.	Results match the device area.
TC-D05	Manual location	Test state, district, or pincode.	Results match the input location.
TC-D06	Empty result message	Search a valid empty area.	User sees next steps.
TC-D07	Result disclaimer	Inspect result screen.	Disclaimer appears.
TC-D08	App category	Audit navigation.	Service appears under a health module.

Category E — edge cases

Case ID	Test case	Action	Pass criteria
TC-E01	Large result set	Search a high-density state.	App renders the list without crash.
TC-E02	Empty catalog	Search an empty area.	App shows a fallback message.
TC-E03	No on_search before timeout	Simulate an absent HSPA reply.	App shows a timeout message.

Sources

UHI PM-JAY HEM Service - Integrator Onboarding v1.4

PreviousPhysical Consultation Next Blood Bank Discovery