NHCX Use Cases

A use case covers each stage of the claims lifecycle: onboarding providers and payers onto the network, verifying coverage, seeking preauthorisation, submitting claims, exchanging supporting information, and reconciling payments. Between them they deliver the core objectives of standardisation, traceability, and predictable auto-adjudication across India's National Health Claims Exchange (NHCX).

Key Use Cases Overview​

• Onboarding Providers and Payers: Onboard participants onto NHCX to validate and route requests to target applications.
• Check Coverage Eligibility: Called by providers to verify beneficiary coverage, policy validity, sum insured, sub-limits, and document requirements.
• Preauth Request Submission: Submitted by providers before admission or planned surgery. Payers respond with line-item adjudication via on_submit.
• Predetermination Request: Inquires expected coverage and deductible calculations for planned procedures without reserving policy balance.
• Claim Request Submission: Submitted by providers upon discharge with final bill, discharge summary, and itemised claims.
• Communication Request: Enables payers to query providers for additional documents (additionalinfo), flag turnaround-time breaches (tatquery), or issue policy updates.
• Payment Notice & Reconciliation: Payers notify providers of bank transfers (UTR), detailing claimed, approved, TDS, and settled amounts.
• Reprocess / Cancel / Shortfall: Providers appeal rejected claims (reprocess), request partial payment balance (partialpayment), or cancel approved preauthorisations.
• Beneficiary Notifications: Push notifications to personal health record (PHR) apps on claim status changes.

---

Master Use Cases Matrix​

All 40 NHA use cases by role, each with its API call and callback.

Shared​

A1 Get participant list​

The participants in the registry, by role.

API Call: /fetch/participants/list

A2 Get policy​

The policies a beneficiary holds, by mobile number or ABHA.

API Call: /participant/get/policies

A3 Get public key​

The recipient's certificate, which is what the bundle is encrypted with.

API Call: /fetch/certs

A4 Get auth token​

The ABDM session token every NHCX call carries, minted with the Milestone 1 client id and secret.

API Call: /get/session

A5 Get status​

Where any request you made got to, by its correlation id.

API Call: /v1/status Callback: /v1/on_status

A6 Receive errors​

Where the exchange tells you a request could not be delivered after five attempts.

API Call: hosted only Callback: /v1/error

Provider​

B1 Check coverage eligibility​

Is the policy in force, what is left in the wallet, and what must be attached.

API Call: /v1/coverageeligibility/check Callback: /v1/coverageeligibility/on_check

B2 Request insurance plan​

A Task with code poll, keyed on policy number and provider id.

API Call: /v1/insuranceplan/request Callback: /v1/insuranceplan/on_request

B3 Submit pre-authorisation​

Permission to treat.

API Call: /v1/preauth/submit Callback: /v1/preauth/on_submit

B4 Respond to a communication​

Acknowledge or answer a message the payer sent about a case.

API Call: /v1/communication/on_request Callback: /v1/communication/request

B5 Submit claim​

Reimbursement after discharge.

API Call: /v1/claim/submit Callback: /v1/claim/on_submit

B6 Search claims​

Look up claim information by criteria.

API Call: /v1/search/submit Callback: /v1/search/on_submit

B7 Acknowledge payment notice​

The receipt for a payment notice, as a Task on this endpoint.

API Call: /v1/paymentnotice/on_request Callback: /v1/paymentnotice/request

B8 Reprocess or cancel​

One endpoint, several jobs, told apart by the Task's code and reason: reprocess with claimrejected, shortfall with partialpayment, cancel.

API Call: /v1/task/submit Callback: /v1/task/on_submit

B9 Submit predetermination​

What would the payer approve for this treatment?

API Call: /v1/predetermination/submit Callback: /v1/predetermination/on_submit

PMJAY​

D1 Fetch the insurance plan​

Keyed on provider id, policy code and participant id.

API Call: /v1/insuranceplan/request Callback: /v1/insuranceplan/on_request

D2 Authenticate the beneficiary​

Fingerprint, iris or face; all three must be built.

API Call: ABHA biometric auth init and verify (not NHCX)

D3 Check coverage eligibility​

Validation after registration returns the wallet, one benefit entry per wallet with allowed and used.

API Call: /v1/coverageeligibility/check Callback: /v1/coverageeligibility/on_check

D4 Submit pre-authorisation​

Not more than one day before admission, with the biometric token or the consent response, the documents the auth-requirements answer asked for, the STG questionnaire for each package, and the registration and admission dates as supporting info.

