HMIS Integration Guide
Configure an HMIS to run PMJAY claims through NHCX with policy, eligibility, biometric, preauthorisation, claim, and payment flows.
This guide maps the PMJAY claim flow to HMIS features and NHCX APIs. Use it after you understand the base NHCX protocol.
Work in progress
The source says the FRD can change. Verify endpoint paths, workflow IDs, and payload rules with the latest NHCX portal.
What PMJAY adds to NHCX
| PMJAY addition | HMIS requirement |
|---|---|
| InsurancePlan use | Load package costs, STGs, documents, and claim conditions from the plan. |
| Biometric authentication | Create a beneficiary user token for preauthorisation and discharge. |
| Structured clinical data | Send ABDM Health Information Type bundles as supporting information. |
| Query response flow | Respond with the preauth or claim workflow ID. Do not use Communication Request for PMJAY claim queries. |
Sandbox configuration
| Value | Use |
|---|---|
| Participant ID | Identify the provider in NHCX. |
| Client ID | Request gateway access. |
| Registry ID | Use it as the sandbox provider ID. |
| Payer ID | Route the request to the selected PMJAY payer. |
| Sample member ID | Test policy and eligibility scenarios. |
| Public and private key | Encrypt outgoing payloads and decrypt callbacks. |
Configure NHCX access
Store the sandbox base URL, client ID, client secret, and participant ID.
Register callbacks
Expose callback endpoints for InsurancePlan, CoverageEligibility, preauth, claim, task, and payment notice.
Configure PMJAY masters
Map provider IDs, payer IDs, policy codes, package codes, HPR IDs, and HFR IDs.
Store plan data
Store the InsurancePlan response in a structured table.
Run exit tests
Run every happy flow, query flow, rejection flow, and payment flow.
High-level HMIS flow
sequenceDiagram participant HMIS participant NHCX participant Payer HMIS->>NHCX: Get policies HMIS->>NHCX: InsurancePlan request NHCX->>Payer: Route plan request Payer-->>HMIS: InsurancePlan callback HMIS->>NHCX: CoverageEligibility check Payer-->>HMIS: Eligibility callback HMIS->>Payer: Biometric auth HMIS->>NHCX: Preauth submit Payer-->>HMIS: Preauth callback HMIS->>Payer: Biometric auth at discharge HMIS->>NHCX: Claim submit Payer-->>HMIS: Claim callback Payer-->>HMIS: Payment Notice HMIS->>NHCX: Payment acknowledgement
API map
| Step | API | Callback | Main purpose |
|---|---|---|---|
| Policy lookup | /participant/get/policies | Not stated | Find linked policies for a beneficiary. |
| Insurance plan | /v1/insuranceplan/request | /v1/insuranceplan/on_request | Fetch provider-specific plan rules. |
| Eligibility | /v1/coverageeligibility/check | /v1/coverageeligibility/on_check | Validate policy, benefits, and documents. |
| Biometric init | /hcx/abha/biometric/auth/init | Synchronous response | Start fingerprint, iris, or face authentication. |
| Biometric verify | /hcx/abha/biometric/auth/verify | Synchronous response | Create the user token. |
| Biometric refresh | /hcx/abha/biometric/auth/refresh/token | Synchronous response | Refresh the user token. |
| Preauthorisation | /v1/preauth/submit | /v1/preauth/on_submit | Submit the preauth Claim bundle. |
| Preauth cancel | /v1/task/submit | /v1/task/on_submit | Cancel an active preauth. |
| Claim | /v1/claim/submit | /v1/claim/on_submit | Submit the final Claim bundle. |
| Reprocess | /v1/task/submit | /v1/task/on_submit | Request review after rejection or partial payment. |
| Payment notice | Payer callback | /v1/paymentnotice/on_request | Receive payment status and reconciliation data. |
InsurancePlan flow
Call InsurancePlan before preauthorisation or claim work.
The response can exceed 20 MB.
Store it in a queryable format.
Use version control for package and tariff updates.
| Input | Notes |
|---|---|
| Provider ID | Use the registry ID or mapped HFR ID. |
| Policy code | Use the beneficiary policy code. |
| Participant ID | Identify the sender. |
Refresh the plan at least weekly.
Refresh it immediately after a payer policy change.
The scenario sheet says a 15 day refresh can apply.
Use the shorter interval unless the payer says otherwise.
CoverageEligibility purposes
| Purpose | When to call | Returned data |
|---|---|---|
discovery | Use when policy details are not available. | Active coverages for the beneficiary. |
validation | Use after registration. | Policy status, wallet balance, and family limit. |
benefits | Use before preauth or enhancement. | Plan benefits and used amounts. |
auth-requirements | Use after package selection. | Documents, STGs, and preauth requirements. |
Biometric authentication
PMJAY requires biometric authentication for ABHA-linked beneficiaries. Perform it at registration, preauthorisation, and discharge. Use the exemption consent document when authentication cannot happen.
| Token | Validity | HMIS action |
|---|---|---|
| User token | 30 minutes | Pass it with PMJAY claim events. |
| Refresh token | 15 days | Refresh before expiry. |
{
"scope": ["abha-login", "aadhaar-bio-verify"],
"loginHint": "abha-number",
"loginId": "91-XXXX-XXXX-1234",
"otpSystem": "aadhaar",
"authMode": "FINGERPRINT"
}Preauthorisation rules
Call CoverageEligibility with auth-requirements before preauthorisation.
Attach all mandatory documents and questionnaire responses.
Set questionnaire responses in supportingInfo with category INF, code AT, and a reference value.
Do not raise preauthorisation more than 1 day before admission.
| Scenario | How to submit |
|---|---|
| Auto approval or manual review | Use the standard preauthorisation bundle. |
| Resubmission | Use the preauth reprocess workflow ID. |
| Enhancement | Include approved treatments and new treatments. |
| Query response | Use the preauth query response workflow ID. |
| Cancellation | Submit a Task with code cancel. |
Claim rules
PMJAY does not use a separate discharge workflow. Send discharge details inside the claim request. Perform biometric authentication at discharge. Use the exemption consent document when authentication cannot happen.
| Required date | Code | Category code |
|---|---|---|
| Registration date | EDT | OTH |
| Admission date | ADDD | ADMD |
| Surgery date | ADDD | SURD |
| Discharge date | ADDD | DSCHD |
| Discharge status | DTH | DIS |
Structured data
Send clinical evidence through supportingInfo and DocumentReference.
Use a Base64-encoded FHIR Bundle for structured health records.
Set contentType to application/json or application/fhir+json.
Use a PDF or image only for unstructured documents.
| Evidence type | Category codes | Value type |
|---|---|---|
| Structured data | DIA, HDS, CD, INF | Reference |
| Unstructured data | POI, POA, DOB, DEF, FIR, ATT | Attachment |
Error handling
Return clear error messages to users. Log every exception with the correlation ID. Do not expose stack traces in production. Use standard HTTP status codes. Show NHCX error codes and payer error codes in a support view.
Sources
- pmjay-hmis-integration-guide.md (NHCX sandbox portal)