Skip to main content

Status and search

Search submit

Authorised entity such as NHA or IRDAI sends a Task to retrieve claim information for a case; the payer returns the documents on the search callback.

POST/v1/search/submit

### Business purpose

Regulators and scheme authorities need to see what was actually claimed and decided for a given case without being a party to the original exchange. The Search API is that privileged pull path: an authorised entity submits a Task naming the case, and the payer supplies the claim documents. It supports oversight, audit and dispute review, and it lets payers answer such requests through the same encrypted, correlated channel as everything else on NHCX. The documented callers are NHA and IRDAI; a provider integration usually implements only the responding side.

### When to use

Use it when an authorised entity needs the claim documents for a known case number, for example during a regulatory audit or a dispute. It is a pull, not a lifecycle step, and sits outside the workflow-code sequence. The protected header's x-hcx-correlation_id carries the correlation id of the request being queried, and x-hcx-status is request.initiated. The result arrives asynchronously on /v1/search/on_submit with task type code=poll; if the search is for a claim document, the callback payload is the ClaimResponse for the reference number.

### Preconditions

- The caller is an entity authorised to search claim information (the source names NHA and IRDAI) and is registered on NHCX with a valid Bearer token. - Request body is a JWE per RFC-7516 with protocol headers per the ProtocolHeader schema. - Domain payload is an encrypted Task built per the TaskBundle, with the entity being queried referenced in the about element using the sender's reference id. - Protected header carries sender_code, recipient_code, a fresh api_call_id, the correlation id of the request being queried, an IST timestamp and status request.initiated. - HTTP headers Accept, Content-Type and bearer_auth.

### Postconditions

The gateway returns HTTP 202 with a StatusSuccessResponse (timestamp, api_call_id, correlation_id, result with sender_code, recipient_code, entity_type and protocol_status, and error), or 400, 404 or 500 in the same envelope. It forwards the Task to the payer, who responds later on /v1/search/on_submit with the claim document: a ClaimResponse whose basedOn carries the sender's reference id and whose about carries the recipient's reference id and the current status of the response entity. No case state changes; Search only reads.

### Common mistakes

- Using Search as a general status lookup; Status answers where a request is, Search returns documents. - Sending a CommunicationRequest as the domain payload; Search uses a Task (Status is the one that uses CommunicationRequest). - Forgetting the about reference with the sender's reference id, leaving the payer with nothing to search for (PAYR-1102 Invalid search parameter requested). - Minting a new correlation id rather than carrying the one for the request being queried. - Calling it from a participant that is not an authorised entity; the description scopes it explicitly. - Expecting the documents in the synchronous 202.

### Best practices

- Reference the case in Task.about using the sender's own reference id and keep it consistent with the correlation id you carry. - Persist the correlation id so the on_submit result can be matched. - Use fresh api_call_id values, IST timestamps and request.initiated on the outbound header. - Handle 404 as a signal that the correlation id is unknown to the gateway, not as a retry trigger. - Implement v1/error and the on_submit receiver before submitting searches.

### Related scenario

A scheme authority reviewing a grievance about a rejected claim needs the payer's adjudication record. Its integration posts /v1/search/submit with a Task whose about element names the case and whose header carries the claim's correlation id. The gateway acknowledges with 202 and forwards the Task to the payer. The payer's system locates the ClaimResponse for the reference number and returns it on /v1/search/on_submit with basedOn holding the authority's reference and about holding the payer's reference and current status. The authority then compares it with the provider's original /v1/claim/submit bundle.

### 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 a StatusSuccessResponse (timestamp, api_call_id, correlation_id, result with sender_code, recipient_code, entity_type and protocol_status, and error), or 400, 404 or 500 in the same envelope.

Callbacks​

  • After this call, ABDM posts Receive search submit to v1_search_submit. Open the callback.