Integration Handbook

This page distils the large PMJAY handbook for HMIS teams. It keeps the process, roles, milestones, sequences, and mandatory requirements. It omits most payload tables.

Reader roles

Business outcome

The HMIS must identify the payer, confirm a linked policy, and prepare cashless admission data. It must fetch InsurancePlan rules before benefit selection. It must submit preauthorisation, claim, reprocess, and payment acknowledgement transactions. It must receive payer callbacks asynchronously.

End-to-end lifecycle

flowchart TD
A[Payer discovery] --> B[Policy discovery]
B --> C[InsurancePlan fetch]
C --> D[Coverage eligibility]
D --> E[Biometric authentication]
E --> F[Preauthorisation]
F --> G{Payer decision}
G -->|Approved| H[Treatment and discharge]
G -->|Query| I[Query response]
I --> F
G -->|Rejected| J[Close or reprocess]
H --> K[Claim submission]
K --> L{Claim decision}
L -->|Approved| M[Payment notice]
L -->|Query| N[Claim query response]
N --> K
L -->|Rejected or partial| O[Reprocess if valid]
M --> P[Payment acknowledgement]

Cashless admission sequence

Protocol requirements

All NHCX transaction payloads use JWE Compact Serialization. Encrypt the FHIR Bundle before submission. Decrypt each callback with the provider private key. Return HTTP 202 within 30 seconds for each callback.

{
  "alg": "RSA-OAEP-256",
  "enc": "A256GCM",
  "x-hcx-sender_code": "1000004446@hcx",
  "x-hcx-recipient_code": "1518@hcx",
  "x-hcx-api_call_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "x-hcx-request_id": "f0e1d2c3-b4a5-6978-0fed-cba987654321",
  "x-hcx-correlation_id": "11223344-5566-7788-99aa-bbccddeeff00",
  "x-hcx-workflow_id": "12",
  "x-hcx-timestamp": "2026-03-19T11:46:34+05:30",
  "x-hcx-status": "request.initiated",
  "x-hcx-ben-abha-id": "91711234567890"
}

Authentication and gateway

Request an NHCX token with client credentials. Refresh the token before 1200 seconds. Fetch the payer certificate before encryption. Try X.509 import first. Use SPKI as a fallback for short keys.

Workflow IDs

Core API sequences

InsurancePlan

Send a FHIR Task with code poll. Include policyNumber, providerId, or both. Receive an InsurancePlan bundle through /insuranceplan/on_request. Store InsurancePlan, Organization, and Questionnaire entries.

CoverageEligibility

Send a CoverageEligibilityRequest with purpose validation, benefits, or auth-requirements. Include Patient, Organization, Coverage, and PractitionerRole references. Include items for auth-requirements. Read inforce, benefit amounts, exclusions, and authorization support codes.

Preauthorisation

Send a Claim bundle with Claim.use preauthorization. Include patient identity, coverage, provider, insurer, diagnosis, procedure, care team, items, and supporting information. Use workflow ID 12 for a new request. Use workflow ID 19 for a query response. Use /task/submit with code cancel for cancellation.

Claim

Send a Claim bundle with Claim.use claim. Reuse approved preauth data when possible. Replace estimates with final bill amounts. Add discharge summary, operative notes, diagnostics, and final bills. PMJAY merges discharge and claim into one claim flow.

Reprocess

Use a Task resource with code reprocess. Link it to the original claim number. Add the reason code, evidence, and supporting documents. Parse the nested ClaimResponse from the Task callback.

Payment

Receive a Task bundle with PaymentNotice and PaymentReconciliation. Store the net amount, TDS amount, payment date, and UTR. Acknowledge the notice with a Task output code paymentack.

Parser rules

Do not treat outcome=complete as approval by itself. Always check the adjudication reason code.

Supporting information codes

Error families

Communication lifecycle caveat

The handbook documents a Communication Request lifecycle. The PMJAY FRD says PMJAY claim queries do not use the Communication API. Use the preauth or claim query workflow for PMJAY claim queries. Use Communication Request only when the payer confirms a separate notification use case.