Skip to main content

Provider: acknowledge the communication

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

The provider calls it to acknowledge a /v1/communication/request. It comes after the quick 202 reply and reuses the request's correlation ID and reason.

Preconditions

  • You decrypted the incoming request and answered it 202 within 30 seconds.
  • A valid access token and the payer's certificate.
  • The acknowledgement mirrors the request and reuses its x-hcx-correlation_ID.

Postconditions

NHCX answers 202 and forwards the acknowledgement to the payer. It only confirms receipt, so the issue itself may still be open.

Common mistakes

  • Using a new correlation ID, so the payer cannot link the acknowledgement.
  • Keeping the connection open while someone reads the message, missing the 30-second limit.
  • Closing the hospital case because the Communication says completed.

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 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 <provider participant code>

x-hcx-recipient_codestringRequired

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

Example <payer 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-workflow_idstring

Which step, or which case. The workflow code explains both readings. Optional on the envelope.

Example 15

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 (timestamp, api_call_id, correlation_id, result, error) and forwards the bundle to the payer.

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​