API Call: /v1/preauth/submit Callback: /v1/preauth/on_submit

D5 Resubmit pre-authorisation​

Revises an approved or rejected case for a different amount or package.

API Call: /v1/preauth/submit Callback: /v1/preauth/on_submit

D6 Raise an enhancement​

Adds to an approved pre-authorisation, as many times as needed until discharge, one at a time, and only for packages whose plan flag allows it.

API Call: /v1/preauth/submit Callback: /v1/preauth/on_submit

D7 Answer a pre-authorisation query​

The query arrived as a ClaimResponse on 24, on the case's own thread, with the question in the item adjudication, not on the communication API.

API Call: /v1/preauth/submit Callback: /v1/preauth/on_submit

D8 Cancel pre-authorisation​

A Task with code cancel, the case number as input and one of seven reasons: treatmentplanchanged, patientrequest, financialconstraints, alternativetreatment, duplicateclaim, administrativeerror, other.

API Call: /v1/task/submit Callback: /v1/task/on_submit

D9 Submit claim​

There is no discharge submission: the claim asserts the discharge and carries its details.

API Call: /v1/claim/submit Callback: /v1/claim/on_submit

D10 Answer a claim query​

As D7, on the claim endpoint: the query is a ClaimResponse on 27, the answer a fresh submit on 161.

API Call: /v1/claim/submit Callback: /v1/claim/on_submit

D11 Reprocess a rejected claim​

An appeal, not a resubmission: a Task with code reprocess and reason claimrejected, a supporting document attached, no amount.

API Call: /v1/task/submit Callback: /v1/task/on_submit

D12 Claim a shortfall​

The same Task with reason partialpayment and an amount capped at the difference, allowed only after payment notice 33 has arrived and been acknowledged with 17.

API Call: /v1/task/submit Callback: /v1/task/on_submit

D13 Acknowledge the payment notice​

Three notices may arrive: 30 when the transfer is initiated, 31 when the bank processes it, 33 when it settles with the UTR.

API Call: /v1/paymentnotice/on_request Callback: /v1/paymentnotice/request

Payer​

C1 Link ABHA with policy​

Tie the ABHA number, mobile and member id to the policy's products at policy creation, naming the payer and the processor.

API Call: /participant/link/abha/policy

C2 De-link ABHA from policy​

Undo C1.

API Call: /participant/delink/abha/policy

C3 Respond to coverage eligibility​

The eligibility and plan details for the beneficiary asked about.

API Call: /v1/coverageeligibility/on_check Callback: /v1/coverageeligibility/check

C4 Respond to insurance plan request​

The plan as a benefit structure.

API Call: /v1/insuranceplan/on_request Callback: /v1/insuranceplan/request

C5 Respond to pre-authorisation​

The adjudicated pre-authorisation.

API Call: /v1/preauth/on_submit Callback: /v1/preauth/submit

C6 Raise a communication​

A message about a case, typed by its reason code: additionalinfo, tatquery for a turnaround breach, grievance, walletupdate, policychange, claimArbitration.

API Call: /v1/communication/request Callback: /v1/communication/on_request

C7 Respond to claim​

The adjudicated claim, item by item, with any deduction and its reason.

API Call: /v1/claim/on_submit Callback: /v1/claim/submit

C8 Respond to search​

The ClaimResponse objects matching the criteria asked for.

API Call: /v1/search/on_submit Callback: /v1/search/submit

C9 Send payment notice​

The money, on a new thread of its own, with the reconciliation itemised by type: approved, claimed, tds, servicetax, advance, recovered, penality.

API Call: /v1/paymentnotice/request Callback: /v1/paymentnotice/on_request

C10 Respond to a Task​

The answer to a reprocess, shortfall or cancel.

API Call: /v1/task/on_submit Callback: /v1/task/submit

C11 Respond to predetermination​

What the payer would approve for the proposed treatment.

API Call: /v1/predetermination/on_submit Callback: /v1/predetermination/submit

Patient app​

E1 Subscribe to notifications​

A patient app subscribes when the beneficiary logs in with their ABHA, and the most recent subscription wins.

API Call: /v1/notification/subscribe Callback: /v1/notification/on_subscribe

---

Shared Use Cases (Payer and Provider)​

The following use cases are common to both Payer and Provider participants on the NHCX platform. None of them carries a workflow code, because they are registry and session calls rather than claim transactions.

