Skip to main content

Provider: submit a claim

Provider submits the final itemised Claim bundle (Claim.use claim), or a claim query response or resubmission; NHCX routes it to the payer.

POST/v1/claim/submit

Business purpose

The claim is where money actually moves. After treatment the provider assembles finalised bills, the complete document set and the preAuthRef, and asks the payer to adjudicate and settle. A well-prepared claim closes within days; a poorly prepared one cycles through queries and resubmissions for weeks. The endpoint gives hospitals a single structured channel for settlement requests and gives payers a complete evidentiary package against which to calculate the approved amount, apply deductions and trigger payment.

When to use

Use it after discharge to claim payment for a case with an approved pre-authorisation. The same call answers a payer query on the claim: the workflow code in the header says which. A reprocess goes through /v1/task/submit instead.

Preconditions

  • An approved pre-authorisation exists, and no claim has been raised for the case yet.
  • The bundle is an FHIR Claim with use set to claim and the final bill amounts.
  • Discharge details and the required documents are attached. For PMJAY, so is proof of presence at discharge.
  • A valid access token, the payer's certificate and a fresh correlation ID.

Postconditions

  • NHCX answers 202 at once. That only means the message was accepted.
  • The payer's answers arrive later on /v1/claim/on_submit, possibly several times.
  • A response.complete closes the claim. Nothing more can be sent on it.

Common mistakes

  • Claiming more than the pre-authorisation approved, or items it did not include.
  • Answering a claim query as a new claim instead of a query reply.
  • Missing documents the payer asked for, which causes a query and delays payment.
  • Reusing the pre-authorisation's correlation ID for the claim.

Best practices

  • Start from the approved preauth payload: keep diagnosis and procedure entries, change Claim.use to claim, replace estimates with final amounts and add the full document set.
  • Reference preAuthRef and reuse the case number; key every submission on the correlation ID and persist workflow ID and use_case with it.
  • Check response.outcome on every callback; partial means the claim is still live, so keep monitoring the same correlation ID.
  • Validate supportingInfo value types and discharge codes before encrypting; the PAYR-1098, 1099 and 1501 to 1505 family rejects malformed supporting info.
  • For LAMA discharges send stratification with duration; for cyclic procedures send cycle information for every cycle with one biometric record per date (PAYR-1368, PAYR-1369).
  • Implement v1/error and use /v1/status with the claim's correlation ID when no callback arrives.

Related scenario

A patient is discharged home after the corneal grafting approved under preAuthRef PREAUTH-HP-2026-78901. The billing desk takes the preauth bundle, sets Claim.use to claim, records discharge code DTH After Surgery, attaches the discharge summary, operative notes and final itemised bill of 13700 INR, and posts it to /v1/claim/submit under workflow 15 with use_case New and a new correlation ID. NHCX returns 202. The payer sends 25 and 28 as response.partial, then queries under 27 for a missing investigation report; the hospital answers under 151. Approval arrives under 26 as response.complete, and a payment notice follows on /v1/paymentnotice/request.

Specification

Chapter Claim 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 15

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>

x-hcx-use_casestring

Values differ by exchange. Domain headers lists them. Optional on the envelope.

Example New

Body

payloadstring

Responses

202

NHCX returns HTTP 202 Accepted with a StatusSuccessResponse acknowledgement (entity_type claim) and forwards the request asynchronously.

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​