Skip to main content

Payer: send the coverage eligibility response

Payer returns the CoverageEligibilityResponse (policy in force, benefits, auth requirements) or an error to the provider through NHCX.

POST/v1/coverageeligibility/on_check

Business purpose

This is the answer leg of the eligibility check. The payer (or a TPA acting for it) tells the provider whether the policy is live, which items are covered or excluded, the allowed amounts, whether preauthorisation is required and which supporting documents the preauth must carry. Delivering this before treatment lets the hospital counsel the patient and assemble the right evidence, and lets the payer avoid adjudicating preauths that were never going to be covered.

When to use

  • The payer calls it after it has processed a /v1/coverageeligibility/check, with the same x-hcx-correlation_ID.
  • Set x-hcx-status to one of these:
  • response.complete for a final answer. Accept response.completed as the same value; some samples spell it that way.
  • response.partial for a partial answer.
  • response.error for a protocol-level rejection, with x-hcx-error_details filled in.
  • The payload is a CoverageEligibilityResponseBundle with outcome complete. It says whether the policy is in force (insurance[*].inforce), which items are excluded (item[*].excluded), and whether a pre-authorisation is needed and with which documents (item[*].authorizationRequired, item[*].authorizationSupporting).
  • A redirect or forward to another payer is also a valid outcome.

Preconditions

  • A check with this correlation ID exists in NHCX.
  • The payer has a valid access token and the provider's certificate, and encrypts the answer for the provider.
  • x-hcx-status is response.complete, response.partial or response.error.
  • Business errors go inside the encrypted answer. Only protocol errors go in x-hcx-error_details.

Postconditions

  • NHCX answers 202 and forwards the answer to the provider.
  • The provider must reply 202 within 30 seconds, or NHCX retries up to five times.
  • On success the check is closed and the provider can move on to pre-authorisation.

Common mistakes

  • Replying with 200 or a custom body on the receiving side, which makes NHCX retry.
  • Creating a new correlation ID instead of reusing the request's.
  • Putting patient or clinical details in x-hcx-error_details.

Best practices

  • Acknowledge first, process later: return 202 within 30 seconds and queue decryption and business handling.
  • Be idempotent on x-hcx-correlation_ID; the same callback may be redelivered up to five times.
  • Set inforce, disposition, excluded, authorizationRequired and authorizationSupporting explicitly so the desk can act without free-text interpretation.
  • Use ProtocolResponse with x-hcx-status response.error and a catalogued error code for protocol rejections; put business errors inside the encrypted resource.
  • Providers: whitelist the NHCX NAT IPs, expose the callback on a domain name (not IP or port) on an India-based server, and implement v1/error alongside on_check.

Related scenario

A state health agency's bridge receives an eligibility check for a beneficiary requesting validation and auth-requirements for package SE012A. Its rules engine confirms the policy is active with sufficient wallet balance and that SE012A needs preauthorisation with documents MAND0409, MAND0104 and MAND0062. The bridge builds a CoverageEligibilityResponseBundle, encrypts it for the hospital, sets x-hcx-status response.complete with the original correlation ID and posts it to /v1/coverageeligibility/on_check. NHCX acknowledges with 202 and delivers it to the hospital's callback, which acknowledges within 30 seconds; the hospital then prepares its /v1/preauth/submit.

Specification

Chapter Coverage eligibility response 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 <payer participant code>

x-hcx-recipient_codestringRequired

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

Example <provider 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.

Example 11

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 response.complete

x-hcx-ben-abha-idstring

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

Example <14-digit ABHA number>

x-hcx-debug_flagstring

Error, Info or Debug. A server may ignore it. Optional on the envelope.

Example INFO

Body

typestringRequired

Always JWEPayload. Every response (on_) call sends it beside payload.

One of JWEPayload

payloadstringRequired

Responses

202

The gateway (and, when the callback reaches it, the provider system) returns HTTP 202 Accepted with the StatusSuccessResponse acknowledgement echoing correlation_id and api_call_id, entity_type coverageeligibility and a protocol_status.

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​