A1: Get participant list​

• Role / Side: shared
• API Called: /fetch/participants/list
• Carries JWE: false
• Simulator Console: /participants
• Data Element Mapping: package/mappings/A1.yaml

The participants in the registry, by role. How a provider finds a payer and a payer finds a provider.

Data elements

NRCeS profiles: Organization.

A2: Get policy​

• Role / Side: shared
• API Called: /participant/get/policies
• Carries JWE: false
• Simulator Console: /search
• Data Element Mapping: package/mappings/A2.yaml

The policies a beneficiary holds, by mobile number or ABHA. Each names the insurer and the processor, and the processor is the recipient for every claim-side call.

Data elements

NRCeS profiles: Patient, Coverage, Organization.

A3: Get public key​

• Role / Side: shared
• API Called: /fetch/certs
• Carries JWE: false
• Simulator Console: /participants
• Data Element Mapping: package/mappings/A3.yaml

The recipient's certificate, which is what the bundle is encrypted with. Fetched before anything is addressed to a participant.

Data elements

A4: Get auth token​

• Role / Side: shared
• API Called: /get/session
• Carries JWE: false
• Simulator Console: /session
• Data Element Mapping: package/mappings/A4.yaml

The ABDM session token every NHCX call carries, minted with the Milestone 1 client id and secret.

Data elements

A5: Get status​

• Role / Side: shared
• API Called: /v1/status
• Callback API: /v1/on_status
• Carries JWE: true
• Simulator Console: /status
• Data Element Mapping: package/mappings/A5.yaml
• FHIR Reference: Predetermination, Status and Search, A5

Where any request you made got to, by its correlation id. The sandbox's own status page answers without a token.

A6: Receive errors​

• Role / Side: shared
• API Called: (hosted only)
• Callback API: /v1/error
• Carries JWE: false
• Data Element Mapping: package/mappings/A6.yaml

Where the exchange tells you a request could not be delivered after five attempts. Without it a sender never learns that a request died, which looks exactly like a case still under review.

Data elements

Provider Use Cases​

The following use cases are initiated by Provider participants (hospitals, daycare centers) to verify coverage, submit preauthorisations, answer queries, submit claims, and reconcile payments.

B1: Check coverage eligibility​

• Role / Side: provider
• API Called: /v1/coverageeligibility/check
• Callback API: /v1/coverageeligibility/on_check
• Workflow ID: none; sits beside registration 10 and admission 11
• Carries JWE: true
• Data Element Mapping: package/mappings/B1.yaml
• FHIR Reference: Coverage Eligibility Request, B1
• Sample FHIR Bundles (5): B1-check.json, auth-requirements.json, benefits.json, discovery.json, validation.json

Is the policy in force, what is left in the wallet, and what must be attached. One endpoint, four purposes: discovery, validation, benefits, auth-requirements.

B2: Request insurance plan​

• Role / Side: provider
• API Called: /v1/insuranceplan/request
• Callback API: /v1/insuranceplan/on_request
• Carries JWE: true
• Data Element Mapping: package/mappings/B2.yaml
• FHIR Reference: Insurance Plan Request, B2
• Sample FHIR Bundles (2): B2-request.json, insurance-plan-request.json

A Task with code poll, keyed on policy number and provider id. The answer is the policy as a benefit structure: packages, rates, documents, questionnaires.

B3: Submit pre-authorisation​

• Role / Side: provider
• API Called: /v1/preauth/submit
• Callback API: /v1/preauth/on_submit
• Workflow ID: 12 new, 121 resubmission, 13 enhancement; under PMJAY 19 answers a query and 131 an enhancement query
• Carries JWE: true
• Data Element Mapping: package/mappings/B3.yaml
• FHIR Reference: Preauthorisation Request, B3
• Sample FHIR Bundles (6): B3-enhancement.json, B3-request.json, preauth-cancel.json, preauth-enhancement.json, preauth-queryupdate.json, preauth-request.json

Permission to treat. A resubmission, an enhancement and a query answer all reuse the same bundle with a new correlation id and the original reference; only the workflow code tells them apart. The acknowledgement on 20 brings the payer's own case number, and the desk files everything under it.

B4: Respond to a communication​

