Skip to main content

Provider: request an insurance plan

Provider sends a Task with code poll naming both a policy number and its HFR ID to fetch the payer's machine-readable InsurancePlan for that pairing.

POST/v1/insuranceplan/request

Business purpose

Policies have traditionally been PDFs that hospital desks interpret by hand, producing ambiguity about benefits, claim conditions and documents, and rework and rejections downstream. The InsurancePlan API replaces that with a structured, provider-specific, policy-specific contract view: empanelled specialities, package codes and rates, implant and stratification qualifiers, claim conditions such as EnhancementAllowed or Standalone, mandatory documents and questionnaires. Hospitals gain an authoritative view before treatment; payers gain fewer malformed preauths and claims. It is one of the most critical APIs for implementors.

When to use

Call it before any pre-authorisation or claim for a payer and policy, ideally at registration. It fetches the plan: covered treatments, rates and required documents.

Preconditions

  • You have a valid access token and the payer's certificate.
  • The request is an FHIR Task with both the policy number and the hospital's HFR ID.
  • x-hcx-recipient_code is the processing ID, not the payer ID, and the correlation ID is new.

Postconditions

  • NHCX answers 202 at once. That is a receipt, not the plan.
  • The plan arrives later on /v1/insuranceplan/on_request. It may be empty if nothing matches.

Common mistakes

  • Sending a Task without both the policy number and the HFR ID.
  • Expecting the plan in the 202 response.
  • Sending a new request while an earlier one is still with the payer.
  • Treating an empty plan as a gateway fault.

Best practices

  • Integrate deeply: call at registration or admission, before cost estimation, and together with coverage eligibility.
  • Cache the returned plan and refresh on a schedule or when the treatment plan changes; it is provider-, policy- and MoU-specific.
  • Enforce the returned claim conditions (GovtReserved, EnhancementAllowed, QuantityAllowed, ImplantApplicable, Standalone, ParentProcedure, Unspecified) locally before building preauths.
  • Persist the correlation ID so the on_request callback can be matched; mint a new one for each discovery cycle.
  • Use IST timestamps and a fresh API_call_ID per call.
  • Stand up the on_request receiver and v1/error before the first request.

Related scenario

A PMJAY beneficiary arrives at an empanelled hospital's admission desk. After the desk fetches the patient's policies through the participant registry and resolves the processingID, the integration posts /v1/insuranceplan/request with a Task carrying policyNumber and the hospital's HFR ID. The gateway returns 202. Minutes later the payer's package master arrives on /v1/insuranceplan/on_request: the hospital's empanelled specialities, package codes, rates, implant qualifiers and the mandatory-document questionnaire. The desk selects the relevant package, checks the claim conditions, and proceeds to /v1/coverageeligibility/check and then /v1/preauth/submit.

Specification

Chapter Insurance plan request of the NHCX integration specification.

Authorizations

bearer_authapiKeyRequired

Every NHCX call carries the access token from the session call in a header named bearer_auth, as the word Bearer, a space and the token. NHCX reads bearer_auth, not Authorization.

Example Bearer <access token>

Protected header

These fields go in the JWE protected header of payload, not as HTTP headers. Building and sending a JWE shows how to prepare and encrypt the payload, and Receiving a callback how to decrypt one.

algstringRequired

Key management algorithm. Always RSA-OAEP-256: the content key is wrapped with the recipient's RSA public key.

Example RSA-OAEP-256

encstringRequired

Content encryption algorithm. Always A256GCM.

Example A256GCM

x-hcx-sender_codestringRequired

Your participant code. Mandatory on the envelope.

Example <provider participant code>

x-hcx-recipient_codestringRequired

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

Example <payer participant code>

x-hcx-api_call_idstringRequired

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

Example <uuid>

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. Send it anyway, as a fresh UUID per originating request: it is cheap and satisfies both readings until NHA rules.

Example <uuid>

x-hcx-correlation_idstringRequired

The thread that ties a request to its answers. The correlation ID rule says when to reuse it. Mandatory on the envelope.

Example <uuid>

x-hcx-workflow_idstring

Which step, or which case. The workflow code explains both readings. Optional on the envelope.

x-hcx-timestampstringRequired

The time the message was made. Timestamp gives the format. Mandatory on the envelope.

Example <iso timestamp>

x-hcx-statusstringRequired

Where this message stands. Status words lists the values. Mandatory on the envelope.

Example request.initiated

x-hcx-ben-abha-idstring

The beneficiary's ABHA number. Optional: send it when the beneficiary has an ABHA number. Optional on the envelope.

Body

payloadstring

Responses

202

The gateway returns HTTP 202 with a StatusSuccessResponse whose result carries sender_code, recipient_code, entity_type insuranceplan and protocol_status; 400, 404 and 500 use the same envelope.

timestampstring
api_call_idstring
correlation_idstring
resultobject
result.sender_codestring
result.recipient_codestring
result.entity_typestring
result.protocol_statusstring
errorobject
error.codestring
error.messagestring

Callbacks​