Skip to main content

Communication

Communication acknowledgement callback

Provider returns the acknowledgement Task bundle for a payer communication, echoing the reason code and correlation id so the payer can close the loop.

POST/v1/communication/on_request

### Business purpose

A payer that has pushed a TAT alert, grievance, wallet update, policy change or document request needs proof that the hospital received it, because the next adjudication step or SLA clock often depends on it. This callback is that proof. The provider posts a bundle of identical structure to the request, with Task.status completed confirming receipt, and the payer's system can then continue, escalate or wait for the documents. It keeps the entire exchange inside NHCX, auditable by correlation id, rather than in phone calls and email.

### When to use

Call it after receiving and persisting a /v1/communication/request bundle. The gateway has already been given a 202 within 30 seconds; this call is the separate business acknowledgement. Echo the same Task.reasonCode (tatquery, grievance, walletupdate, policychange, additionalinfo or the arbitration code) and Task.code poll, keep Task.intent proposal, and use the same x-hcx-correlation_id as the incoming request. x-hcx-workflow_id is validated at the gateway for the acknowledgement as well as the request. Responder status values are response.complete, response.partial or response.error.

### Preconditions

- The inbound JWE was extracted from the payload field, validated as a five-part string, decrypted with your PKCS8 private key and its protected header parsed for correlation id, status and workflow id. - The provider is a registered NHCX participant and holds a valid Bearer token. - The payer's certificate is available to encrypt the acknowledgement bundle. - The acknowledgement bundle mirrors the request (Task completed, intent proposal, code poll, reasonCode echoed) with the provider Organization listed before the payer Organization and Bundle.timestamp updated to the acknowledgement time. - Protected header reuses the request's x-hcx-correlation_id, carries a fresh x-hcx-api_call_id and a responder x-hcx-status.

### Postconditions

The gateway returns HTTP 202 with the StatusSuccessResponse envelope (timestamp, api_call_id, correlation_id, result, error) and forwards the bundle to the payer. The payer's system can link the acknowledgement to the original notification by correlation id and by the shared claim or preauth reference in Task.identifier and Communication.id. The underlying issue is not resolved by this call: a TAT breach or grievance may still be open, and any documents requested via additionalinfo are supplied through the relevant preauth or claim resubmission path. Validation failures come back as 400, unknown resources as 404, downstream faults as 500.

### Common mistakes

- Minting a new correlation id on the acknowledgement instead of echoing the request's; the payer can no longer link it (NHCX-1010 No Data with given Correlation id for call back request). - Sending the acknowledgement before, or instead of, the synchronous 202; the gateway treats a missing or malformed 202 as an error and retries up to five times. - Holding the socket open while a human reviews the message, breaching the 30-second window. - Closing the hospital case on acknowledgement because Communication.status reads completed. - Deriving sender and receiver roles from Organization identifier types, which are swapped in the sandbox sample. - Building the reason-code switch on a single spelling of the arbitration code.

### Best practices

- Acknowledge first, process later: return 202 with the acceptance body, queue the bundle, then build and post the on_request acknowledgement asynchronously. - Switch on Task.reasonCode.code to route: tatquery to the claims desk, walletupdate to the benefit cache, policychange to package rate tables. - Be idempotent on x-hcx-correlation_id; the same communication may be redelivered. - Validate x-hcx-workflow_id against the workflow of the associated claim or preauth before acting. - Use IST timestamps and a fresh x-hcx-api_call_id on the acknowledgement call. - Log the reason code, category, priority and correlation id for the audit trail.

### Related scenario

A district hospital receives a communication from the scheme payer on its registered callback: reasonCode additionalinfo, category instruction, asking for an updated discharge summary on a claim submitted last week. The endpoint returns 202 immediately and queues the bundle. The claims desk is notified, and the integration posts the acknowledgement Task on /v1/communication/on_request with the same correlation id and reasonCode. The desk then attaches the discharge summary through the claim's resubmission path, and the final adjudication arrives later on /v1/claim/on_submit, possibly followed by a payment notice on /v1/paymentnotice/request.

### Specification

Chapter [Communication](/docs/nhcx/v1/reference/fhir/communication) 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-workflow_idstring

Which step, or which case. See the two readings below. Optional 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 (timestamp, api_call_id, correlation_id, result, error) and forwards the bundle to the payer.

Callbacks​

  • After this call, ABDM posts Receive communication acknowledgement callback to v1_communication_on_request. Open the callback.