• Role / Side: provider
• API Called: /v1/communication/on_request
• Callback API: /v1/communication/request
• Workflow ID: 24, 241 or 27, echoed from the payer's request
• Carries JWE: true
• Data Element Mapping: package/mappings/B4.yaml
• FHIR Reference: Communication, B4
• Sample FHIR Bundles (5): B4-claim-query-answer.json, B4-preauth-query-answer.json, communication-acknowledgement.json, communication-request.json, communication-response.json

Acknowledge or answer a message the payer sent about a case. A generic or IRDAI payer raises its query here, as a CommunicationRequest task bundle carrying 24, 241 or 27; the answer is a Communication task bundle on on_request that echoes the request's correlation id and workflow id. The payer's reason code says what kind of message it was.

B5: Submit claim​

• Role / Side: provider
• API Called: /v1/claim/submit
• Callback API: /v1/claim/on_submit
• Workflow ID: 15 claim, 161 query answer under PMJAY, 14 provisional discharge where a payer supports one
• Carries JWE: true
• Data Element Mapping: package/mappings/B5.yaml
• FHIR Reference: Claim Request, B5
• Sample FHIR Bundles (5): B5-request.json, claim-queryupdate.json, claim-release.json, claim-reprocess.json, claim-request.json

Reimbursement after discharge. The amount may not exceed what the pre-authorisation approved. The acknowledgement on 25 brings the payer's case number. PMJAY takes a claim query answer on 161 only; 151, 19 and 16 are refused with PAYR-1321.

B6: Search claims​

• Role / Side: provider
• API Called: /v1/search/submit
• Callback API: /v1/search/on_submit
• Carries JWE: true
• Data Element Mapping: package/mappings/B6.yaml
• FHIR Reference: Predetermination, Status and Search, B6
• Sample FHIR Bundles (1): claim-search.json

Look up claim information by criteria. The provider sandbox exit checklist names /v1/search/submit for claim search, while the Technical Specifications route /search/submit from NHA through NHCX to the payer: a cross-payer search for NHA or a regulator. A provider's search over its own cases is /claim/search in the protocol, which the access-control policy allows for requests that originated from the provider. No source confirms which of the two the sandbox accepts from a provider.

B7: Acknowledge payment notice​

• Role / Side: provider
• API Called: /v1/paymentnotice/on_request
• Callback API: /v1/paymentnotice/request
• Workflow ID: 30 echoed from the notice on the generic network; 17 under PMJAY
• Carries JWE: true
• Data Element Mapping: package/mappings/B7.yaml
• FHIR Reference: Payment Notice and Acknowledgement, B7
• Sample FHIR Bundles (2): B7-acknowledgement.json, payment-notice-ack.json

The receipt for a payment notice, as a Task on this endpoint. The notice arrives on a new thread of its own; a generic payer takes the acknowledgement with the notice's 30 echoed, PMJAY with 17.

B8: Reprocess or cancel​

• Role / Side: provider
• API Called: /v1/task/submit
• Callback API: /v1/task/on_submit
• Workflow ID: PC01 cancel, 36 reprocess or shortfall
• Carries JWE: true
• Data Element Mapping: package/mappings/B8.yaml
• FHIR Reference: Cancel, Reprocess and Shortfall, B8
• Sample FHIR Bundles (2): B8-cancel.json, B8-reprocess.json

One endpoint, several jobs, told apart by the Task's code and reason: reprocess with claimrejected, shortfall with partialpayment, cancel. A reprocess goes on 36 and is acknowledged on 37; a cancel goes on PC01 and is done on PC02. Both carry the input intimationNumber. A supporting document is mandatory on a reprocess.

B9: Submit predetermination​

• Role / Side: provider
• API Called: /v1/predetermination/submit
• Callback API: /v1/predetermination/on_submit
• Carries JWE: true
• Data Element Mapping: package/mappings/B9.yaml
• FHIR Reference: Predetermination, Status and Search, B9
• Sample FHIR Bundles (1): predetermination-request.json

What would the payer approve for this treatment? Same bundle shape as a pre-authorisation, asked before committing to one.

PMJAY Scheme Use Cases​

The following use cases govern the Pradhan Mantri Jan Arogya Yojana (AB PM-JAY) cashless lifecycle as detailed in the official NHA PMJAY Handbook. They follow strict Standard Treatment Guidelines (STG), mandatory biometrics, package rules, and Turnaround Time (TAT) auto-approvals.

D1: Fetch the insurance plan​

• Role / Side: pmjay
• API Called: /v1/insuranceplan/request
• Callback API: /v1/insuranceplan/on_request
• Carries JWE: true
• Data Element Mapping: package/mappings/D1.yaml
• FHIR Reference: Insurance Plan Request, D1
• Sample FHIR Bundles (1): D1-request.json

