Skip to main content

Adapter

Coverage eligibility check (internal) (adapter)

Internal twin of /v1/coverageeligibility/check with the same JWEPayload body and response set; only the operationId differs.

POST/internal/v1/coverageeligibility/check

### Business purpose

The coverage eligibility service publishes its check operation twice, once at /v1 and once at /internal/v1. Both let a provider validate a beneficiary's coverage with a payer before preauthorisation. The internal path exists in the OpenAPI document as an operationally distinct route for the same business function; the published material does not describe a separate business purpose for it.

### When to use

Documented as the internal variant of the eligibility check (operationId coverageeligibilityCheckPostInternal), served by coverageeligibilityhcxservice and tagged V1.0 APIs-Payer side like its public twin. The same purposes (discovery, validation, auth-requirements, benefits) and the same x-hcx-status request.initiated apply. The OpenAPI specs expose this operation twice, at /v1/... and at /internal/v1/..., with identical descriptions, request bodies and response sets; only the operationId differs (an Internal suffix). The specs do not document what makes the internal variant different beyond that suffix, so treat it as a mirror of the public path and integrate against the public /v1 path unless NHCX onboarding tells you otherwise.

### Preconditions

Identical to the public path: an onboarded provider with a valid Bearer token, the payer certificate fetched and cached, a CoverageEligibilityRequest bundle encrypted with RSA-OAEP-256 and A256GCM, a fresh correlation UUID, the processingID as recipient code, and the full x-hcx-* protected header set. Nothing additional is documented for the internal route.

### Postconditions

Same as /v1/coverageeligibility/check: HTTP 202 Accepted with a StatusSuccessResponse acknowledgement, then asynchronous forwarding to the payer and an answer on the on_check callback (the internal twin /internal/v1/coverageeligibility/on_check exists with the same body). 400, 404 and 500 carry the same schema.

### Common mistakes

- Assuming the internal path has different semantics or a different body; the specs give it the same JWEPayload body and the same responses. - Integrating against the internal path without confirmation from NHCX onboarding, then hitting a 404 on the gateway host; when a path 404s, the endpoint index recommends trying the alternate host and prefix shape. - All the mistakes listed for the public check (202 treated as an answer, wrong recipient code, reused correlation ID, wrong status string) apply unchanged.

### Best practices

- Default to /v1/coverageeligibility/check; use the internal path only where NHCX instructs you to. - Keep one client implementation for both paths, parameterised only on the URL, so header hygiene and correlation handling stay identical. - Log which variant was used with each correlation ID for troubleshooting.

### Related scenario

A hospital integration team exploring the coverageeligibilityhcxservice Swagger sees two check operations. They build one client against /v1/coverageeligibility/check and confirm with NHCX support whether the internal twin is meant for their deployment. In production traffic the eligibility request still starts from get/policies, goes out as a JWE to the check path, receives a 202, and the payer's answer arrives on the on_check callback before the preauth is raised.

### Specification

Chapter [Coverage eligibility request](/docs/nhcx/v1/reference/fhir/coverage-eligibility-request) 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

Same as /v1/coverageeligibility/check: HTTP 202 Accepted with a StatusSuccessResponse acknowledgement, then asynchronous forwarding to the payer and an answer on the on_check callback (the internal twin /internal/v1/coverageeligibility/on_check exists with the same body).