Skip to main content

Adapter

Communication request (internal variant) (adapter)

Internal twin of /v1/communication/request: same JWEPayload body, description and 202 envelope, operationId communicationRequestPostInternal.

POST/internal/v1/communication/request

### Business purpose

Six NHCX services expose each operation twice, once at /v1/... and once at /internal/v1/..., with identical descriptions and request bodies and only the operationId suffix differing. This entry is the internal twin of the payer-initiated communication request: the channel through which a payer pushes TAT alerts, grievances, wallet or policy updates and additional-information requests to a provider. It exists so the exchange can route the same operation over an internal path; the specifications do not document any further difference from the public endpoint.

### When to use

The published OpenAPI documents give this path the same semantics as /v1/communication/request: a payer submits a Task plus Communication bundle for a provider during the claim lifecycle, identified by Task.reasonCode (tatquery, grievance, walletupdate, policychange, additionalinfo, claim arbitration). The specs do not state when an integrator should prefer the internal path over the public one, so integrators should code against /v1/communication/request unless onboarding instructions direct otherwise. Header rules are unchanged: request.initiated status and a workflow id validated against the associated case.

### Preconditions

- Identical to the public endpoint: registered sender and recipient, valid Bearer token, recipient certificate for JWE encryption (RSA-OAEP-256, A256GCM). - Request body is a JWEPayload, { "payload": "<compact JWE>" }, whose plaintext is the Task plus Communication collection Bundle. - Protected header carries sender_code, recipient_code, api_call_id, correlation_id, workflow_id, timestamp in IST and status request.initiated. - Whether the internal prefix is reachable from a participant's network is not documented; confirm with the environment index and your onboarding contact.

### Postconditions

Returns the same response set as the public endpoint: 202 Accepted with a StatusSuccessResponse (timestamp, api_call_id, correlation_id, result, error), or 400 Request Validation failed, 404 Requested resource was not found and 500 Downstream systems down/unhandled exceptions in the same envelope. The bundle is forwarded to the provider's registered callback, which must acknowledge with 202 within 30 seconds and then answer on the communication on_request path under the same correlation id. No additional state change is documented for the internal variant.

### Common mistakes

- Assuming the internal path behaves differently or bypasses header validation; the specs describe it as identical apart from the operationId. - Hard-coding the internal prefix in a participant integration without confirmation that it is the route you were onboarded to. - The same envelope errors as the public path: wrong status spelling (NHCX-1011), invalid header (NHCX-1005), duplicate correlation id (NHCX-1006), invalid workflow (PAYR-1003). - Mixing the hcxsbx.abdm.gov.in/<service> spec host and the apisbx.abdm.gov.in/pmjay/sbxhcx gateway base; a 404 is the first sign.

### Best practices

- Treat this path exactly as /v1/communication/request in your client: same bundle builder, same header hygiene, same correlation-id persistence. - Keep the path prefix configurable so you can switch between public and internal forms without a code change. - Use fresh UUIDs for api_call_id per call and correlation_id per cycle; use IST timestamps. - Implement v1/error and idempotent callback handling regardless of which path you post to.

### Related scenario

An insurer's integration team exploring the communicationhcxservice Swagger on the sandbox host sees both communicationRequestPost and communicationRequestPostInternal listed with the same description. They wire their TAT-alert sender to the public /v1/communication/request path as documented in the handbook, keep the internal variant as a configurable alternative, and confirm with NHCX onboarding which form their gateway route expects. The rest of the flow is unchanged: 202 acknowledgement, provider callback within 30 seconds, and the acknowledgement Task on the on_request path.

### 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

200

Returns the same response set as the public endpoint: 202 Accepted with a StatusSuccessResponse (timestamp, api_call_id, correlation_id, result, error), or 400 Request Validation failed, 404 Requested resource was not found and 500 Downstream systems down/unhandled exceptions in the same envelope.