Keyed on provider id, policy code and participant id. The answer is the scheme configuration for this hospital: specialities, packages, rates, Claim-Condition flags, mandatory documents and questionnaires. Over twenty megabytes; store it queryable, version it, refresh weekly and on any policychange communication.

D2: Authenticate the beneficiary​

• Role / Side: pmjay
• API Called: ABHA biometric auth init and verify (not NHCX)
• Carries JWE: false
• Data Element Mapping: package/mappings/D2.yaml

Fingerprint, iris or face; all three must be built. Success yields a user token valid thirty minutes that rides on the eligibility check and the pre-authorisation; a fresh one rides on the claim. Where biometrics are impossible, a signed exemption consent and the matching questionnaire stand in, except on a cyclic case.

Data elements

NRCeS profiles: Patient.

D3: Check coverage eligibility​

• Role / Side: pmjay
• API Called: /v1/coverageeligibility/check
• Callback API: /v1/coverageeligibility/on_check
• Carries JWE: true
• Data Element Mapping: package/mappings/D3.yaml
• FHIR Reference: Coverage Eligibility Request, D3
• Sample FHIR Bundles (1): D3-check.json

Validation after registration returns the wallet, one benefit entry per wallet with allowed and used. Benefits and auth-requirements before a pre-authorisation return what the package needs attached. Register only after coverage is validated, and validate again every time treatment is added.

D4: Submit pre-authorisation​

• Role / Side: pmjay
• API Called: /v1/preauth/submit
• Callback API: /v1/preauth/on_submit
• Workflow ID: 12
• Carries JWE: true
• Simulator Console: /builder?family=preauth&usecase=initiate
• Data Element Mapping: package/mappings/D4.yaml
• FHIR Reference: Preauthorisation Request, D4
• Sample FHIR Bundles (1): D4-request.json

Not more than one day before admission, with the biometric token or the consent response, the documents the auth-requirements answer asked for, the STG questionnaire for each package, and the registration and admission dates as supporting info. Auto-approved only if it is the first pre-authorisation for the case and every package allows it.

D5: Resubmit pre-authorisation​

• Role / Side: pmjay
• API Called: /v1/preauth/submit
• Callback API: /v1/preauth/on_submit
• Workflow ID: 121
• Carries JWE: true
• Simulator Console: /builder?family=preauth&usecase=resubmit
• Data Element Mapping: package/mappings/D5.yaml
• FHIR Reference: Preauthorisation Request, D5

Revises an approved or rejected case for a different amount or package. Nullifies every earlier instance; the payer treats it as the new base request.

D6: Raise an enhancement​

• Role / Side: pmjay
• API Called: /v1/preauth/submit
• Callback API: /v1/preauth/on_submit
• Workflow ID: 13, and 131 to answer an enhancement query raised on 241
• Carries JWE: true
• Simulator Console: /builder?family=preauth&usecase=enhance
• Data Element Mapping: package/mappings/D6.yaml
• FHIR Reference: Preauthorisation Enhancement, D6
• Sample FHIR Bundles (2): D6-enhancement-query-answer.json, D6-enhancement.json

Adds to an approved pre-authorisation, as many times as needed until discharge, one at a time, and only for packages whose plan flag allows it. The bundle carries the approved items and the ones now sought. A query on it arrives as a ClaimResponse on 241, on the case's own thread, and is answered by a fresh submit on 131.

D7: Answer a pre-authorisation query​

• Role / Side: pmjay
• API Called: /v1/preauth/submit
• Callback API: /v1/preauth/on_submit
• Workflow ID: 19
• Carries JWE: true
• Simulator Console: /builder?family=preauth&usecase=query-answer
• Data Element Mapping: package/mappings/D7.yaml
• FHIR Reference: Preauthorisation Query and Answer, D7
• Sample FHIR Bundles (1): D7-query-answer.json

The query arrived as a ClaimResponse on 24, on the case's own thread, with the question in the item adjudication, not on the communication API. Answer with a fresh submit of the same bundle shape on this code, never as a new 12, which opens a second case.

D8: Cancel pre-authorisation​

