Skip to main content

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 side integration. NHA runs the single HSPA. No third party builds one for this service.

PartyWho runs itWhat it does here
EUAYou, or any PHR appSends the search. Receives the on_search. Renders the hospital list.
UHI GatewayNHAValidates and routes the search. Relays the on_search back to you.
PM-JAY HEM HSPANHAQueries the HEM database. Builds the on_search catalog.

Signing, onboarding and Gateway base URLs are shared across UHI. See UHI services.

Before you onboard​

Your application must have completed HIE-CM Milestone 2 as an 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.

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.

StepWho actsWhat happens
1Your systemPOST /search to the Gateway with state, plus any optional filters.
2GatewayReturns HTTP 200 ACK immediately.
3GatewayPOSTs the search to the PM-JAY HEM HSPA.
4PM-JAY HEM HSPAQueries the HEM database.
5PM-JAY HEM HSPAPOSTs on_search to the Gateway with matching hospital records.
6GatewayPOSTs the on_search to your consumer_uri.
7Your systemACKs 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.

ParameterValueWhere it goes
domainnic2004:85112context.domain in every call
fulfillment.typePMJAYHEMmessage.intent.fulfillment.type
item.descriptor.codePMJAYmessage.intent.item.descriptor.code
item.descriptor.namePMJAYmessage.intent.item.descriptor.name
item.descriptor.flagfalsemessage.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 typeMandatoryOptional fields addedUse case
State onlystate.name, state.codenoneEvery empanelled hospital in a state
State and districtstate.name, state.codedistrict.name, district.codeNarrow to one district
State and specialitystate.name, state.codecategory.descriptor.name, category.descriptor.codeFilter by clinical speciality
State and facility namestate.name, state.codeprovider.descriptor.nameFind a hospital by name
State and pincodestate.name, state.codeaddress.area_codeSearch a pincode area
State and GPSstate.name, state.codelocation.gps, radius.type, radius.value, radius.unitProximity 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.

# Sandbox
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"}'

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​

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.

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​

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.

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.

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.

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​

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.

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: 9966753790
          email: test@gmail.com
          tags.nodalOfficerNumber: 9966753790

Field reference​

search: context​

All fields are mandatory.

FieldTypeValue
domainstringnic2004:85112, fixed
countrystringIND, fixed
citystringSTD code, for example std:011
actionstringsearch, fixed
core_versionstring0.7.1
consumer_idstringYour registered EUA identifier
consumer_uristringYour HTTPS callback URL
message_idUUIDFresh per call. Never reuse.
transaction_idUUIDFresh per search session. The on_search copies it.
timestampISO 8601Request time

search: message.intent​

Field pathTypeMandatoryDescription
fulfillment.typestringYesPMJAYHEM, fixed
fulfillment.start.time.timestampdatetimeYesStart of the search window
fulfillment.end.time.timestampdatetimeYesEnd of the search window
item.descriptor.codestringYesPMJAY, fixed
item.descriptor.namestringYesPMJAY, fixed
item.descriptor.flagbooleanYesfalse, fixed
location.state.namestringYesState name in capitals, for example ANDHRA PRADESH
location.state.codestringYesNumeric state code, for example 28
location.district.namestringNoDistrict name in capitals
location.district.codeintegerNoNumeric district code
location.gpsstringNolat,long, for example 17.378,78.436
location.radius.typestringNoCONSTANT. Required with a GPS search.
location.radius.valuefloatNoRadius in km, for example 13.0
location.radius.unitstringNokm
address.area_codeintegerNo6 digit pincode
category.descriptor.namestringNoSpeciality name, for example Cardiology
category.descriptor.codeintegerNoSpeciality code, for example 100002
provider.descriptor.namestringNoHospital or facility name

on_search: provider records​

Field pathTypeDescription
catalog.providers[].idstringPM-JAY HEM hospital ID, for example HOSP27G13867
catalog.providers[].descriptor.namestringHospital name
catalog.providers[].descriptor.codestringG government, P private
catalog.providers[].descriptor.flagbooleanNABH accreditation. May be unpopulated.
catalog.providers[].descriptor.short_descstringState level empanelment context
catalog.providers[].descriptor.long_descstringEmpanelment status description
catalog.providers[].categories[].descriptor.namestringSpeciality name
catalog.providers[].categories[].descriptor.codeintegerSpeciality code
catalog.providers[].fulfillments[] with type: Establishment DatestringYear the hospital was established
catalog.providers[].fulfillments[] with type: Empaneled DatestringDate of PM-JAY empanelment
catalog.providers[].location.gpsstringlat,long of the hospital
catalog.providers[].location.addressstringStreet address
catalog.providers[].location.city.namestringCity name
catalog.providers[].location.district.namestringDistrict name
catalog.providers[].location.district.codestringDistrict code
catalog.providers[].location.state.namestringState name
catalog.providers[].location.state.codeintegerState code
catalog.providers[].contact.phonestringHospital phone number
catalog.providers[].contact.emailstringHospital email
catalog.providers[].contact.tags.nodalOfficerNumberstringNodal officer number for PM-JAY questions

Known limitations​

These apply to the current phase.

LimitationWhat to do
GPS search can return incomplete results where hospital density is lowOffer district or pincode search as a fallback next to GPS
descriptor.flag, the NABH accreditation flag, is not consistently populatedDo not filter on it. Show it when present, otherwise say nothing.
on_search responses arrive asynchronously with no end of results signalSet a timeout window. Show results as they arrive.
No pagination on on_searchHandle large payloads without blocking the UI. Paginate on the client for display.
No booking or referralScope your UI to discovery
The covered procedure list can lag real package changesShow 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.

CategoryWhat it checks
A, context validationAll mandatory context fields present. transaction_id in on_search matches the originating search. domain mirrors correctly.
B, search filtersOne test per supported filter variant, checking that results honour the filter.
C, on_search responseProvider ID present and non null. Core fields present. Empanelment and establishment dates present. GPS parseable. Nodal officer number present. Specialities returned.
D, user experienceThe 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 casesA 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 linked discharge summaries and multilingual voice are named as the third. Dates for either are not yet published.

Next​

Last updated on