Skip to main content

Provider: check coverage eligibility

Provider asks the payer, via NHCX, whether a beneficiary's policy is in force, what it covers and which documents a preauth will need.

POST/v1/coverageeligibility/check

Business purpose

Coverage eligibility is the pre-check a hospital desk runs before committing a patient to a cashless pathway. It confirms three things the desk needs: that the policy is active, what benefits and wallet balance are available, and whether a specific procedure needs authorisation at all. A rejection that would otherwise surface days later at preauth or claim adjudication surfaces in seconds while the patient is still at the counter, which benefits the hospital (less rework), the payer (fewer malformed preauths) and the patient (earlier certainty).

When to use

  • Call it at registration or admission, before you submit a pre-authorisation on /v1/preauth/submit.
  • Set purpose to say what you want back. It takes one or more values:
  • discovery finds the beneficiary's policies. Use it only when /participant/get/policies gives no policy code.
  • validation says whether the policy is in force, with the used amount, available balance and wallet liability.
  • benefits says whether a package is covered for this beneficiary.
  • auth-requirements says whether a chosen procedure is covered at this hospital, and returns the STG questionnaires and MAND document codes the pre-authorisation must carry.
  • Send x-hcx-status request.initiated.
  • No workflow code is specific to eligibility. The sample exchange uses x-hcx-workflow_ID 11 (PATIENT_ADMITTED).
  • Under PMJAY, run an auth-requirements check even for an unspecified procedure.

Preconditions

  • You have a valid access token and the payer's certificate.
  • x-hcx-recipient_code is the processing ID from the policy lookup, not the payer ID.
  • x-hcx-correlation_ID is a new UUID for this check.
  • The bundle names the patient, the coverage, the hospital and the insurer, encrypted for the payer.

Postconditions

  • NHCX answers 202 at once. That only means the message was accepted.
  • The payer's answer arrives later on /v1/coverageeligibility/on_check.

Common mistakes

  • Treating the 202 as the eligibility answer.
  • Using the payer ID as the recipient code instead of the processing ID.
  • Reusing a correlation ID from an earlier check.
  • Sending a status other than request.initiated.

Best practices

  • Persist the correlation ID against the patient episode before posting; it is the only key for matching the callback.
  • Refresh the token automatically before the 1200-second expiry and treat a 401 as refresh-and-retry-once.
  • Run discovery first only when get/policies gives no policy code, then validation, then auth-requirements for the chosen package; store the returned MAND codes and STG questionnaire references and attach them to the preauth.
  • "Match response items to your request by productOrService code: the payer answers in the package codes you sent, for example MG004A, as NHA's published PMJAY bundles show. The numbers in the handbook's response table (100005, 100478, 100063, 100012) are not item codes; in the published bundles they are questionnaire, document-requirement and question identifiers."
  • Use IST timestamps with the +05:30 offset in the protected header.
  • Log the 202 body (protocol_status, API_call_ID) so a missing callback can be traced with /v1/status.

Related scenario

A patient arrives at a district hospital with a PMJAY card. The desk calls /participant/get/policies and receives a processingID for the state health agency. Because the treating doctor wants a corneal grafting package, the desk builds a CoverageEligibilityRequest with purpose validation and auth-requirements, encrypts it for the payer and posts it to /v1/coverageeligibility/check, receiving a 202 with protocol_status request.queued. Minutes later the payer's answer lands on /v1/coverageeligibility/on_check with inforce true, authorizationRequired true and MAND0409 and MAND0104 listed as supporting documents. The desk collects those documents and proceeds to /v1/preauth/submit under workflow 12.

Specification

Chapter Coverage eligibility 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.

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

Example <14-digit ABHA number>

Body

payloadstring

Responses

202

NHCX replies synchronously with HTTP 202 Accepted and a StatusSuccessResponse acknowledgement (timestamp, api_call_id, correlation_id, result with sender_code, recipient_code, entity_type coverageeligibility and protocol_status such as request.queued or request.dispatched, plus an empty error object).

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​