Skip to main content

Provider: submit a pre-authorisation

Provider submits, resubmits, enhances or answers a query on a pre-authorisation Claim bundle (Claim.use preauthorization); NHCX routes it to the payer.

POST/v1/preauth/submit

Business purpose

Pre-authorisation is the provider's formal request for the payer's approval to deliver a specific treatment to a covered beneficiary. An approved preAuthRef is the payer's binding commitment to reimburse the approved amount and is required before the final claim can proceed through NHCX. Settling the money question before the patient enters theatre protects the hospital from unpaid treatment, gives the payer control over admissibility, and gives the patient certainty about cashless cover.

When to use

Use it to ask the payer to approve a treatment before it starts. The same call also sends a resubmission, an enhancement or an answer to a payer query: the workflow code in the header says which.

Preconditions

  • You have a valid access token and the payer's certificate.
  • Coverage is confirmed and the documents the payer asks for are ready.
  • The bundle is an FHIR Claim with use set to preauthorization, encrypted for the payer.

Postconditions

  • NHCX answers 202 at once. That only means the message was accepted, not approved.
  • The payer's decision arrives later on /v1/preauth/on_submit.

Common mistakes

  • Sending to the insurer's code instead of the claims processor's.
  • Treating the 202 as an approval.
  • Reusing a correlation ID after a failed request.

Best practices

  • Build one ClaimBundle and switch Claim.use between preauthorization and claim; keep careTeamSequence, diagnosisSequence, procedureSequence and informationSequence internally consistent.
  • Always send both x-hcx-workflow_ID and x-hcx-use_case, and persist them with the correlation ID and the case number.
  • Attach every document the auth-requirements response listed (MAND codes) before submitting; the document list is per package, not static.
  • Raise enhancements while the patient is admitted, not retrospectively at discharge (PAYR-1018 time limit expired).
  • Persist preAuthRef from an approved or partially approved response; it is required at final claim.
  • Implement v1/error and /v1/status so a preauth that never reached the payer is visible at the desk.

Related scenario

After the eligibility callback confirms cover for corneal grafting (SE012A) and lists the required documents, the hospital builds a Claim bundle with use preauthorization, ICD-10 H18.6, a total of 13700 INR and the investigation and consent attachments, and posts it to /v1/preauth/submit under workflow 12 with use_case New. NHCX returns 202. The payer queries under 24 asking for detailed ICPs; the hospital answers on the same endpoint under 19 with the same correlation ID. Approval arrives under 21 with preAuthRef PREAUTH-HP-2026-78901. Two days later the surgeon needs a higher bed category, so the hospital posts an enhancement under 13 with use_case Enhancement, and after discharge it moves to /v1/claim/submit.

Specification

Chapter Preauthorisation request of the NHCX integration specification.

Also sent as pre-authorisation enhancement

The same address, with other headers and body.

Provider asks for more against an approved pre-authorisation, a longer stay or an added package, on the same endpoint and case number as the first request, under workflow 13 with x-hcx-use_case Enhancement.

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 12

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 request.initiated

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>

x-hcx-use_casestring

Values differ by exchange. Domain headers lists them. Optional on the envelope.

Example New

Body

payloadstring

Responses

202

NHCX returns HTTP 202 Accepted with a StatusSuccessResponse acknowledgement (entity_type preauth, protocol_status request.queued or request.dispatched).

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​