NHCX is moving from pilot to default: IRDAI has directed insurers onto it, the DHIS incentive pays hospitals to upgrade, and PMJAY claims are converging onto the same rails. But the official onboarding path is scattered across a PPTX on GitHub, 27 documents on the sandbox portal, and answers buried in NHA's discussion threads.
This guide assembles that path into one checklist — validated against NHA's own integrator guide, Postman collections, and sandbox-exit documents — and answers the question every HIMS team asks first: what exactly is in scope for us?
Prerequisites: What You Need Before Touching the NHCX Sandbox
- HFR Facility ID — your hospital/facility registered in the Health Facility Registry (facility.abdm.gov.in). Providers use the HFR ID as their registry ID on NHCX.
- ABDM M1 production certificate — not just M1 development: NHA requires your software to be live on M1 production before NHCX onboarding starts. Your existing ABDM client-ID gets NHCX roles attached to it — no separate credential set. (And remember: M1 alone can't exit the ABDM sandbox — plan M1+M2.)
- The right participant role. NHCX has four: PROVIDER (10001) — any system on the care-delivery side: hospital HIMS, clinic software, diagnostic labs, pharmacies; PAYER (10002) — insurers; AGENCY_TPA (10003); and EUA (10009) — patient-facing PHR applications. Payers/TPAs register with their IRDAI number instead of an HFR ID.
The Official Onboarding Journey
- 1. Register on the NHCX sandbox via the ABDM sandbox portal (sandbox.abdm.gov.in → sandbox registration), using your ABDM client-ID and secret. The sandbox team attaches NHCX roles to those credentials after verification.
- 2. Create your participant via the participant service APIs, with the correct role and registry codes. Session tokens come from the same ABDM gateway sessions API you already use for M1–M3.
- 3. Build the use-case APIs (the 13 provider use cases below) against the sandbox base URL, with payloads as FHIR R4 bundles per NRCES NHCX profiles, JWE-encrypted (RFC 7516) to the receiver's public key fetched from the certs API.
- 4. FHIR bundle validation by NRCeS — you email your bundles to NHA's integration address and the NRCeS team validates them against the profiles before testing begins.
- 5. Functional testing + HTC demo — NHA's internal demo checks your use cases end-to-end; the Health Tech Committee demo is the final gate.
- 6. Production — NHA assigns the provider role to your M1 production client-ID; you go live against the production base URLs, ideally after a small pilot.
The Actual Scope: 13 Provider Use Cases NHA Will Test
The provider-side sandbox-exit document enumerates exactly what a HIMS must demonstrate. This is your development scope:
- Registry & setup (call-only): ① fetch participant list, ② get beneficiary policies (by mobile/ABHA), ③ fetch the payer's public key, ④ get the auth token.
- Eligibility & planning: ⑤ coverage eligibility check (+ on_check callback), ⑥ insurance plan details request (+ callback).
- Authorization & treatment: ⑦ pre-authorization submit (+ on_submit), ⑧ respond to payer communication requests for additional documents.
- Claim & settlement: ⑨ claim submission (+ on_submit), ⑩ claim search, ⑪ acknowledge payment notice, ⑫ reprocess/cancel via task submit, ⑬ status check (+ on_status).
Every asynchronous flow means your HIMS also hosts the on_* callback endpoints — and each callback must handle two payload shapes: an encrypted FHIR bundle when the payer processed the request, or a plain ProtocolResponse when it failed protocol validation. We cover the traps in our companion post: 10 common NHCX integration mistakes.
What This Touches Inside a HIMS
NHCX is not a bolt-on API client — it cuts across five modules:
- Front office / registration: ABHA capture (your existing M1 work) plus insurance-policy capture and ABHA-policy linking.
- TPA / insurance desk: eligibility checks at admission, pre-auth submission with cost estimates and documents, handling payer queries mid-treatment, pre-auth enhancement when treatment costs grow.
- Clinical / EMR: discharge summaries, diagnoses and procedures feed the claim bundle; discharge-type handling (normal, death, LAMA, DAMA) maps to the payer's discharge questionnaires.
- Billing: the itemized final bill — pharmacy, lab, OT, room — becomes structured FHIR claim items with amounts the payer's engine re-validates.
- Finance: payment-notice handling, reconciliation against approved amounts, and the reprocess/erroneous-claim flow when settlement doesn't match.
This is why M2-grade FHIR tooling matters so much: the claim bundle carries clinical resources, and teams that built real FHIR document generation for ABDM M2 reuse most of it here. For how to structure this without rewriting your HIMS, see our NHCX integration architecture guide.
Labs, Pharmacies, and Other Providers
The PROVIDER role is not hospitals-only. Diagnostic labs and pharmacies sit on the same side of the exchange — anywhere a claimable service is delivered. The practical difference is scope: a standalone lab's claim lifecycle is simpler (no admission, no pre-auth enhancement, no discharge questionnaires), but the protocol work — participant onboarding, JWE envelopes, callbacks, error handling — is identical. Patient-facing health apps are a different role entirely (EUA), with their own registry code.
Private Insurance vs PMJAY: Same Rails, Extra Steps
NHCX itself serves private insurance claims. PMJAY claims run on the same framework but add scheme-specific onboarding: PMJAY workflow alignment, package definitions, unspecified-procedure rules, and state health agency processes. The sandbox portal has a dedicated NHCX-PMJAY-HMIS documentation section for this leg. If your hospitals serve both, plan the private-insurance integration first — the PMJAY leg builds on it.
Realistic Timeline
For a HIMS with M1 production already done and working FHIR tooling: development of the 13 use cases typically runs 8–12 weeks, with NRCeS bundle validation, functional testing, and the HTC demo adding 4–8 weeks depending on NHA scheduling. Without FHIR tooling, add the M2-style document-generation work first — that is the long pole, not the claim APIs.
We've done this path — our team runs production ABDM integrations, built FHIR tooling for Indian HIMS stacks, and works hands-on with the NHCX sandbox. If you want the checklist turned into a project plan for your product, explore our Healthcare Interoperability Solutions and ABDM integration services, or talk to our team.