• Role / Side: pmjay
• API Called: /v1/task/submit
• Callback API: /v1/task/on_submit
• Workflow ID: PC01
• Carries JWE: true
• Simulator Console: /builder?family=preauth&usecase=cancel
• Data Element Mapping: package/mappings/D8.yaml
• FHIR Reference: Cancel, Reprocess and Shortfall, D8
• Sample FHIR Bundles (1): D8-cancel.json

A Task with code cancel, the case number as input and one of seven reasons: treatmentplanchanged, patientrequest, financialconstraints, alternativetreatment, duplicateclaim, administrativeerror, other. Allowed at any point until the claim is raised.

D9: Submit claim​

• Role / Side: pmjay
• API Called: /v1/claim/submit
• Callback API: /v1/claim/on_submit
• Workflow ID: 15
• Carries JWE: true
• Simulator Console: /builder?family=claim&usecase=submit
• Data Element Mapping: package/mappings/D9.yaml
• FHIR Reference: Claim Request, D9
• Sample FHIR Bundles (1): D9-request.json

There is no discharge submission: the claim asserts the discharge and carries its details. Four dates, the discharge type under category DIS with the stage as its value, a fresh biometric token, and LM100 as the single procedure in place of the approved items on a LAMA or DAMA discharge before or during surgery. The amount may not exceed what was approved.

D10: Answer a claim query​

• Role / Side: pmjay
• API Called: /v1/claim/submit
• Callback API: /v1/claim/on_submit
• Workflow ID: 161
• Carries JWE: true
• Simulator Console: /builder?family=claim&usecase=query-answer
• Data Element Mapping: package/mappings/D10.yaml
• FHIR Reference: Claim Query and Answer, D10
• Sample FHIR Bundles (1): D10-query-answer.json

As D7, on the claim endpoint: the query is a ClaimResponse on 27, the answer a fresh submit on 161. The sandbox refuses 151, 19 and 16 with PAYR-1321. The final adjudication then arrives with outcome complete and, often, a deductible adjudication naming why the eligible amount is less than the claimed one.

D11: Reprocess a rejected claim​

• Role / Side: pmjay
• API Called: /v1/task/submit
• Callback API: /v1/task/on_submit
• Workflow ID: 36
• Carries JWE: true
• Simulator Console: /builder?family=claim&usecase=reprocess
• Data Element Mapping: package/mappings/D11.yaml
• FHIR Reference: Cancel, Reprocess and Shortfall, D11
• Sample FHIR Bundles (1): D11-reprocess.json

An appeal, not a resubmission: a Task with code reprocess and reason claimrejected, a supporting document attached, no amount. Raise it the moment the rejection arrives. Once only; the Claim Review Committee is final.

D12: Claim a shortfall​

• Role / Side: pmjay
• API Called: /v1/task/submit
• Callback API: /v1/task/on_submit
• Workflow ID: 36
• Carries JWE: true
• Simulator Console: /builder?family=claim&usecase=shortfall
• Data Element Mapping: package/mappings/D12.yaml
• FHIR Reference: Cancel, Reprocess and Shortfall, D12

The same Task with reason partialpayment and an amount capped at the difference, allowed only after payment notice 33 has arrived and been acknowledged with 17. Once only, and never after a reprocess.

D13: Acknowledge the payment notice​

• Role / Side: pmjay
• API Called: /v1/paymentnotice/on_request
• Callback API: /v1/paymentnotice/request
• Workflow ID: 17
• Carries JWE: true
• Simulator Console: /builder?family=paymentnotice&usecase=acknowledge
• Data Element Mapping: package/mappings/D13.yaml
• FHIR Reference: Payment Notice and Acknowledgement, D13
• Sample FHIR Bundles (1): D13-acknowledgement.json

Three notices may arrive: 30 when the transfer is initiated, 31 when the bank processes it, 33 when it settles with the UTR. The reconciliation splits the amount into what was paid and what was deducted as tax. Keep the UTR; it is the reference for any dispute.

Payer Use Cases​

The following use cases are implemented by Payer participants (Insurance Companies and Third Party Administrators) to respond to provider inquiries, adjudicate claims, raise queries, and settle payments.

C1: Link ABHA with policy​

• Role / Side: payer
• API Called: /participant/link/abha/policy
• Carries JWE: false
• Simulator Console: /participants
• Data Element Mapping: package/mappings/C1.yaml

Tie the ABHA number, mobile and member id to the policy's products at policy creation, naming the payer and the processor. This is what makes A2 answer.

Data elements

NRCeS profiles: Patient, Coverage, Organization.

C2: De-link ABHA from policy​

