Skip to main content

Status and search

Search result callback

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 after receiving a /v1/search/submit Task, acknowledging it with 202 within 30 seconds and locating the requested documents. The task type code=poll is the discriminator that tells the recipient this is a search poll and not another Task-driven flow. For a claim document the domain payload is the ClaimResponse for the reference number, with basedOn holding the sender's reference id and about holding the recipient's reference id and the current status. Carry the same x-hcx-correlation_id as the search and a responder status such as response.complete.

### Preconditions

- The inbound search Task was decrypted and its correlation id, status and workflow id captured; the 202 acceptance body was already returned. - The payer is a registered participant with a valid Bearer token and the requester's certificate for encryption. - The response is a JWE whose plaintext carries the ClaimResponse (for claim-document searches) with basedOn and about populated as documented; the loosely typed HcxOnSearchBody requires only a type property. - Protected header echoes the search's x-hcx-correlation_id, carries a fresh api_call_id, an IST timestamp and a responder status.

### Postconditions

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. The requester reads the recipient's reference id and the current status of the response entity from the about element. Nothing about the underlying claim changes; the search is read-only. The endpoint is tagged V1.0 APIs-Provider side because the callback is delivered to the provider side of the exchange, with operationId hcxOnSearchPost.

### Common mistakes

- Returning the search result in the synchronous 202 instead of on this callback. - Minting a new correlation id on the response so the requester cannot match it (NHCX-1010). - Omitting basedOn or about, or swapping them: basedOn carries the sender's id, about the recipient's id and current status. - Sending a Task or bare Bundle where the claim-document search expects the ClaimResponse resource. - Reading the ClaimResponse outcome as approval without checking adjudication; a rejected claim still carries outcome complete. - Missing the 30-second window on the inbound 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)](/docs/nhcx/v1/getting-started/nhcx-adapter) of the NHCX integration specification.

Authorizations

Authorizationbearer tokenRequired

On every NHCX call, the token goes in a header called bearer_auth, with the word Bearer and a space in front. The sources are not unanimous: the authentication page and the FAQ both write the example as Authorization, and the notification endpoint uses Authorization. The safe course, and what the adapter does, is to send both headers with the same value.

Headers

bearer_authstringRequired

It is bearer_auth, not Authorization, on NHCX's own endpoints.

x-hcx-sender_codestringRequired

Your participant code. Mandatory on the envelope.

x-hcx-recipient_codestringRequired

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

x-hcx-api_call_idstringRequired

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

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.

x-hcx-correlation_idstringRequired

The thread. See the rule below. Mandatory on the envelope.

x-hcx-timestampstringRequired

See the format note below. Mandatory on the envelope.

x-hcx-statusstringRequired

Where this message stands. Values below. Mandatory on the envelope.

x-hcx-ben-abha-idstringRequired

The beneficiary's ABHA number. Mandatory on every exchange, including those with no beneficiary in the payload. Mandatory on the envelope.

Body

payloadstring

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.

Callbacks​

  • After this call, ABDM posts Receive search result callback to v1_search_on_submit. Open the callback.