Skip to main content

Payer: send the search result

Callback returning a search result for task type code=poll; for a claim-document search the payload is the ClaimResponse for the reference number.

POST/v1/search/on_submit

Business purpose

This is how a payer answers an authorised entity's search. It completes the oversight loop: the regulator or scheme authority asked for the claim documents for a case, and the payer returns the adjudication record through NHCX rather than by email or portal download. That keeps the answer encrypted, correlated to the original request and auditable. Providers benefit indirectly, because disputes and audits can be resolved from the record of what was actually submitted and decided rather than from reconstructed paperwork.

When to use

The payer calls it to answer a /v1/search/submit request. For a claim document search, the payload is the ClaimResponse for the case.

Preconditions

  • You received and decrypted the search Task, and answered it with 202.
  • You have a valid access token and the requester's certificate.
  • The header repeats the search's x-hcx-correlation_ID.

Postconditions

NHCX answers 202 and passes the result to the requester. The claim itself does not change.

Common mistakes

  • Returning the result in the 202 instead of on this callback.
  • Making a new correlation ID, so the requester cannot match the answer.
  • Sending a Task or a bare bundle instead of the ClaimResponse.
  • Missing the 30-second window on the incoming search, which causes redeliveries.

Best practices

  • Key the search on the sender's reference ID from Task.about and echo it in basedOn.
  • Populate about with your own reference ID and the current status so the requester needs no further call.
  • Return 202 to the inbound search first, resolve documents asynchronously, then post this callback.
  • Be idempotent on correlation ID; the same search may be redelivered up to five times.
  • Use a fresh API_call_ID, IST timestamp and a responder status from response.complete, response.partial or response.error.

Related scenario

An insurer receives a search Task from the scheme authority for a claim its TPA rejected last quarter. The gateway-facing endpoint acknowledges with 202, and a worker retrieves the stored ClaimResponse for the reference number. The TPA posts /v1/search/on_submit with the ClaimResponse, basedOn set to the authority's reference ID and about set to the insurer's claim ID and current status, under the same correlation ID as the search. The authority's system acknowledges within 30 seconds and the reviewer compares the adjudication against the provider's original claim and any reprocess Task submitted on /v1/task/submit.

Specification

Chapter NHCX adapter (Optional) 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-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>

Body

typestringRequired

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

One of JWEPayload

payloadstringRequired

Responses

202

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

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​