• Role / Side: payer
• API Called: /participant/delink/abha/policy
• Carries JWE: false
• Data Element Mapping: package/mappings/C2.yaml

Undo C1. Only the party named as payer or processor on the link may do this.

Data elements

NRCeS profiles: Patient, Coverage.

C3: Respond to coverage eligibility​

• Role / Side: payer
• API Called: /v1/coverageeligibility/on_check
• Callback API: /v1/coverageeligibility/check
• Carries JWE: true
• Data Element Mapping: package/mappings/C3.yaml
• FHIR Reference: Coverage Eligibility Response, C3
• Sample FHIR Bundles (7): C3-benefits-pmjay.json, C3-response-generic.json, C3-response-pmjay.json, benefits-response.json, coverage-eligibility.json, discovery-response.json, validation-response.json

The eligibility and plan details for the beneficiary asked about. A payer may instead answer with a forward instruction, asking the exchange to pass the request to another payer.

C4: Respond to insurance plan request​

• Role / Side: payer
• API Called: /v1/insuranceplan/on_request
• Callback API: /v1/insuranceplan/request
• Carries JWE: true
• Data Element Mapping: package/mappings/C4.yaml
• FHIR Reference: Insurance Plan Response Overview, C4
• Sample FHIR Bundles (2): C4-response-generic.json, C4-response-pmjay.json

The plan as a benefit structure. Under PMJAY this is the scheme configuration for one hospital and can exceed twenty megabytes.

C5: Respond to pre-authorisation​

• Role / Side: payer
• API Called: /v1/preauth/on_submit
• Callback API: /v1/preauth/submit
• Workflow ID: 20 received, 21 approved, 23 rejected, 24 queried, 22 enhancement approved, 231 denied, 241 queried
• Carries JWE: true
• Data Element Mapping: package/mappings/C5.yaml
• FHIR Reference: Preauthorisation Response, C5
• Sample FHIR Bundles (10): C5-approved-wf21-pmjay.json, C5-approved-wf21.json, C5-enhancement-approved-wf22-pmjay.json, C5-enhancement-approved-wf22.json, C5-queried-wf24.json, C5-received-wf20-pmjay.json, C5-received-wf20.json, C5-rejected-wf23-pmjay.json, C5-rejected-wf23.json, preauth-queried.json

The adjudicated pre-authorisation. The acknowledgement on 20 travels as response.partial and carries the payer's own case number; the decisions travel as response.complete. Read outcome and the adjudication amounts together: complete covers approval and denial alike. Under PMJAY a query is this ClaimResponse on 24 or 241, on the case's own thread.

C6: Raise a communication​

• Role / Side: payer
• API Called: /v1/communication/request
• Callback API: /v1/communication/on_request
• Workflow ID: 24, 241, 27 for a generic payer's queries; N02 and the intimation codes for the rest
• Carries JWE: true
• Data Element Mapping: package/mappings/C6.yaml
• FHIR Reference: Communication, C6
• Sample FHIR Bundles (3): C6-claim-query-wf27.json, C6-notification-wfN02.json, C6-preauth-query-wf24.json

A message about a case, typed by its reason code: additionalinfo, tatquery for a turnaround breach, grievance, walletupdate, policychange, claimArbitration. A generic or IRDAI payer raises its document queries here, as a CommunicationRequest task bundle carrying 24, 241 or 27, and takes the answer as a Communication task bundle on on_request echoing the correlation id and workflow id. PMJAY does not use it for queries; its query is the ClaimResponse on the case's own thread.

C7: Respond to claim​

• Role / Side: payer
• API Called: /v1/claim/on_submit
• Callback API: /v1/claim/submit
• Workflow ID: 25 received, 26 approved, 27 queried, 28 in process, 29 forwarded, 291 denied
• Carries JWE: true
• Data Element Mapping: package/mappings/C7.yaml
• FHIR Reference: Claim Response, C7
• Sample FHIR Bundles (9): C7-approved-deduction-wf26-pmjay.json, C7-approved-wf26-pmjay.json, C7-approved-wf26.json, C7-queried-wf27.json, C7-received-wf25-pmjay.json, C7-received-wf25.json, C7-rejected-wf291-pmjay.json, C7-rejected-wf291.json, claim-queried.json

The adjudicated claim, item by item, with any deduction and its reason. The acknowledgement on 25 travels as response.partial with the payer's case number. Under PMJAY a query is this ClaimResponse on 27, answered by a fresh submit on 161.

