Skip to main content

Status and search

Status check

Sender asks NHCX where its own in-flight request stands; the gateway answers request.queued or request.dispatched, and only dispatched yields a callback.

POST/v1/status

### Business purpose

Asynchronous exchanges lose messages, stall in queues and outlive the shift of the desk operator who started them. The Status API exists so the original sender can find out which side of the exchange is holding a request without resubmitting it and creating a duplicate. It answers the hospital desk's most common question, where is my preauth, by telling it whether the gateway has forwarded the request to the payer at all. Providers, payers and TPAs all benefit because it separates gateway delay from payer delay before anyone escalates.

### When to use

Call it after a submission whose callback has not arrived within your operational tolerance, for example a preauth (workflow 12) or claim (workflow 15) still awaiting its on_submit. It is only for requests you originated; x-hcx-correlation_id carries the x-hcx-api_call_id of the request being checked (the Status sheet: "same as API caller ID of the request that requires a status check"). Send x-hcx-status request.initiated. x-hcx-workflow_id and x-hcx-use_case (New, Enhancement or Resubmit) are optional on this call; x-hcx-ben-abha-id is mandatory. If the reply is request.queued, the payer has never seen the request and no callback will come; if request.dispatched, the payer holds it and will answer on the status callback.

### Preconditions

- You are the original sender of the request being queried and have its api_call_id persisted. - Valid Bearer token; the request body is a JWE per RFC-7516 like every protocol API. - The payload inside the JWE is an empty string: no bundle, no Task, no resource. The Status sheet of the requests-and-responses workbook says "Payload should be empty string". The sandbox exit checklists word it as the "encrypted payload of request for which the status is seeking for" and describe no bundle for it. - Protected header with sender_code, recipient_code, a fresh api_call_id, the original request's api_call_id as correlation_id, an IST timestamp and status request.initiated. - HTTP headers Accept, Content-Type and bearer_auth.

### Postconditions

The gateway validates the request and returns the protocol status synchronously in the HTTP response: HTTP 202 with a StatusSuccessResponse whose result carries sender_code, recipient_code, entity_type and protocol_status of request.queued or request.dispatched. On request.queued nothing further happens; the original request is still inside NHCX. On request.dispatched the gateway forwards the status request to the recipient, who responds asynchronously on the status callback (named /v1/on_status and /hcx/on_status in different sentences of the source). A 404 against a correlation id you believe you sent strongly suggests the original submission never landed; NHCX-1012 reports no records for the api caller id.

### Common mistakes

- Minting a fresh correlation id for the status call itself instead of setting it to the original request's api_call_id; this is the single most common status-integration error and yields NHCX-1012 or 404. - Polling in a tight loop; a request.queued answer means the gateway is still working and there is no callback for that branch. - Resubmitting the original request after a request.queued response, which duplicates it (NHCX-1006). - Reading the Appendix C lifecycle statuses (request.acknowledged, request.queried, request.complete) as Status API outcomes; the API returns only the two gateway values. - Querying a correlation id after NHCX deleted it following five failed deliveries; it is gone. - Querying a request another participant originated; senders may only query their own.

### Best practices

- Persist the correlation id against the case record before every submission so a status check is always possible. - Use a bounded, spaced schedule tied to the correlation id, then escalate; do not poll aggressively. - Branch on protocol_status: wait on request.queued, expect the status callback on request.dispatched. - Use a fresh x-hcx-api_call_id per status call and IST timestamps. - Treat Status as transport position only; the decision lives in the original on_ callback or a Search for the claim document. - Implement the status callback and v1/error so both branches of the answer have somewhere to land.

### Related scenario

A hospital's TPA desk submitted a preauth on /v1/preauth/submit at 09:00 and by 13:00 nothing has arrived on /v1/preauth/on_submit. Rather than resubmit, the integration posts /v1/status with the preauth's correlation id. The synchronous reply shows protocol_status request.dispatched, so the request is with the payer, not stuck at the gateway; the desk stops worrying about a lost message and waits for the status callback and the eventual preauth decision. Had the reply been request.queued, the desk would have waited on the gateway and, if the delay persisted, escalated to NHCX support with the correlation id.

### 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 validates the request and returns the protocol status synchronously in the HTTP response: HTTP 202 with a StatusSuccessResponse whose result carries sender_code, recipient_code, entity_type and protocol_status of request.queued or request.dispatched.

Callbacks​