Skip to main content

Insurance plan

Insurance plan callback

Payer returns the InsurancePlan collection Bundle (InsurancePlan, Organization, optional Questionnaire) under the request correlation id.

POST/v1/insuranceplan/on_request

### Business purpose

This callback delivers the digital policy that every later preauth and claim is judged against. The payer publishes, for one policy and one hospital, the empanelled specialities, packages and rates, cost qualifiers for implants and stratification, exclusions, claim conditions and mandatory documents, and the questionnaires for standard treatment guidelines or history. Hospitals use it to select packages and validate submissions before they go out; payers use it to cut malformed requests and to make the MoU an enforceable, machine-readable contract view rather than a PDF.

### When to use

The payer calls it after receiving a /v1/insuranceplan/request Task (code poll), acknowledging it with 202 and assembling the plan for the policyNumber and/or providerId supplied. The bundle is of type collection and follows one of two structures: plan, specificCost, category, benefit, cost, qualifiers (the PMJAY package-master shape) or coverage, benefit, limit. Carry the same x-hcx-correlation_id as the request and a responder x-hcx-status (response.complete, or response.error with x-hcx-error_details when no plan can be produced). The plan may legitimately be empty when no coverage matches.

### Preconditions

- The inbound Task was decrypted, its correlation id captured and the 202 acceptance body already returned. - Payer registered on NHCX with a valid Bearer token and the provider's certificate for JWE encryption. - A collection Bundle containing InsurancePlan (with plan.generalCost for the overall sum insured, specificCost per speciality, benefit per package with cost and qualifiers, and the claim-exclusion, claimCondition and claimSupportingInfoRequirement extensions), Organization entries and any Questionnaire resources. - Protected header echoing the request's correlation id with a fresh api_call_id, IST timestamp and responder status; request body declared as a bare object in the OpenAPI but still a JWE per RFC-7516.

### Postconditions

The gateway returns HTTP 202 with the StatusSuccessResponse envelope (400, 404 and 500 in the same shape) and forwards the bundle to the provider's registered endpoint, which must acknowledge with 202 within 30 seconds. After decryption the provider holds the plan, may cache it, and must enforce its claim conditions and document requirements before preauth. Codes carried in the plan, such as specificCost.category as the speciality code and benefit.type as the procedure code, are what later PAYR-1114, PAYR-1202 and PAYR-1204 validations are checked against. Errors returned instead of a plan use PAYR-1401 to PAYR-1406.

### Common mistakes

- Returning the plan in the synchronous 202 to the request, or before acknowledging the inbound Task within 30 seconds. - Minting a new correlation id rather than echoing the request's (NHCX-1010). - Encoding cost.value as the package rate; the IG defines it as the extra amount paid over and above the procedure cost. - Synthesising codes for claim conditions listed as NA (rules_yn, los, ip_op_flag, incentive_applicable, gst_applicable, gst_percentage). - Shipping the full package master unfiltered; the response must be provider-specific and contextually filtered per the MoU. - Provider side: treating an empty plan as a transport failure, or failing to parse both structuring approaches.

### Best practices

- Acknowledge the inbound request first, build the bundle asynchronously, then post this callback. - Filter to the requesting provider's empanelled specialities and the named policy; include Questionnaire resources for mandatory documents and STGs. - Use the documented claim-condition codes (GovtReserved, ApprovalNotRequired, EnhancementAllowed, QuantityAllowed, IsDayCare, ImplantApplicable, StratificationAllowed, Standalone, ParentProcedure, Unspecified) so provider systems can enforce them. - Provider side: cache with periodic refresh, refresh when treatment changes, and validate preauth items against the plan's speciality and package codes. - Use a fresh api_call_id, IST timestamp and response.complete or response.error.

### Related scenario

A state health agency's payer platform receives a plan discovery Task from an empanelled hospital for policy PMJAY with the hospital's HFR id. It returns 202, then generates the InsurancePlan bundle: General Medicine and Ophthalmology as specificCost categories, each package as a benefit with its rate, implant qualifiers on the packages that allow them, EnhancementAllowed and Standalone conditions, and the proof-of-identity questionnaire. It posts /v1/insuranceplan/on_request under the same correlation id. The hospital acknowledges within 30 seconds, caches the plan, selects a package, and moves to /v1/coverageeligibility/check before submitting the preauth.

### Specification

Chapter [Insurance plan response](/docs/nhcx/v1/reference/fhir/insurance-plan-response-overview) of the NHCX integration specification.

Authorizations

Authorizationbearer tokenRequired

On every NHCX call, the token goes in a header called bearer_auth, with the word Bearer and a space in front. The sources are not unanimous: the authentication page and the FAQ both write the example as Authorization, and the notification endpoint uses Authorization. The safe course, and what the adapter does, is to send both headers with the same value.

Headers

bearer_authstringRequired

It is bearer_auth, not Authorization, on NHCX's own endpoints.

x-hcx-sender_codestringRequired

Your participant code. Mandatory on the envelope.

x-hcx-recipient_codestringRequired

The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.

x-hcx-api_call_idstringRequired

Fresh on every message, including responses. Mandatory on the envelope.

x-hcx-request_idstring

One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope.

x-hcx-correlation_idstringRequired

The thread. See the rule below. Mandatory on the envelope.

x-hcx-workflow_idstring

Which step, or which case. See the two readings below. Optional on the envelope.

x-hcx-timestampstringRequired

See the format note below. Mandatory on the envelope.

x-hcx-statusstringRequired

Where this message stands. Values below. Mandatory on the envelope.

x-hcx-ben-abha-idstringRequired

The beneficiary's ABHA number. Mandatory on every exchange, including those with no beneficiary in the payload. Mandatory on the envelope.

Body

payloadstring

Responses

202

The gateway returns HTTP 202 with the StatusSuccessResponse envelope (400, 404 and 500 in the same shape) and forwards the bundle to the provider's registered endpoint, which must acknowledge with 202 within 30 seconds.

Callbacks​

  • After this call, ABDM posts Receive insurance plan callback to v1_insuranceplan_on_request. Open the callback.