C8: Respond to search​

• Role / Side: payer
• API Called: /v1/search/on_submit
• Callback API: /v1/search/submit
• Carries JWE: true
• Data Element Mapping: package/mappings/C8.yaml
• FHIR Reference: Predetermination, Status and Search, C8
• Sample FHIR Bundles (1): search-response.json

The ClaimResponse objects matching the criteria asked for.

C9: Send payment notice​

• Role / Side: payer
• API Called: /v1/paymentnotice/request
• Callback API: /v1/paymentnotice/on_request
• Workflow ID: 30 initiated, 31 processed, 33 settled
• Carries JWE: true
• Data Element Mapping: package/mappings/C9.yaml
• FHIR Reference: Payment Notice and Acknowledgement, C9
• Sample FHIR Bundles (3): C9-notice-tds-wf30-pmjay.json, C9-notice-wf30.json, payment-notice.json

The money, on a new thread of its own, with the reconciliation itemised by type: approved, claimed, tds, servicetax, advance, recovered, penality. The bank's UTR rides on the settled notice.

C10: Respond to a Task​

• Role / Side: payer
• API Called: /v1/task/on_submit
• Callback API: /v1/task/submit
• Workflow ID: 251 acknowledged, 252 approved, 253 rejected, 254 queried, PC02 cancelled, 37 arbitration acknowledged
• Carries JWE: true
• Data Element Mapping: package/mappings/C10.yaml
• FHIR Reference: Cancel, Reprocess and Shortfall, C10
• Sample FHIR Bundles (4): C10-arbitration-wf37-pmjay.json, C10-arbitration-wf37.json, C10-cancelled-wfPC02-pmjay.json, C10-cancelled-wfPC02.json

The answer to a reprocess, shortfall or cancel. A cancellation done is PC02 and carries the case's ClaimResponse in its output; a reprocess on 36 is acknowledged on 37 as arbitration. Both payers answer this way.

C11: Respond to predetermination​

• Role / Side: payer
• API Called: /v1/predetermination/on_submit
• Callback API: /v1/predetermination/submit
• Carries JWE: true
• Data Element Mapping: package/mappings/C11.yaml
• FHIR Reference: Predetermination, Status and Search, C11
• Sample FHIR Bundles (1): predetermination-response.json

What the payer would approve for the proposed treatment.

Beneficiary & Patient App Use Cases​

Personal health record apps and beneficiary portals register on NHCX to receive real-time updates on a patient's claims and authorizations.

E1: Subscribe to notifications​

• Role / Side: patient
• API Called: /v1/notification/subscribe
• Callback API: /v1/notification/on_subscribe
• Workflow ID: N01 to a payer, N02 to a provider, N03 to a beneficiary, N04 acknowledgement
• Carries JWE: false
• Data Element Mapping: package/mappings/E1.yaml

A patient app subscribes when the beneficiary logs in with their ABHA, and the most recent subscription wins. Topics: workflow_events for claim progress, network_events for exchange maintenance, participant_events for changes to payers and providers.

Data elements

NRCeS profiles: Patient.

---

FHIR Builder Use Cases​

The NHCX FHIR Builder provides pre-configured templates and presets for generating conforming bundles across claim lifecycle stages:

---

The 100 Official NHCX Test Use Cases​

NHA specifies a formal test matrix of 100 numbered use cases covering every scenario an integrator must demonstrate for network certification. The complete reference manifest is preserved at fixtures/usecases.txt.

Testing Against the Dummy Payer​

The sandbox hosts a payer that answers back, participant ID 1000003538@hcx. It handles insurance plan, coverage eligibility, preauthorisation, claim, payment notice and communication. For the plan call use provider ID 32722 and policy 100217.

Two test hooks drive its decisions:

• dummyhcxpayer/process/request makes it approve, reject or query a preauthorisation or claim you have submitted, by correlation ID.
• dummyhcxpayer/paymentNotice/init makes it send you a payment notice.

A query from the dummy payer arrives as a communication request, which you answer on /v1/communication/on_request before the final decision comes back on on_submit.

---

Workflow Codes Cross-Reference​

Endpoints alone do not identify a transaction. A new preauthorisation, a resubmission, an enhancement and a query response all travel on /v1/preauth/submit with the same bundle. The workflow code in the header is what tells them apart, and each code expects a particular status word. See Workflow Codes for the complete state machines and code tables.